Next: , Previous: , Up: Other I/O   [Contents][Index]

5.19.5 String words

The following string library stores strings in ordinary variables, which then contain a pointer to a cell-counted string allocated from the heap. The string library originates from bigFORTH.

delete ( buffer size u –  ) gforth-string “delete”

deletes the first u bytes from a buffer and fills the rest at the end with blanks.

insert ( string length buffer size –  ) gforth-string “insert”

inserts a string at the front of a buffer. The remaining bytes are moved on.

$! ( addr1 u $addr –  ) gforth-string “string-store”

stores a newly allocated string buffer at an address, frees the previous buffer if necessary.

$@ ( $addr – addr2 u  ) gforth-string “string-fetch”

returns the stored string.

$@len ( $addr – u  ) gforth-string “string-fetch-len”

returns the length of the stored string.

$!len ( u $addr –  ) gforth-string “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  ) unknown “$+!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-string “string-del”

deletes u bytes from a string with offset off.

$ins ( addr1 u $addr off –  ) gforth-string “string-ins”

inserts a string at offset off.

$+! ( addr1 u $addr –  ) gforth-string “string-plus-store”

appends a string to another.

c$+! ( char $addr –  ) gforth-string “c-string-plus-store”

append a character to a string.

$free ( $addr –  ) gforth-string “string-free”

free the string pointed to by addr, and set addr to 0

$init ( $addr –  ) unknown “$init”

store an empty string there, regardless of what was in before

$split ( addr u char – addr1 u1 addr2 u2  ) gforth-string “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-string “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 –  ) unknown “$over”

overwrite string at offset off with addr u

$exec ( xt addr –  ) unknown “$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  ) unknown “$tmp”

generate a temporary string from the output of a word

$. ( addr –  ) unknown “$.”

print a string, shortcut

$slurp ( fid addr –  ) unknown “$slurp”

slurp a file fid into a string addr2

$slurp-file ( addr1 u1 addr2 –  ) unknown “$slurp-file”

slurp a named file addr1 u1 into a string addr2

$[] ( u $[]addr – addr’  ) unknown “$[]”

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 –  ) unknown “$[]map”

execute xt for all elements of the string array addr. xt is ( addr u – ), getting one string at a time

$[]slurp ( fid addr –  ) unknown “$[]slurp”

slurp a file fid line by line into a string array addr

$[]slurp-file ( addr u $addr –  ) unknown “$[]slurp-file”

slurp a named file addr u line by line into a string array $addr

$[]. ( addr –  ) unknown “$[].”

print all array entries

$[]free ( addr –  ) unknown “$[]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 –  ) unknown “$save”

push string to dictionary for savesys

$[]save ( addr –  ) unknown “$[]save”

push string array to dictionary for savesys

$boot ( $addr –  ) unknown “$boot”

take string from dictionary to allocated memory. clean dictionary afterwards.

$[]boot ( addr –  ) unknown “$[]boot”

take string array from dictionary to allocated memory

$saved ( addr –  ) unknown “$saved”
$[]saved ( addr –  ) unknown “$[]saved”
$Variable ( ) unknown “$Variable”

A string variable which is preserved across savesystem

$[]Variable ( ) unknown “$[]Variable”

A string variable which is preserved across savesystem

Next: Terminal output, Previous: Displaying characters and strings, Up: Other I/O   [Contents][Index]