_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 (size_t)-1, it is computed from s using wcslen(). See PL_new_atom() for error handling.

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 PL_ATOM, PL_STRING, PL_CODE_LIST or PL_CHAR_LIST.

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 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 the term_t passed in as arguments to a predicate, we must copy the argument term_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