Next: , Previous: Displaying characters and strings, Up: Other I/O


5.19.5 String words

The following string library stores strings in ordinary variables, which then contain a pointer to a counted string stored allocated from the heap. Instead of a count byte, there's a whole count cell, sufficient for all normal use. 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 addr2 –         gforth-string       “string-store”

stores a string at an address, If there was a string there already, that string will be lost.

$@       addr1 – 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.

$del       addr off u –         gforth-string       “string-del”

deletes u bytes from a string with offset off.

$ins       addr1 u addr2 off –         gforth-string       “string-ins”

inserts a string at offset off.

$+!       addr1 u addr2 –         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.

$off       addr –         gforth-string       “string-off”

releases a string.

$init       addr –         gforth-string       “string-init”

initializes a string to empty (doesn't look at what was there 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 redirected 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

$[]       n addr – addr'         unknown       “$[]”

index into the string array and return the address at index n

$[]!       addr u n $[]addr –         unknown       “$[]!”

store a string into an array at index n

$[]+!       addr u n $[]addr –         unknown       “$[]+!”

add a string to the string at addr n

$[]@       n $[]addr – addr u         unknown       “$[]´'

fetch a string from array index n – return the zero string if empty

$[]#       addr – len         unknown       “$[]#”

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

$[]off       addr –         unknown       “$[]off”

release a string array