rovide 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 asPL_new_atom("[]")
andATOM_dot
is the same asPL_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
orREP_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(). - int 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
orREP_ISO_LATIN_1
. Storage is defined by theBUF_*
flags as described with PL_get_chars(). The flagCVT_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
). - 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.