The following string library stores strings in ordinary cell-size variables (string handles). These handles contain a pointer to a cell-counted string allocated from the heap. The string library originates from bigFORTH.
Because there is only one permanent reference to the contents (the one
in the handle), the string can be relocated or deleted without
worrying about dangling references; this requires that the programmer
uses references produced by, e.g., $@ only for temporary
purposes, i.e., these references are not passed out, e.g., as return
values or stored in global memory, and words that may change the
handle are not called while these references exist.
This library is complemented by the cell-pair representation: You use the $tring words for variable strings which are cumbersome with the c-addr u representation. You use the cell-pair representation for processing (e.g., inspecting) strings while they do not change.
$! ( addr1 u $addr – ) gforth-0.7 “string-store”
stores a newly allocated string buffer at an address, frees the previous buffer if necessary.
$@ ( $addr – addr2 u ) gforth-0.7 “string-fetch”
returns the stored string.
$@len ( $addr – u ) gforth-0.7 “string-fetch-len”
returns the length of the stored string.
$!len ( u $addr – ) gforth-0.7 “string-store-len”
changes the length of the stored string. Therefore we must change the memory area and adjust address and count cell as well.
$+!len ( u $addr – addr ) gforth-1.0 “string-plus-store-len”
make room for u bytes at the end of the memory area referenced by $addr; addr is the address of the first of these bytes.
$del ( $addr off u – ) gforth-0.7 “string-del”
Deletes u bytes at offset off bytes in the string $addr.
$ins ( addr1 u $addr off – ) gforth-0.7 “string-ins”
Inserts string addr1 u at offset off bytes in the string $addr.
$+! ( addr1 u $addr – ) gforth-0.7 “string-plus-store”
appends a string to another.
c$+! ( char $addr – ) gforth-1.0 “c-string-plus-store”
append a character to a string.
$free ( $addr – ) gforth-1.0 “string-free”
free the string pointed to by addr, and set addr to 0
$init ( $addr – ) gforth-1.0 “string-init”
store an empty string there, regardless of what was in before
$iter ( .. $addr char xt – .. ) gforth-0.7 “string-iter”
Splits the string in $addr using char as separator.
For each part, its descriptor c-addr u is pushed and xt
( ... c-addr u -- ... ) is executed.
$over ( addr u $addr off – ) gforth-1.0 “string-over”
Overwrite u bytes at offset off bytes in the string $addr with the string at addr u.
$exec ( xt $addr – ) gforth-1.0 “string-exec”
execute xt while the standard output (TYPE, EMIT, and everything that uses them) is appended to the string in $addr.
$. ( $addr – ) gforth-1.0 “string-dot”
print a string, shortcut
$slurp ( fid $addr – ) gforth-1.0 “string-slurp”
Read the file fid until the end (without closing it) and put the read data into the string at $addr.
$slurp-file ( c-addr u $addr – ) gforth-1.0 “string-slurp-file”
Put all the data in the file named c-addr u into the string at $addr.
$+slurp ( fid $addr – ) gforth-1.0 “string-plus-slurp”
Read the file fid until the end (without closing it) and append the read data to the string at $addr.
$+slurp-file ( c-addr u $addr – ) gforth-1.0 “string-plus+slurp-file”
Append all the data in the file named c-addr u to the string at $addr.
$[] ( u $[]addr – addr’ ) gforth-1.0 “string-array”
Addr’ is the address of the uth element of the string array $[]addr. The array is resized if needed.
$[]! ( c-addr u n $[]addr – ) gforth-1.0 “string-array-store”
Store string c-addr y into the string array $[]addr at index n. The array is resized if needed.
$[]+! ( c-addr u n $[]addr – ) gforth-1.0 “string-array-plus-store”
Append the string c-addr u to the string at index n.
The array is resized if needed. Don’t confuse this with
$+[]!.
$+[]! ( c-addr u $[]addr – ) gforth-1.0 “string-append-array”
Store the string c-addr u as the new last element of string array $[]addr. The array is resized if needed.
$[]@ ( n $[]addr – addr u ) gforth-1.0 “string-array-fetch”
fetch a string from array index n — return the zero string if empty, and don’t accidentally grow the array.
$[]# ( $[]addr – len ) gforth-1.0 “string-array-num”
return the number of elements in an array
$[]map ( $[]addr xt – ) gforth-1.0 “string-array-map”
execute xt for all elements of the string array $[]addr. xt is ( addr u – ), getting one string at a time
$[]slurp ( fid $[]addr – ) gforth-1.0 “string-array-slurp”
slurp a file fid line by line into a string array $[]addr
$[]slurp-file ( addr u $[]addr – ) gforth-1.0 “string-array-slurp-file”
slurp a named file addr u line by line into a string array $[]addr
$[]. ( $[]addr – ) gforth-1.0 “string-array-dot”
print all array entries
$[]free ( $[]addr – ) gforth-1.0 “string-array-free”
$[]addr contains the address of a cell-counted string that contains the addresses of a number of cell-counted strings; $[]free frees these strings, frees the array, and sets addr to 0
$Variable ( "name" – ) gforth-1.0 “string-variable”
Defines a string variable whose content is preserved across savesystem
$[]Variable ( "name" – ) gforth-1.0 “string-array-variable”
Defines a string array variable whose content is preserved across savesystem