isp_mem_strings.spin2

'' =================================================================================================
''
''   File....... isp_mem_strings.spin2
''   Purpose.... provide sprintf() c-like functions for Spin2 developers
''   Authors.... Stephen M. Moraco
''                (Highly leveraged from jm_serial.spin2 by Jon McPhalen)
''   E-mail..... stephen@ironsheep.biz
''   Started.... Feb 2022
''   Updated.... 4 Feb 2022
''
'' =================================================================================================

OBJ { Objects Used by this Object }

    nstr        : "jm_nstrings"                                 ' number-to-string

PUB null()

  '' This is not a top level object

CON { pst formatting }

  HOME     =  1
  CRSR_XY  =  2
  CRSR_LF  =  3
  CRSR_RT  =  4
  CRSR_UP  =  5
  CRSR_DN  =  6
  BELL     =  7
  BKSP     =  8
  TAB      =  9
  LF       = 10
  CLR_EOL  = 11
  CLR_DN   = 12
  CR       = 13
  CRSR_X   = 14
  CRSR_Y   = 15
  CLS      = 16

CON { formatted strings }

{{

 -------------------------------------------------------------------------------------------------
    Escaped characters

      \\          backslash char
      \%          percent char
      \q          double quote
      \b          backspace
      \t          tab (horizontal)
      \n          new line (vertical tab)
      \r          carriage return
      \nnn        arbitrary ASCII value (nnn is decimal)

    Formatted arguments

      %w.pf       print argument as decimal width decimal point
      %[w[.p]]d   print argument as decimal
      %[w[.p]]x   print argument as hex
      %[w[.p]]o   print argument as octal
      %[w[.p]]q   print argument as quarternary
      %[w[.p]]b   print argument as binary
      %[w]s       print argument as string
      %[w]c       print argument as character (

                  -- w is field width
                     * positive w causes right alignment in field
                     * negative w causes left alignment in field
                  -- %ws aligns s in field (may truncate)
                  -- %wc prints w copies of c
                  -- p is precision characters
                     * number of characters to use, aligned in field
                       -- prepends 0 if needed to match p
                       -- for %w.pf, p is number of digits after decimal point
 -------------------------------------------------------------------------------------------------

}}

PUB sFormatStr0(pUserBuff, p_str) : nPlaced
'' Format string w/o-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, 0)


PUB sFormatStr1(pUserBuff, p_str, arg1): nPlaced
'' Format string and 1-arg into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr2(pUserBuff, p_str, arg1, arg2): nPlaced
'' Format string and 2-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr3(pUserBuff, p_str, arg1, arg2, arg3): nPlaced
'' Format string and 3-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr4(pUserBuff, p_str, arg1, arg2, arg3, arg4): nPlaced
'' Format string and 4-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr5(pUserBuff, p_str, arg1, arg2, arg3, arg4, arg5): nPlaced
'' Format string and 5-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr6(pUserBuff, p_str, arg1, arg2, arg3, arg4, arg5, arg6): nPlaced
'' Format string and 6-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr7(pUserBuff, p_str, arg1, arg2, arg3, arg4, arg5, arg6, arg7): nPlaced
'' Format string and 7-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)

PUB sFormatStr8(pUserBuff, p_str, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8): nPlaced
'' Format string and 8-args into {pUserBuff} with formatting characters, zero terminated
''  Returns count of characters placed into the users buffer (excl zero term.)
    nPlaced := sFormat(pUserBuff, p_str, @arg1)


