Dynamic-Strings Words

Leave the largest mstring count provided by the implementation. Canonical values are 255 and 2³²-1. "max-m-count"

Leave the size of the mstring count field provided by the implementation in ANS Forth character units, nominally bytes. Canonical sizes are one character and one cell. "slash-m-count"

Push the MSA of a fixed external representation of the empty string onto the string stack. "empty-string"

Push onto the string stack the MSA of a fixed external string whose body is the C newline character, ASCII 10. "newline-string"

A Forth variable that holds the address of the current string space, where all dynamic string operations take place. "d-strings"

Several of the words in this section violate the normal expectation that only ANS Forth strings should appear on the data stack.

(M!) is the same as Wil Baden's PLACE, except it assumes the buffer address msa to be aligned, and stores s as a measured string, zero-filled to trailing alignment. As with PLACE, it is assumed that the mstring copy does not clobber the old string, and there is no check for room starting at msa. "parens-m-store"

Parse the parse area up to the first occurrence of char, which is parsed away. If executing in compilation mode, append run-time semantics to the current definition that leaves the ANS Forth string representation on the stack. In interpretation mode, leave the ANS Forth string representation for a stored mstring copy, which may be transient in the style of S". In either mode, the stored string is a mstring. "parse-to-s"

Allot room and store the ANS Forth string into aligned data space as a measured string, leaving data space aligned; and leave the length and new body address. It is assumed that len is unsigned. An error is thrown if there is an mcount overflow. "m-comma-s"

Assume the input ANS Forth string to be represented as a measured string. Leave its MSA. "minus-m-count"

Convert the input measured string to its ANS Forth string representation. "m-count"

Leave the length of the input measured string. "m-count-fetch"

Store len in the measured string count field at msa. "m-count-store"

A synonym for "(" including any immediacy, and allowing multiple lines before the terminating right parenthesis, as specified for "(" in the File-Access word set. "paren-string-colon"

Leave the number of address units available for dynamic strings and string stack entries in the string buffer. "string-unused"

Leave the size in address units allocated for the current string buffer. "slash-string-buf"

Allocate and initialize a string space with size address units available for the string buffer including the string stack, and with a string frame stack for frame description entries holding up to #frames. The size is rounded up to address alignment, and the buffer begins and ends with address alignment. Return addr, the address of the string space. The standard word free with addr as input can be used to release the space. "make-string-space"

Leave the number of string frames allowed on the string frame stack for the current string space. "max-number-string-frames"

Set all string variables holding bound string values in string space to the empty string, and clear string space including the string buffer, string stack, and string stack frames. "zero-strings"

Disable garbage collection in the current string space. An error will be thrown if garbage collection is attempted. "string-g-c-off"

Enable garbage collection in the current string space. This is the default. "string-g-c-on"

Fetch the dstring garbage collection "off" state. Intended for saving the off state for later restoration after a usage of $gc-on or $gc-off. "string-g-c-lock-fetch"

Set the dstring garbage collection "off" state according to flag. Intended for restoring the off state previously fetched by gc-lock@. "string-g-c-lock-store"

Leave true if there is garbage in the current string space. Not normally used, since garbage collection is transparent. "string-garbage-question"

If string space is not marked as containing garbage, return false. If there is garbage, throw an error when garbage collection is disabled. Otherwise remove the garbage and return true. Garbage collection is "transparent", so the user would not normally use this word. "collect-string-garbage"

Note: Garbage strings are marked by null backward links. Nongarbage strings are bound by their backward links, pointing either to a string variable DFA or to an entry on the string stack (the deepest if there are several identical references).

Garbage collection fills the gaps occupied by garbage strings by moving any nongarbage strings to lower memory one at a time. The backward link of a string that is moved does not change, but the forward links, in at most one string variable, and/or possibly several on the string stack, are updated to point to the new MSA. This algorithm is "fast" because the backward links make it unnecessary to scan a list of string variables; and because no string is moved more than once. It does, however, require a scan of the string stack for each string that moves, unless it is the current concatenation string, which is guaranteed not to be on the string stack.

Store the string whose MSA is on the string stack in the string variable whose DFA is on the parameter stack. "string-store"

Note: The only situation in which $! copies the string value is when it is a bound string already stored in another variable. In that case, the new copy is the one that is stored in the variable. In particular, external strings are not copied.

