Next: , Previous: , Up: Strings and Characters   [Contents][Index]

5.8.5 $tring words

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

$split ( addr u char – addr1 u1 addr2 u2  ) gforth-0.7 “string-split”

divides a string into two, with one char as separator (e.g. ’?’ for arguments in an HTML query)

$iter ( .. $addr char xt – ..  ) gforth-0.7 “string-iter”

takes a string apart piece for piece, also with a character as separator. For each part a passed token will be called. With this you can take apart arguments – separated with ’&’ – at ease.

$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 slurp a file fid into a string addr2, append mode

$. ( addr –  ) gforth-1.0 “string-dot”

print a string, shortcut

$slurp ( fid addr –  ) gforth-1.0 “string-slurp”

slurp a file fid into a string addr2

$slurp-file ( addr1 u1 addr2 –  ) gforth-1.0 “string-slurp-file”

slurp a named file addr1 u1 into a string addr2

$[] ( u $[]addr – addr’  ) gforth-1.0 “string-array”

index into the string array and return the address at index u The array will be resized as needed

$[]! ( addr u n $[]addr –  ) gforth-1.0 “string-array-store”

store a string into an array at index n

$[]+! ( addr u n $[]addr –  ) gforth-1.0 “string-array-plus-store”

add a string to the string at index n

$[]@ ( 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

Next: Counted string words, Previous: String words, Up: Strings and Characters   [Contents][Index]