This is NO page from the dpans'94 document.
It is an experimental draft for public review, here at FORTH.SF.NET

RFC
2002

TOC

26. The optional ZChar word set

See: A.20 The optional ZChar word set

26.1 Introduction

26.2 Additional terms and notation

zchar string:: A ZChar strings consists of characters terminated by a null. The length of a zchar string is number of charachters between the start of the string and null character at the end. An empty zchar string still occupies a character cell in memory for the null character.

See: A.26.2 Additional terms

backslash string:

A backslash string is an encoding of a basic character string where each sequence of a backslash followed by one or a number of characters does represent one character of the basic character encoding. The following table lists the mapping between the two encodings where the backslash encoding occupies two characters and the the basic encoding one character of memory. For clarification the hex values of the ASCII basic char encodings are given.

backslash encoding     ascii encoding     meaning
   \a                  hex 07             BEL - bell
   \b                  hex 08             BS  - backspace
   \t                  hex 09             HT  - horizontal tabulator
   \n                  hex 0A             LF  - line feed / new line
   \v                  hex 0B             VT  - vertical tabulator
   \f                  hex 0C             FF  - form feed / new page
   \r                  hex 0D             CR  - carriage return
   \\                  hex 5C             a single backslash itself
   \q                  hex 22             a single doublequote
   \e                  hex 1B             a terminal escape control

The sequences of a backslash followed by a number are called octalescapes, the sequence of backslash followed by an [x] character are called hexescapes. The transconding of other backslash sequences is system dependent.

See: A.26.2 Additional terms

backslash octalescapes:: A backslash sequence introduces with a number character and followed other number characters. The number sequences is subject to a number conversion from an octal number string representation to the unsigned bit value that is used in host character encoding.

See: A.26.2 Additional terms

backslash hexescapes:: A backslash sequence introduces with an [x] character followed by exactly two other non-delimiter characters. The two characters are subject to a number conversion from an hexadecimal number string representation to the unsigned bit value that is used in host character encoding.

See: A.26.2 Additional terms

26.3 Additional usage requirements

26.3.1 Basis

The ZChar strings are an implementation used primarily to interface with C implemented routines - to create parameters and work on returned data. In many cases it is beneficial to keep the zero-terminated strings on forth level and to work directly with them.

See: 17 string extensions word set.

26.3.2 Environmental queries

Append table 26.2 to table 3.5.

See: 3.2.6 Environmental queries

Table 26.2 - Environmental query strings

String            Value data type  Constant?  Meaning
------            ---------------  ---------  -------
ZCHAR-EXT         flag             no         zchar extensions word set present

26.4 Additional documentation requirements

26.4.1 System documentation

26.4.1.1 Implementation-defined options

the compatibility level of backslash sequences in backslash string literals with C string literals. A system may be dependent on features of functions in libc.
a system must implement one of these options for backslash string literals.
- allow the delimiter char in backslash string literals when escaped with a backslash.
- implement backslash octalescapes.
- implement backslash hexescapes.
it is recommended to implement atleast backslash hexescapes.

26.4.1.2 Ambiguous conditions

whether backslash string literals can span multiple lines using a similar approach as the backslash-newline code as seen in C and unixshell sources - a forth system may throw on any control char in a string and a backslash at the of the input line.
whether backslash-octalsequences are understood in backslash string literals as in C, or whether the system will throw on any backslash-and-number sequence.
whether an extension to backslash-octalsequences is understood to accept a maximum or less than three number characters when other numbers or characters are known to be not convertible to the host character encoding.
whether an extension to backslash-hexequences is understood to accept less than two alphanumeric characters when the latter characters are known to be not convertible to the host character encoding.
whether the backslash-e and backslash-q sequences are implemented in backslash string literals.
whether other backslash-alphachar sequnces are understood in backslash string literals, including a default mapping of these to control characters instead of throwing an exception.
systems usually map sequences of backslash and a non-alphanumeric character silently to the very same non-alphanumeric character after the backslash. An ambiguous condition exists when a system chooses to do otherwise like throwing on an unrecognized characters or to map silently some of these non-alnum characters to a different non-alphanum character. (note: some systems chose to map backslash-singlequote to a doublequote character).
whether in backslash string literals the delimiter (usually the doublequote character or space character) may occur when escaped as a backslash-delimiterchar sequence, or whether another backslash-sequence must be used to represent the delimiter char.

26.4.1.3 Other system documentation

which exception number is used when an unexpected backslash sequence is encountered in backslash string literals.

26.4.2 Program documentation

26.4.2.1 Environmental dependencies

no additional dependencies.

26.4.2.2 Other program documentation

no additional requirements.

26.5 Compliance and labeling

26.5.1 STD Forth systems

The phrase Providing the ZChar word set shall be appended to the label of any Standard System that provides all of the ZChar word set.

The phrase Providing name(s) from the ZChar Extensions word set shall be appended to the label of any Standard System that provides portions of the ZChar Extensions word set.