Note: If the string value held by the string variable on entry is a bound string that is also referenced deeper on the string stack, its back link is reset to point to the deepest string stack reference. If it is a bound string not deeper on the string stack and not identical to the input string, its back link is set to zero, making it garbage. If it is an external string, its MSA in the variable is simply written over by that popped from the string stack.

Leave the MSA of the string held by the string variable. The string is not copied. "string-fetch"

Create a definition for "name" which pushes an external copy of a$ onto the string stack, without copying it into the string buffer. When a$ is already external, the definition does not make a new copy; otherwise it copies a$ into data space as a measured string. "string-constant"

For example:

     $" This is a sample string." $constant sample$

Warning: If a$ is external because it is in another string space, it may move or disappear at the next garbage collection in that space, making the MSA pushed by "name" invalid. This can be avoided by sandwiching sections of code where this could occur between $gc-off and $gc-on.

Create an ordinary ANS Forth variable and initialize it to the address of a fixed, external, measured representation of the empty string, such as that pushed onto the string stack by empty$. "string-variable"

Parse the parse area up to the first occurrence of char, which is parsed away, and store the string as an external measured string. If executing in compilation mode, append run-time semantics to the current definition that leaves the MSA on the string stack. In interpretation mode, leave the MSA on the string stack, where the stored copy, unlike parse>s, is required to be nontransient. An error is thrown if there is an mcount overflow. "parse-to-string"

These words are synonyms, with $type deprecated. Display the string on the terminal. If the system implementation of TYPE has its output vectored, $. uses the same vector. "string-dot", "string-type"

Leave the number of items on the string stack. "string-depth"

Drop the topmost string stack entry, marking it as garbage if it is initially bound to the top of the string stack. "string-drop"

Leave a copy of the topmost string stack entry. The string value is not copied. "string-dupe"

Exchange the two most accessible strings on the string stack. Throw an error if there are less than two strings on the stack. Neither string value is copied. "string-swap"

Drop the next to top item from the string stack. "string-nip"

Note: A system-level implementation may be omitted. Because of essential string space bookkeeping, it can be little more efficient than the high-level definition:

 
      : $nip  $swap $drop ;

Leave a copy of the next most accessible string stack entry on top of the string stack. The string value is not copied. "string-over"

Copy the top string stack item just below the second item. The string value is not copied. "string-tuck"

Note: A system-level implementation may be omitted. Because of essential string space bookkeeping, it can be little more efficient than the high-level definition:

 
      : $tuck  $swap $over ;

Drop the two topmost string stack entries, marking them as garbage if appropriate. "string-two-drop"

Leave copies of the two topmost string stack entries. The string values are not copied. "string-two-dupe"

Copy the u-th string stack entry to the top of the string stack. The string value is not copied. Throw an error if the input string stack does not have at least u+1 items. "string-pick"

Exchange the ith and jth strings on the string stack, where the top is the 0th. Throw an error if there are not at least max[i,j]+1 strings on the stack. Neither string value is copied. "string-exchange"

Drop a$ from the string stack and leave it as an ANS Forth string a.s, without copying. "string-s-from"

Warning: If a$ is a bound string, it may move or disappear at the next garbage collection, making a.s invalid. This can be avoided by sandwiching sections of code where this could occur between $gc-off and $gc-on.

Drop a$ from the string stack, copy it into data space as a measured string, and leave it as an ANS Forth string a.s. "string-comma-s"

Leave the string stack unchanged, and leave the string body address and length on the data stack. "string-s-fetch"

Warning: If a$ is a bound string, it may move at the next garbage collection, making a.s invalid. This can be avoided by sandwiching sections of code where this could occur between $gc-off and $gc-on.

Push the external ANS Forth string a.s onto the string stack, without copying the string value into the string buffer. It is an unchecked error if the ANS Forth string a.s is not stored as a fixed, external measured string. "to-string-s"

Warning: If the string value of a.s is actually in the string buffer, the push operation may generate a garbage collection that invalidates its MSA.

Copy the external string value whose body address and count are on the parameter stack into the string buffer and push it onto the string stack. Errors are thrown if there is an mcount overflow, if there is not enough room in string space, even after garbage collection, or if there is an unterminated string concatenation. The input external string need not exist as a measured string. "to-string-s-copy"