PUB sFormat(pUserBuff, p_str, p_args) : nPlaced | idx, c, asc, fld, digits, pBffr
'' Format string with escape sequences and embedded values to {pOutBuf}
'' -- {pUserBuff} is a pointer to the users buffer to receive the formatted string
'' -- {p_str} is a pointer to the format control string
'' -- {p_args} is pointer to array of longs that hold field values
''    * field values can be numbers, characters, or pointers to strings
  'debug("sfmt: fstr(", udec_(strsize(p_str)), ")=[", zstr_(p_str), "]")

  idx := 0                                                     ' value index
  pBffr := pUserBuff
  repeat
    c := byte[p_str++]
    if (c == 0)
      quit

    elseif (c == "\")
      c := byte[p_str++]
      if (c == "\")
        sTx("\", pBffr++)
      elseif (c == "%")
        sTx("%", pBffr++)
      elseif (c == "q")
        sTx(34, pBffr++)
      elseif (c == "b")
        sTx(BKSP, pBffr++)
      elseif (c == "t")
        sTx(TAB, pBffr++)
      elseif (c == "n")
        sTx(LF, pBffr++)
      elseif (c == "r")
        sTx(CR, pBffr++)
      elseif ((c >= "0") and (c <= "9"))
        --p_str
        p_str, asc, _ := get_nargs(p_str)
        if ((asc >= 0) and (asc <= 255))
          sTx(asc, pBffr++)

    elseif (c == "%")
      p_str, fld, digits := get_nargs(p_str)
      c := byte[p_str++]
      if (c == "f")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 99, digits, fld, " "), pBffr)
      elseif (c == "d")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 10, digits, fld, " "), pBffr)
      elseif (c == "x")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 16, digits, fld, " "), pBffr)
      elseif (c == "o")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 08, digits, fld, " "), pBffr)
      elseif (c == "q")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 04, digits, fld, " "), pBffr)
      elseif (c == "b")
        pBffr := sStr(nstr.fmt_number(long[p_args][idx++], 02, digits, fld, " "), pBffr)
      elseif (c == "s")
        pBffr := sStr(nstr.padstr(long[p_args][idx++], fld, " "), pBffr)
      elseif (c == "c")
        pBffr := sTxn(long[p_args][idx++], (abs fld) #> 1, pBffr)

    else
      sTx(c, pBffr++)

  byte[pBffr] := 0  ' place terminator
  nPlaced := strsize(pUserBuff)
  'debug("sfmt: ", UHEX_BYTE_ARRAY_(pUserBuff, 48))
  'debug("sfmt: str(", udec_(nPlaced), ")=[", zstr_(pUserBuff), "]")

CON { --- Internal Methods --- }

PRI sTx(nChr, pOutBuf)
' write char to bfr
    byte[pOutBuf] := nChr

PRI sTxn(nChr, nCount, pOutBuf) : pBufNext
' Emit byte n times
    repeat nCount
        sTx(nChr, pOutBuf++)

    pBufNext := pOutBuf

PRI sStr(pStr, pOutBuf) : pBufNext
' write char to bfr
    repeat (strsize(pStr))
        sTx(byte[pStr++], pOutBuf++)

    pBufNext := pOutBuf

PRI get_nargs(p_str) : p_str1, val1, val2 | c, sign
' Parse one or two numbers from string in n, -n, n.n, or -n.n format
' -- dpoint separates values
' -- only first # may be negative
' -- returns pointer to 1st char after value(s)

  c := byte[p_str]                                              ' check for negative on first value
  if (c == "-")
    sign := -1
    ++p_str
  else
    sign := 0

  repeat                                                        ' get first value
    c := byte[p_str++]
    if ((c >= "0") and (c <= "9"))
      val1 := (val1 * 10) + (c - "0")
    else
      if (sign)
        val1 := -val1
      quit

  if (c == ".")                                                 ' if dpoint
    repeat                                                      '  get second value
      c := byte[p_str++]
      if ((c >= "0") and (c <= "9"))
        val2 := (val2 * 10) + (c - "0")
      else
        quit

  p_str1 := p_str - 1                                           ' back up to non-digit


CON { license }
{{

 -------------------------------------------------------------------------------------------------
  MIT License

  Copyright (c) 2022 Iron Sheep Productions, LLC

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
 =================================================================================================
}}