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 from a string with offset off.
$ins ( addr1 u $addr off – ) gforth-0.7 “string-ins”
inserts a string at offset off.
$+! ( 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 string at offset off with 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 variable addr.
$tmp ( xt – addr u ) gforth-1.0 “string-t-m-p”
generate a temporary string from the output of a word
$. ( 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
$save ( $addr – ) gforth-1.0 “string-save”
push string to dictionary for savesys
$[]save ( addr – ) gforth-1.0 “string-array-save”
push string array to dictionary for savesys
$boot ( $addr – ) gforth-1.0 “string-boot”
Take string from dictionary to allocated memory. Clean dictionary afterwards.
$[]boot ( addr – ) gforth-1.0 “string-array-boot”
take string array from dictionary to allocated memory
$saved ( addr – ) gforth-1.0 “string-saved”
mark an address as booted/saved
$[]saved ( addr – ) gforth-1.0 “string-array-saved”
mark an address as booted/saved
$Variable ( – ) gforth-1.0 “string-variable”
A string variable which is preserved across savesystem
$[]Variable ( – ) gforth-1.0 “string-array-variable”
A string variable which is preserved across savesystem