5.6.3.2 Reading data from a term

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_string_from_atom() 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.

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(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 converted and the second how the argument is stored. Below is a specification of these constants. BUF_RING implies, if the data is not static (as from an atom), the data is copied to the next buffer from a ring of four (4) 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 free() when not needed any longer.

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 integers between 1 and 255
CVT_INTEGER	Convert if term is an integer (using%d)
CVT_FLOAT	Convert if term is a float (using%f)
CVT_NUMBER	Convert if term is a integer or float
CVT_ATOMIC	Convert if term is atomic
CVT_VARIABLE	Convert variable to print-name
CVT_ALL	Convert if term is any of the above, except for variables
BUF_DISCARDABLE	Data must copied immediately
BUF_RING	Data is stored in a ring of buffers
BUF_MALLOC	Data is copied to a new buffer returned by malloc(3)

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 no 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, assign its value over i. Note that Prolog integers have limited value-range. If t is a floating point number that can be represented as a long, this function succeeds as well.

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()/PL_get_pointer() guarantees 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 lookup 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 (including), assign a with a term-reference to the argument.