Did you know ... Search Documentation:
Reading data from a term

12.4.4.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. 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.

bool 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().
bool 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.
bool 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 be copied immediately. Use with caution - you must be certain that no PL_*() function is called before you use the memory because if garbage collection occurs, the value of s won't be properly updated - BUF_STACK is safe, but slower. Also, some flags can cause BUF_DISCARDABLE to be treated as BUF_STACK. See section 12.4.14.
BUF_STACK
Data is stored on a stack. The older BUF_RING is an alias for BUF_STACK. BUF_STACK is the default if BUF_MALLOC is not specified. BUF_STACK should not be used inside a loop, unless it is within a (PL_STRINGS_MARK-PL_STRINGS_RELEASE). 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. If BUF_MALLOC is specified, BUF_STACK is ignored. See section 12.4.14.
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.
bool 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.
bool 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().
bool 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().
bool 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().
bool 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().
bool 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.
bool PL_get_bool(term_t +t, int *val)
bool PL_get_stdbool(term_t +t, bool *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, 0 and are also accepted. PL_get_stdbool_ex() deals with the C11 bool type while PL_get_bool_ex() targetted C standard versions before the introduction of bool.
bool 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.
bool 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.
bool 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().
bool 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().
bool 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.
bool 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.
bool 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. Returns FALSE if t is not a compound or index is out of range (zero or higher than the arity of the compound). This function never raises a Prolog exception.
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. This is faster, but invalid usage leads to undefined behaviour.
bool PL_get_arg_values(term_t +t, size_t from, size_t count, pl_value_t *values, unsigned int flags)
Fill values with the arguments from ... from+count-1 of the compound term t, where the first argument is 1. This is intended for C code that reads many small terms, for example coordinates, as it avoids creating a term_t and calling an API function for each argument. The type pl_value_t is defined as below. 
typedef struct pl_value
{ uint64_t type   : 8;          /* PL_VARIABLE, PL_ATOM, ... */
  uint64_t length : 56;         /* length of value.s */
  union
  { int64_t   i;                /* PL_INT64 */
    double    f;                /* PL_FLOAT; numbers if PL_AS_FLOAT */
    atom_t    a;                /* PL_ATOM, PL_NIL, PL_BLOB */
    functor_t t;                /* PL_TERM, PL_LIST_PAIR, PL_DICT */
    char     *s;                /* text (see CVT_*, REP_*, BUF_*) */
  } value;
} pl_value_t;

The field type is the type of the argument and is one of PL_VARIABLE, PL_ATOM, PL_NIL, PL_BLOB, PL_INT64, PL_INTEGER (an integer that does not fit in 64 bits), PL_RATIONAL, PL_FLOAT, PL_STRING, PL_TERM, PL_LIST_PAIR or PL_DICT. The type and flags decide which member of value is filled. Text is stored in s with its length in bytes in length, using the REP_* and BUF_* flags as PL_get_nchars(). The following flags decide on the conversion:

CVT_ATOM
Represent a text atom as text. Without, a holds the atom handle. The empty list and blobs always use a.
CVT_INTEGER
Represent an integer that does not fit in 64 bits as decimal text. Using CVT_XINTEGER, the text is hexadecimal.
CVT_RATIONAL
Represent a rational number or large integer as text, e.g., 1r3.
PL_AS_FLOAT
Store all numbers as a double in f. The field type still tells the type of the number. This flag is an alias for CVT_FLOAT. The function fails or, using CVT_EXCEPTION, raises a float overflow error if a number cannot be represented as a float.
CVT_EXCEPTION
Raise an exception if the function fails due to an argument that cannot be represented. A large integer or rational number that is not converted raises a representation or type error.

Strings are always represented as text. Floats are always represented as f. Variables and compound terms are never converted. For compound terms, t holds the functor.

The function fails silently if from and count are not a valid range of arguments. If t is not compound, it fails or raises a type error if CVT_EXCEPTION is given. If the function fails using BUF_MALLOC, no text needs to be freed.

bool 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.

Tags are associated to your profile if you are logged in
Tags:
Stefan Kral said (2015-12-12T05:06:03):0 upvotes 0 0 downvotes
Picture of user Stefan Kral.

The info on PL_get_int64(term_t +t, int64_t *i) includes the following text which doesn't sound right to me:

"Currently all Prolog integers can be represented using this type, but this might change if SWI-Prolog introduces unbounded integers."

Possible documentation relict?!

Cheers, Stefan.