_t
len, const pl_wchar_t *s)Create atom from wide-character string as PL_new_atom_nchars()
does for ISO-Latin-1 strings. If s only contains ISO-Latin-1
characters a normal byte-array atom is created. If len is
const pl_wchar_t* PL_atom_wchars(atom_t
atom, size_t *len) Extract characters from a wide-character atom. Succeeds on any atom
marked as‘text'. If the underlying atom is a wide-character atom,
the returned pointer is a pointer into the atom structure. If the atom
is represented as an ISO-Latin-1 string, the returned pointer comes from
Prolog's‘buffer stack' (see section
12.4.14).
int PL_get_wchars(term_t
t, size_t *len, pl_wchar_t **s, unsigned flags) Wide-character version of PL_get_chars().
The flags argument is the same as for PL_get_chars().
Note that this operation may return a pointer into Prolog's‘buffer
stack' (see section
12.4.14).
int PL_put_wchars(term_t
-t, int type, size_t len, const pl_wchar_t *s) Put text from a wide character array in t. Arguments
are the same as PL_unify_wchars().217The
current implemention uses PL_put_variable()
followed by PL_unify_wchars().
int PL_unify_wchars(term_t
+t, int type, size_t len, const pl_wchar_t *s) Unify t with a textual representation of the C wide-character
array s. The type argument defines the Prolog
representation and is one of
int PL_unify_wchars_diff(term_t
+t, term_t -tail, int type, size_t len, const pl_wchar_t *s) Difference list version of PL_unify_wchars(),
only supporting the types
(size_t)-1
,
it is computed from s using wcslen(). See PL_new_atom()
for error handling.PL_ATOM
, PL_STRING
,
PL_CODE_LIST
or PL_CHAR_LIST
.PL_CODE_LIST
and PL_CHAR_LIST
.
It serves two purposes. It allows for returning very long lists from
data read from a stream without the need for a resizing buffer in C.
Also, the use of difference lists is often practical for further
processing in Prolog. Examples can be found in packages/clib/readutil.c
from the source distribution.
12.4.4.5 Reading a list
The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of atoms; the code below will print the atoms, each on a line. Please note the following:
- We need a
term_t
term reference for the elements (head). This reference is reused for each element. - We walk over the list using PL_get_list_ex()
which overwrites the list
term_t
. As it is not allowed to overwrite theterm_t
passed in as arguments to a predicate, we must copy the argumentterm_t
. - SWI-Prolog atoms are Unicode objects. The PL_get_chars()
returns a
char*
. We want it to convert atoms, return the result as a multibyte string (REP_UTF8
may also be used) and finally we want an exception on type, instantiation or representation errors (if the system's default encoding cannot represent some characters of the Unicode atom). This may create temporary copies of the atom text - PL_STRINGS_MARK() ... PL_STRINGS_RELEASE() handles that. - The *_ex() API functions are functionally the same as the ones
without the
_ex
suffix, but they raise type, domain, or instantiation errors when the input is invalid; whereas the plain version may only raise resource excep