|Did you know ...||Search Documentation:|
|Atoms and functors|
The following functions provide for communication using atoms and functors.
The following atoms are provided as macros, giving access to the
empty list symbol and the name of the list constructor. Prior to version 7,
ATOM_nil is the same as
ATOM_dot is the same as
This is no longer the case in SWI-Prolog version 7.
PL_new_functor(ATOM_dot,2). It is advised to use PL_get_list(), PL_put_list() or PL_unify_list() where applicable.
REP_MB. If len is
(size_t)-1, it is computed from s using strlen(). Raises an exception if s violates rep and returns
(atom_t)0. For other error conditions, see PL_new_atom().
REP_ISO_LATIN_1. Storage is defined by the
BUF_*flags as described with PL_get_chars(). The flag
CVT_EXCEPTIONdefines whether or not the function fails silently or raises a Prolog exception. This function may fail because atom is not a text atom but a blob (see section 12.4.10), conversion to the requested encoding is not possible or a resource error occurs.
term_thandle should use PL_atom_nchars(), PL_atom_wchars(), or PL_atom_mbchars(). If it is known that atom is a classical Prolog text atom, one can use PL_atom_nchars() to obtain the C string and its length (for ISO-Latin-1 atoms) or PL_atom_wchars() to obtain a C wide string (
With the introduction of atom garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the call-port. In the multithreaded version (see chapter 10), they appear asynchronously, except for the invoking thread.
For dealing with atom garbage collection, two additional functions are provided:
Please note that the following two calls are different with respect to atom garbage collection:
PL_unify_atom_chars(t, "text"); PL_unify_atom(t, PL_new_atom("text"));
The latter increments the reference count of the atom
which effectively ensures the atom will never be collected. It is
advised to use the *_chars() or *_nchars() functions whenever