- Documentation
- Reference manual
- Foreign Language Interface
- The Foreign Include File
- Analysing Terms via the Foreign Interface
- Reading data from a term
- PL_get_atom()
- PL_get_atom_chars()
- PL_get_string_chars()
- PL_get_chars()
- PL_get_list_chars()
- PL_get_integer()
- PL_get_long()
- PL_get_int64()
- PL_get_uint64()
- PL_get_intptr()
- PL_get_bool()
- PL_get_stdbool()
- PL_get_pointer()
- PL_get_float()
- PL_get_functor()
- PL_get_name_arity()
- PL_get_compound_name_arity()
- PL_get_module()
- PL_get_arg()
- PL_get_arg_values()
- PL_get_dict_key()
- Reading data from a term
- Analysing Terms via the Foreign Interface
- The Foreign Include File
- Foreign Language Interface
- Packages
- Reference manual
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,
aholds the atom handle. The empty list and blobs always usea. - 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
doubleinf. The fieldtypestill tells the type of the number. This flag is an alias forCVT_FLOAT. The function fails or, usingCVT_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.