12.4.2 Atoms and functors

The following functions provide for communication using atoms and functors.

atom_t PL_new_atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced (see section 12.4.2.1). Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (atom_t)0.

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 PL_new_atom("[]") and ATOM_dot is the same as PL_new_atom("."). This is no longer the case in SWI-Prolog version 7.

atom_t ATOM_nil(A)

tomic constant that represents the empty list. It is advised to use PL_get_nil(), PL_put_nil() or PL_unify_nil() where applicable.

atom_t ATOM_dot(A)

tomic constant that represents the name of the list constructor. The list constructor itself is created using PL_new_functor(ATOM_dot,2). It is advised to use PL_get_list(), PL_put_list() or PL_unify_list() where applicable.

atom_t PL_new_atom_mbchars(int rep, size_t len, const char *s)

This function generalizes PL_new_atom() and PL_new_atom_nchars() while allowing for multiple encodings. The rep argument is one of REP_ISO_LATIN_1, REP_UTF8 or 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().

bool PL_atom_mbchars(atom_t atom, size_t len, char *s, unsigned int flags)

This function generalizes fetching the text associated with an atom. The encoding depends on the flags REP_UTF8, REP_MB or REP_ISO_LATIN_1. Storage is defined by the BUF_* flags as described with PL_get_chars(). The flag CVT_EXCEPTION defines 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.

const char* PL_atom_chars(atom_t atom)

Deprecated. This function returns a pointer to the content represented by the atom or blob regardless of its type. New code that uses blobs should use the blob functions such as PL_blob_data() to get a pointer to the content, the size of the content, and the type of the content. Most applications that need to get text from a term_t handle 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 (wchar_t).

size_t PL_atom_index(atom_t atom)

Extract the index of an atom. This is a relatively small integer. Atoms are numbered sequentially, starting at one (1). Note that the sequence may have holes due to atom garbage collection. The released index may later be reused for a new atom. The index may be used as a compact identifier for the atom. Extracting the index has no impact on the lifetime of the atom, i.e., the index is valid as long as the atom_t is valid.

atom_t PL_atom_from_index(size_t index)

Recover an atom from its index as obtained by PL_atom_index().

functor_t PL_new_functor(atom_t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session. Future versions may garbage collect functors as part of atom garbage collection. Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (atom_t)0.

atom_t PL_functor_name(functor_t f)

Return an atom representing the name of the given functor.

size_t PL_functor_arity(functor_t f)

Return the arity of the given functor.

12.4.2.1 Atoms and atom garbage collection

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:

void PL_register_atom(atom_t atom)

Increment the reference count of the atom by one. PL_new_atom() performs this automatically, returning an atom with a reference count of at least one.^{218Otherwise asynchronous atom garbage collection might destroy the atom before it is used.}

void PL_unregister_atom(atom_t atom)

Decrement the reference count of the atom. If the reference count drops below zero, an assertion error is raised.

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 text, which effectively ensures the atom will never be collected. It is advised to use the *_chars() or *_nchars() functions whenever applicable.