The phrase Providing the ZChar Extensions word set shall be appended to the label of any Standard System that provides all of the Environment and ZChar Extensions word sets.

26.5.2 STD Forth programs

The phrase Requiring the ZChar word set shall be appended to the label of Standard Programs that require the system to provide the ZChar word set.

The phrase Requiring name(s) from the ZChar Extensions word set shall be appended to the label of Standard Programs that require the system to provide portions of the ZChar Extensions word set.

The phrase Requiring the ZChar Extensions word set shall be appended to the label of Standard Programs that require the system to provide all of the Environment and ZChar Extensions word sets.

26.6 Glossary

26.6.1 ZChar words


26.6.1.0001 Z"

ZCHAR

        Interpretation: Interpretation semantics for this word are undefined.

        Compilation: ( "ccc<quote>" -- )

Parse ccc delimited by " (double-quote). Append the run-time semantics given below to the current definition.

        Run-time: ( -- z-addr )

Return z-addr describing a string consisting of the characters ccc plus a terminating null zchar. A program shall not alter the returned string.

See: 3.4.1 Parsing, 6.2.0855 C" , 6.1.2165 S" , 11.6.1.2165 S" ,


26.6.1.0002 ZCOUNT

ZCHAR

        ( z-addr -- z-addr u )

Return the character string specification for the zchar string stored at c-addr. The returned c-addr is the same for these strings. u is number of zchars up to the terminating null charachter, which is the length of the string.

See: 6.1.0980 COUNT 26.6.2.0003 ZSTRLEN

26.6.2 ZChar extension words


26.6.2.0003 ZSTRLEN

ZCHAR

       ( z-addr -- u )

Return the length of the zchar string stored at c-addr which is the number of zchars up to the terminating null charachter from z-addr.

See: 26.6.2.0002 ZCOUNT


26.6.2.0004 ZMOVE

ZCHAR

        ( z-addr1 z-addr2 -- )

Copy consecutive characters from the data space starting at c-addr1 to that starting at c-addr2, proceeding character-by-character from lower addresses to higher addresses until the terminating null character in z-addr1 is encountered which is copied last.

See: 17.6.1.0910 CMOVE , 17.6.1.0920 CMOVE>


26.6.2.0005 APPENDZ / Z+PLACE

ZCHAR EXT

        ( c-addr u z-addr -- )

Adjust the destination z-addr by looking for its terminating null character. If u is greater than zero, copy u consecutive characters from the data space starting at c-addr to that starting at the null character, proceeding character-by-character from lower addresses to higher addresses. Place a null character in the destination area after copying

See: 26.6.2.0004 ZMOVE , 26.6.2.0006 ZPLACE


26.6.2.0006 ZPLACE

ZCHAR EXT

        ( c-addr u z-addr -- )

If u is greater than zero, copy u consecutive characters from the data space starting at c-addr to that starting at z-addr, proceeding character-by-character from lower addresses to higher addresses. Always place a null character in the destination area as the end of the z-addr.

See: 26.6.1.0004 ZMOVE , 26.6.6.0005 Z+PLACE / APPENDZ


26.6.2.0007 C\"

ZCHAR EXT

        Interpretation: Interpretation semantics for this word are undefined.

        Compilation: ( "backslash-string<quote>" -- )

Parse the backslash-string definition up to the final " (double-quote) and append the run-time semantics given below to the current definition.

        Run-time: ( -- c-addr )

Return c-addr, a counted string consisting of the characters of the backslash-string. A program shall not alter the returned string.

See: 3.4.1 Parsing , 26.4.1 backslash-string , 26.2.005 Z\" , 6.2.0855 C" , 6.1.2165 S" , 11.6.1.2165 S" ,


26.6.2.0008 S\"

ZCHAR EXT

        Interpretation: Interpretation semantics for this word are undefined.

        Compilation: ( "backslash-string<quote>" -- )

Parse the backslash-string definition up to the final " (double-quote) and append the run-time semantics given below to the current definition.

        Run-time: ( -- c-addr u )

Return c-addr and u describing a string consisting of the characters ccc. A program shall not alter the returned string.

See: 3.4.1 Parsing , 26.4.1 backslash-string , 26.2.005 Z\" , 6.2.0855 C" , 6.1.2165 S" , 11.6.1.2165 S" ,


26.6.2.0009 Z\"

ZCHAR EXT

        Interpretation: Interpretation semantics for this word are undefined.

        Compilation: ( "backslash-string<quote>" -- )

Parse the backslash-string definition up to the final " (double-quote) and append the run-time semantics given below to the current definition.

        Run-time: ( -- z-addr )

Return z-addr, a zchar string consisting of the characters of the backslash-string plus the required null character at the end. A program shall not alter the returned string.

See: 3.4.1 Parsing , 26.4.1 backslash-string , 26.2.0003 C\" , 26.2.0004 S\" , 6.2.0855 C" , 6.1.2165 S" , 11.6.1.2165 S" ,

Table of Contents

Next Section