Warning: This word should not be used when the input string is a bound string because the copy operation may generate a garbage collection which invalidates its MSA.

Abort if the string stack would underflow when popped.

Otherwise pop the top of the string stack and push it onto the data stack.

If the string is in the current string space and initially bound to the top of the string stack, mark it as garbage by setting its back link to NULL and set the garbage flag. "string-pop"

Note: This word violates the normal expectation that only ANS Forth strings should appear on the data stack.

Warning: If msa is the address of a bound string, it may become invalid at the next garbage collection. This can be avoided by sandwiching sections of code where this could occur between $gc-off and $gc-on.

Pop an external mstring address from the data stack and push it onto the string stack after checking for room, invoking garbage collection if necessary. Not to be used with a dynamic string because a garbage collection can invalidate its address.

Note: This word violates the normal expectation that only ANS Forth strings should appear on the data stack.

If the input is the empty string, drop it and do nothing else.

In particular, do not start a new concatenation, which would lock string space against new, nonconcatenating copies.

Append the string body to the end of the string currently being concatenated as the last string in the string buffer, and update its count field. If there is no concatenating string, start one. An error is thrown if there is not enough room in the string buffer even after a garbage collection, or if there is an mcount overflow. An ambiguous condition results if the combined string would be too large to calculate its length in a cell. When there is a concatenating string, only concatenation can copy a string into the string buffer. Pushes onto the string stack without copy are still allowed. "string-plus", "s-plus"

If there is no concatenating string, do nothing but leave the empty string. If there is, leave it as a string bound to the top of the string stack, and terminate concatenation, permitting normal copies into the string buffer. "end-cat"

Note: Concatenation can be interrupted and resumed like this:

 
      ENDCAT ... $+

where the intervening action must ensure that the string pushed by ENDCAT is on top of the string stack for $+. There may be overhead from a recopy of the interrupted concatenation, if any new strings have been produced in string space, even if marked as garbage. If the intervening action leaves a new concatenation in progress, the old is concatenated to the new (unless there was no old concatenation in progress).

Parse the parse area up to the first occurrence of char, which is parsed away. If executing in compilation mode, append run-time semantics to the current definition that concatenates the characters parsed from the string. Otherwise concatenate the characters. "parse-s-plus"

Leave the number of entries in the topmost string frame. Throw an error if the frame stack is empty. "number-string-args"

Immediate and compilation-only.

Copy the argument strings across lines to the string buffer, push them onto the string stack with argn the most accessible, and make them into the top compile-time string stack frame. Compile the run-time code to make an argument frame out of the n most accessible run-time string stack entries.

Start intercepting the input stream across lines. For any argument word token, compile run-time code that concatenates the corresponding string in the run-time frame. For any nonargument word token, compile its normal run-time semantics. At the semicolon terminating the definition, drop the compile-time argument frame, compile code to drop the run-time argument frame, perform the normal system semicolon semantics, and stop intercepting the input stream. "string-args-brace"

Syntax for defining a string macro george:

 
      : george  ($: a$ b$ c$ -- cat$ )
        $ARGS{ arg1 arg2 arg3 }
        $+" This is arg1:  " arg1 $+" ." ENDCAT ;

Push the description of a string stack frame starting at the top of the string stack and containing u entries onto the string frame stack. Errors are thrown if the frame stack would overflow or if the depth of the string stack above the top frame, if there is one, is less than u. The value u = 0 is allowed. "string-frame"

Note: The current implementations push u and the string stack pointer onto the frame stack.

Note: Any changes to the string stack in or below the string frame before it is dropped, except for those induced by garbage collection, result in an ambiguous condition.

Leave the number of string frames currently on the string frame stack. "string-frame-depth"

Drop the topmost string frame from the string frame stack and string stack, and the corresponding strings, frame*$, from the string stack. An error is thrown if either stack would underflow. The cases where the frame has zero entries on the string stack and/or there are zero or more items on the string stack above the top frame item are handled properly. "drop-string-frame"

Leave true and its index u in the top string frame if the ANS Forth string matches an element of the frame, else leave false. The index of the top frame element is zero. "find-string-arg"

Leave the u-th string in the topmost string frame, where the index u of the top element is zero. Throw an error if the frame stack is empty or if the top frame contains less than u + 1 strings. "th-string-arg"