The functions PL_get_*() read information from a Prolog
term. Most of them take two arguments. The first is the input term and
the second is a pointer to the output value or a term reference. The
return value is TRUE or FALSE, indicating the
success of the "get" operation. Most functions have a related "_ex"
function that raises an error if the argument is the operation cannot be
completed. If the Prolog term is not suitable, this is a type, domain or
instantiation error. If the receiving C type cannot represent the value
this is a representation error.
For integers an alternative interface exists, which helps deal with
the various integer types in C and C++. They are convenient for use with
_Generic selection or C++ overloading.
- int PL_get_atom(term_t
+t, atom_t *a)
- If t is an atom, store the unique atom identifier over a.
See also PL_atom_chars()
and PL_new_atom().
If there is no need to access the data (characters) of an atom, it is
advised to manipulate atoms using their handle. As the atom is
referenced by t, it will live at least as long as t
does. If longer lifetime is required, the atom should be locked using PL_register_atom().
- int PL_get_atom_chars(term_t
+t, char **s)
- If t is an atom, store a pointer to a 0-terminated C-string
in
s. It is explicitly not allowed to modify
the contents of this string. Some built-in atoms may have the string
allocated in read-only memory, so‘temporary manipulation’can
cause an error.
- int PL_get_string_chars(term_t
+t, char **s, size_t *len)
- If t is a string object, store a pointer to a 0-terminated
C-string in s and the length of the string in len.
Note that this pointer is invalidated by backtracking, garbage
collection and stack-shifts, so generally the only safe operations are
to pass it immediately to a C function that doesn't involve Prolog.
- int PL_get_chars(term_t
+t, char **s, unsigned flags)
- Convert the argument term t to a 0-terminated C-string.
flags is a bitwise disjunction from two groups of constants.
The first specifies which term types should be converted and the second
how the argument is stored. Below is a specification of these constants.
BUF_STACK implies, if the data is not static (as from an
atom), that the data is pushed on a stack. If BUF_MALLOC is
used, the data must be freed using PL_free()
when no longer needed.
With the introduction of wide characters (see section
2.18.1), not all atoms can be converted into a char*.
This function fails if t is of the wrong type, but also if
the text cannot be represented. See the REP_* flags below
for details. See also PL_get_wchars()
and PL_get_nchars().
The first set of flags (CVT_ATOM through CVT_VARIABLE,
if set, are tested in order, using the first that matches. If none of
these match, then a check is made for one of CVT_WRITE,
CVT_WRITE_CANONICAL, CVT_WRITEQ being set. If
none of the “CVT_WRITE*” flags are set, then a type_error
is raised.
- CVT_ATOM
- Convert if term is an atom.
- CVT_STRING
- Convert if term is a string.
- CVT_LIST
- Convert if term is a list of characters (atoms of length 1) or character
codes (integers representing Unicode code points).
- CVT_INTEGER
- Convert if term is an integer.
- CVT_RATIONAL
- Convert if term is a rational number (including integers). Non-integral
numbers are written as <num>r<den>.
- CVT_XINTEGER
- Convert if term is an integer to hexadecimal notation. May be combined
with
CVT_RATIONAL to represent rational numbers using
hexadecimal notation. Hexadecimal notation is notably useful for
transferring big integers to other programming environments if the
target system can read hexadecimal notation because the result is both
more compact and faster to write and read.
- CVT_FLOAT
- Convert if term is a float. The characters returned are the same as
write/1
would write for the floating point number.
- CVT_NUMBER
- Convert if term is an integer, rational number or float. Equivalent to
CVT_RATIONAL|CVT_FLOAT.
Note that
CVT_INTEGER is implied by CVT_RATIONAL.
- CVT_ATOMIC
- Convert if term is atomic. Equivalent to
CVT_NUMBER|CVT_ATOM|CVT_STRING.
- CVT_ALL
- Convert if term is any of the above. Integers and rational numbers are
written as decimal (i.e.,
CVT_XINTEGER is not
implied). Note that this does not include variables or terms (with the
exception of a list of characters/codes). Equivalent to
CVT_ATOMIC|CVT_LIST.
- CVT_VARIABLE
- Convert variable to print-name (e.g.,
_3290).
- CVT_WRITE
- Convert any term that is not converted by any of the other flags using
write/1.
If no
BUF_* is provided, BUF_STACK is implied.
- CVT_WRITEQ
- As
CVT_WRITE, but using writeq/2.
- CVT_WRITE_CANONICAL
- As
CVT_WRITE, but using write_canonical/2.
- CVT_EXCEPTION
- If conversion fails due to a type error, raise a Prolog type error
exception in addition to failure.
- BUF_DISCARDABLE
- Data must copied immediately.
- BUF_STACK
- Data is stored on a stack. The older
BUF_RING is an alias
for BUF_STACK. See section
12.4.14.
- BUF_MALLOC
- Data is copied to a new buffer returned by PL_malloc(3).
When no longer needed the user must call PL_free()
on the data.
- REP_ISO_LATIN_1
- Text is in ISO Latin-1 encoding and the call fails if text cannot be
represented. This flag has the value 0 and is thus the default.
- REP_UTF8
- Convert the text to a UTF-8 string. This works for all text.
- REP_MB
- Convert to default locale-defined 8-bit string. Success depends on the
locale. Conversion is done using the wcrtomb() C library
function.
- int PL_get_list_chars(+term_t
l, char **s, unsigned flags)
- Same as
PL_get_chars(l, s,
CVT_LIST|flags), provided flags
contains none of the CVT_* flags.
- int PL_get_integer(+term_t
t, int *i)
- If t is a Prolog integer, assign its value over i.
On 32-bit machines, this is the same as PL_get_long(),
but avoids a warning from the compiler. See also PL_get_long()
and
PL_get_integer_ex().
- int PL_get_long(term_t
+t, long *i)
- If t is a Prolog integer that can be represented as a long,
assign its value over i. If t is an integer that
cannot be represented by a C long, this function returns
FALSE.
If t is a floating point number that can be represented as a
long, this function succeeds as well. See also PL_get_int64()
and PL_get_long_ex().
- int PL_get_int64(term_t
+t, int64_t *i)
- If t is a Prolog integer or float that can be represented as
a
int64_t, assign its value over i. See also PL_get_int64_ex().
- int PL_get_uint64(term_t
+t, uint64_t *i)
- If t is a Prolog integer that can be represented as a
uint64_t, assign its value over i. Note that
this requires GMP support for representing uint64_t values
with the high bit set. See also PL_get_uint64_ex().
- int PL_get_intptr(term_t
+t, intptr_t *i)
- Get an integer that is at least as wide as a pointer. On most platforms
this is the same as PL_get_long(),
but on Win64 pointers are 8 bytes and longs only 4. Unlike PL_get_pointer(),
the value is not modified.
- int PL_get_bool(term_t
+t, int *val)
- If t has the value
true, false, set val
to the C constant TRUE or FALSE and return
success, otherwise return failure. The values on, 1, off,
const0 and are also accepted.
- int PL_get_pointer(term_t
+t, void **ptr)
- Together with PL_put_pointer()
and PL_unify_pointer(),
these functions allow representing a C pointer as a Prolog integer. The
integer value is derived from the pointer, but not equivalent. The
translation aims at producing smaller integers that fit more often in
the tagged integer range. Representing C pointers as integers
is unsafe. The blob API described in section
12.4.10 provides a safe way for handling foreign resources that
cooperates with Prolog garbage collection.
- int PL_get_float(term_t
+t, double *f)
- If t is a float, integer or rational number, its value is
assigned over f. Note that if t is an integer or
rational conversion may fail because the number cannot be represented as
a float.
- int PL_get_functor(term_t
+t, functor_t *f)
- If t is compound or an atom, the Prolog representation of the
name-arity pair will be assigned over f. See also
PL_get_name_arity()
and PL_is_functor().
- int PL_get_name_arity(term_t
+t, atom_t *name, size_t *arity)
- If t is compound or an atom, the functor name will be
assigned over name and the arity over arity
(either or both may be NULL). See also PL_get_compound_name_arity(), PL_get_functor()
and PL_is_functor().
- int PL_get_compound_name_arity(term_t
+t, atom_t *name, size_t *arity)
- If t is compound term, the functor name will be assigned over
name and the arity over arity (either or both may
be
NULL). This is the same as PL_get_name_arity(),
but this function fails if t is an atom.
- int PL_get_module(term_t
+t, module_t *module)
- If t is an atom, the system will look up or create the
corresponding module and assign an opaque pointer to it over module.
- int PL_get_arg(size_t
index, term_t +t, term_t -a)
- If t is compound and index is between 1 and arity
(inclusive), assign a with a term reference to the argument.
- int _PL_get_arg(size_t
index, term_t +t, term_t -a)
- Same as PL_get_arg(),
but no checking is performed, neither whether t is actually a
term nor whether index is a valid argument index.
- int PL_get_dict_key(atom_t
key, term_t +dict, term_t -value)
- If dict is a dict, get the associated value in value.
Fails silently if key does not appear in dict or
if if dict is not a dict.
0 
