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


5.19.4 Displaying characters and strings

This section starts with a glossary of Forth words and ends with a set of examples.

bl ( – c-char  ) core “b-l”

c-char is the character value for a space.

space ( ) core “space”

Display one space.

spaces ( u –  ) core “spaces”

Display n spaces.

emit ( c –  ) core “emit”

Display the character associated with character value c.

toupper ( c1 – c2 ) gforth-0.4 “toupper”

If c1 is a lower-case character (in the current locale), c2 is the equivalent upper-case character. All other characters are unchanged.

." ( compilation ’ccc"’ – ; run-time –  ) core “dot-quote”

Compilation: Parse a string ccc delimited by a " (double quote). At run-time, display the string. Interpretation semantics for this word are undefined in ANS Forth. Gforth’s interpretation semantics are to display the string. This is the simplest way to display a string from within a definition; see examples below.

.( ( compilation&interpretation "ccc<paren>" –  ) core-ext “dot-paren”

Compilation and interpretation semantics: Parse a string ccc delimited by a ) (right parenthesis). Display the string. This is often used to display progress information during compilation; see examples below.

.\" ( compilation ’ccc"’ – ; run-time –  ) gforth-0.6 “dot-backslash-quote”

Like .", but translates C-like \-escape-sequences (see S\").

type ( c-addr u –  ) core “type”

If u>0, display u characters from a string starting with the character stored at c-addr.

typewhite ( addr n –  ) gforth-0.4 “typewhite”

Like type, but white space is printed instead of the characters.

cr ( ) core “c-r”

Output a newline (of the favourite kind of the host OS). Note that due to the way the Forth command line interpreter inserts newlines, the preferred way to use cr is at the start of a piece of text; e.g., cr ." hello, world".

S" ( compilation ’ccc"’ – ; run-time – c-addr u  ) core,file “s-quote”

Compilation: Parse a string ccc delimited by a " (double quote). At run-time, return the length, u, and the start address, c-addr of the string. Interpretation: parse the string as before, and return c-addr, u. Gforth allocates the string. The resulting memory leak is usually not a problem; the exception is if you create strings containing S" and evaluate them; then the leak is not bounded by the size of the interpreted files and you may want to free the strings. Forth-2012 only guarantees two buffers of 80 characters each, so in standard programs you should assume that the string lives only until the next-but-one s".

s\" ( compilation ’ccc"’ – ; run-time – c-addr u  ) gforth-0.6 “s-backslash-quote”

Like S", but translates C-like \-escape-sequences, as follows: \a BEL (alert), \b BS, \e ESC (not in C99), \f FF, \n newline, \r CR, \t HT, \v VT, \" ", \\ \, \[0-7]{1,3} octal numerical character value (non-standard), \x[0-9a-f]{0,2} hex numerical character value (standard only with two digits), \u[0-9a-f]{4} for unicode codepoints (auto-merges surrogate pairs), \U[0-9a-f]{8} for extended unicode code points; a \ before any other character is reserved.
Note that \xXX produces raw bytes, while \uXXXX and \UXXXXXXXX produce code points for the current encoding. E.g., if we use UTF-8 encoding and want to encode ä (code point U+00E4), you can write the letter ä itself, or write \xc3\xa4 (the UTF-8 bytes for this code point), \u00e4, or \U000000e4.

C" ( compilation "ccc<quote>" – ; run-time  – c-addr  ) core-ext “c-quote”

Compilation: parse a string ccc delimited by a " (double quote). At run-time, return c-addr which specifies the counted string ccc. Interpretation semantics are undefined.

char ( ’<spaces>ccc’ – c  ) core “char”

Skip leading spaces. Parse the string ccc and return c, the display code representing the first character of ccc.

[char] ( compilation ’<spaces>ccc’ – ; run-time – c  ) core “bracket-char”

Compilation: skip leading spaces. Parse the string ccc. Run-time: return c, the display code representing the first character of ccc. Interpretation semantics for this word are undefined.

As an example, consider the following text, stored in a file test.fs:

.( text-1)
: my-word
  ." text-2" cr
  .( text-3)
;

." text-4"

: my-char
  [char] ALPHABET emit
  char emit
;

When you load this code into Gforth, the following output is generated:

include test.fs RET text-1text-3text-4 ok

Here are some examples of executing my-word and my-char:

my-word RET text-2
 ok
my-char fred RET Af ok
my-char jim RET Aj ok

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