Node:Chars I/O, Next:Jasper, Previous:Gauge, Up:Top

I/O on Lists of Character Codes

This package defines I/O predicates that read from, or write to, a list of character codes (a string). There are also predicates to open a stream referring to a list of character codes. The stream may be used with general Stream I/O predicates.

Note that the predicates in this section properly handle wide characters, irrespectively of the wide character encodings selected. Note also that here, the term chars refers to a list of character codes, rather than to one-char atoms.

This library fully supports multiple SICStus run-times in a process.

To load the package, enter the query

| ?- use_module(library(charsio)).

format_to_chars(+Format, :Arguments, -Chars)

format_to_chars(+Format, :Arguments, ?S0, ?S)

Prints Arguments into a list of character codes using format/3 (see Term I/O). Chars is unified with the list, alternatively S0 and S are unified with the head and tail of the list, respectively.

write_to_chars(+Term, -Chars)

write_to_chars(+Term, ?S0, ?S)

A specialized format_to_chars/[3,4]. Writes Term into a list of character codes using write/2 (see Term I/O). Chars is unified with the list. Alternatively, S0 and S are unified with the head and tail of the list, respectively.

write_term_to_chars(+Term, -Chars, +Options)

write_term_to_chars(+Term, ?S0, ?S, +Options)

A specialized format_to_chars/[3,4]. Writes Term into a list of character codes using write_term/3 and Options (see Term I/O). Chars is unified with the list. Alternatively, S0 and S are unified with the head and tail of the list, respectively.

atom_to_chars(+Atom, -Chars)

atom_to_chars(+Atom, ?S0, ?S)

A specialized format_to_chars/[3,4]. Converts Atom to the list of characters comprising its name. Chars is unified with the list, alternatively S0 and S are unified with the head and tail of the list, respectively.

number_to_chars(+Number, -Chars)

number_to_chars(+Number, ?S0, ?S)

A specialized format_to_chars/[3,4]. Converts Number to the list of characters comprising its name. Chars is unified with the list, alternatively S0 and S are unified with the head and tail of the list, respectively.

read_from_chars(+Chars, -Term)

Reads Term from Chars using read/2. The Chars must, as usual, be terminated by a full-stop, i.e. a ., possibly followed by layout-text.

read_term_from_chars(+Chars, -Term, +Options)

Reads Term from Chars using read_from_term/3 and Options. The Chars must, as usual, be terminated by a full-stop, i.e. a ., possibly followed by layout-text.

open_chars_stream(+Chars, -Stream)

Stream is opened as an input stream to an existing list of character codes. The stream may be read with the Stream I/O predicates and must be closed using close/1. The list is copied to an internal buffer when the stream is opened and must therefore be a ground list of character codes at that point.

with_output_to_chars(:Goal, -Chars)

with_output_to_chars(:Goal, ?S0, ?S)

with_output_to_chars(:Goal, -Stream, ?S0, ?S)

Goal is called with the current_output stream set to a new stream. This stream writes to an internal buffer which is, after the successful execution of Goal, converted to a list of character codes. Chars is unified with the list, alternatively S0 and S are unified with the head and tail of the list, respectively. with_output_to_chars/4 also passes the stream in the Stream argument. It can be used only by Goal for writing.