Support for exchange of wide-character strings is still under
consideration. The functions dealing with 8-bit character strings return
failure when operating on a wide-character atom or Prolog string object.
The functions below can extract and unify both 8-bit and wide atoms and
string objects. Wide character strings are represented as C arrays of
objects of the type pl_wchar_t, which is guaranteed to be
the same as wchar_t on platforms supporting this type. For
example, on MS-Windows, this represents a 16-bit UTF-16 string, while
using the GNU C library (glibc) this represents 32-bit UCS4 characters.
- atom_t PL_new_atom_wchars(size_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.13).
- 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.13).
- 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.