2.3 CHARACTER AND STRING OPERATIONS

Forth contains many words used to reference single characters (bytes) or character strings. Characters may be grouped and thought of as a string; this group is then operated on as a single variable. Character strings are supported by the words documented in this section.

A string may or may not include its length as part of its structure. If it does not, it is referred to as a character string and is specified by a cell pair ( c-addr u ) representing its starting address c-addr and length u in characters. If it does include the length, it is referred to as a counted string and is specified only by its starting address c-addr. The byte at that address contains a binary count of the number of data characters in the string, which immediately follow the count byte. The maximum length of a counted string is 255 data characters (256 bytes total).

Forth Fundamentals 47

Forth Programmer’s Handbook

A standard working area is used to hold most character strings for processing; this area is referred to as PAD.

In addition to the words described in this section, other words may be used to reference character data in specific environments, e.g., database support. Such words are described in the appropriate sections of product-specific manuals.

2.3.1 The PAD—Scratch Storage for Strings

PAD is a storage area of indefinite size (84 characters minimum) that is used to hold strings for intermediate processing. Each terminal task contains a PAD area. The word PAD places the address of the first byte in this area on the top of the stack.

The contents of the region addressed by PAD are under the complete control of the user. No words defined in a Standard Forth system or described in this manual place anything in this region, although changing data space allocations (e.g., by adding new words to the Forth dictionary) may change the address returned by PAD.

In cases where PAD is located relative to the dictionary pointer, the location of PAD changes whenever something is added to the dictionary. Common operations that affect the dictionary pointer may include: adding definitions; adding data or data areas by using , (comma), C, (c-comma), or ALLOT; and discarding definitions. Thus, information left in PAD before one of these operations may not be addressable after the operation (and may, in fact, be overwritten by a new definition).

Return the address of a temporary storage area, usually used for processing strings. The area can hold at least 84 characters. It may be located relative to the top of the dictionary, in which case the address of PAD will vary as the dictionary is modified.

48 Forth Fundamentals

Forth Programmer’s Handbook

References , and C,, Section 4.3.2

ALLOT, Section 4.3.1

2.3.2 Single-Character Reference Words

The words C@ and C! are used to reference single characters in the same way that @ and ! are used to reference cells.

C@ expects an address on top of the stack. This address is replaced with the contents of the addressed byte. This byte will be placed in bits 0–7 of the cell on top of the stack, with the higher order bits set to zero. C@ does not “sign extend,” i.e., it does not propagate the sign bit leftward into more-significant bit positions.

C! expects an address on top of the stack and a character in bits 0–7 of the cell underneath the byte pointer. The high-order bits of this lower cell are ignored. The character is stored in the addressed byte; the address and character cells are removed from the stack.

For example, the following phrase would fetch the first character in PAD to the top of the stack:

PAD C@

References C@ and C!, Section 2.1.3

2.3.3 String Management Operations

Forth contains several words used to reference strings, compare and adjust them, and move strings between different locations. Additional words are used to input or output character strings; these are discussed in Section 3.3.

Forth Fundamentals 49

Forth Programmer’s Handbook

Figure 7. Format of arguments for most two-string operators

Most words that operate on one string expect the length of that string to be on top of the stack, with its address beneath it. Many words that operate on two separate strings expect three items on top of the stack, in the format shown in Figure 7, where one length applies to both strings. The above format is used instead of two separate character counts.

In files, fields containing character strings have names which, when executed, return the address of the field. Thus, such field names may be used to supply arguments for these string operations.

Determine if there are trailing blanks in a string at address c-addr whose original length is u1, and return adjusted string parameters. The same address is returned with an adjusted length u2, equal to u1 less the number of spaces at the end of the string. If u1 is zero, or if the entire string consists of blanks, u2 is zero. “minus-trailing”

Set a region of memory, at address c-addr and of length u, to ASCII blanks (hex

50 Forth Fundamentals