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.
- 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 live-time 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, int *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 save 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_RINGimplies, if the data is not static (as from an atom), that the data is copied to the next buffer from a ring of 16 buffers. This is a convenient way of converting multiple arguments passed to a foreign predicate to C-strings. 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.
- Convert if term is an atom.
- Convert if term is a string.
- Convert if term is a list of of character codes.
- Convert if term is an integer.
- Convert if term is a float. The characters returned are the same as write/1 would write for the floating point number.
- Convert if term is an integer or float.
- Convert if term is atomic.
- Convert variable to print-name
- Convert any term that is not converted by any of the other flags using
CVT_WRITE, but using write_canonical/2.
- Convert if term is any of the above, except for
- If conversion fails due to a type error, raise a Prolog type error exception in addition to failure
- Data must copied immediately
- Data is stored in a ring of buffers
- 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.
- 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.
- Convert the text to a UTF-8 string. This works for all text.
- 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().
- 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().
- int PL_get_int64(term_t +t, int64_t *i)
- If t is a Prolog integer or float that can be represented as
int64_t, assign its value over i. Currently all Prolog integers can be represented using this type, but this might change if SWI-Prolog introduces unbounded integers.
- 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
false, set val to the C constant
FALSEand return success, otherwise return failure.
- int PL_get_pointer(term_t +t, void **ptr)
- In the current system, pointers are represented by Prolog integers, but need some manipulation to make sure they do not get truncated due to the limited Prolog integer range. PL_put_pointer() and PL_get_pointer() guarantee pointers in the range of malloc() are handled without truncating.
- int PL_get_float(term_t +t, double *f)
- If t is a float or integer, its value is assigned over f.
- 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, int *arity)
- If t is compound or an atom, the functor name will be assigned over name and the arity over arity. See also PL_get_functor() and PL_is_functor().
- 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(int 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(int 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.