These functions will take an SP_term_ref and convert it to C data.
They return zero if the conversion fails, and a nonzero value otherwise,
and (except the last two) store the C data in output arguments.
Note that here, the term chars
refers to a code-list,
rather than to a char-list:
int SP_get_integer(SP_term_ref t, long *l)
*l
the C long
corresponding to a Prolog
number. The value must fit in *l
for the operation to
succeed.
For numbers too large to fit in a long
you can use
SP_get_integer_bytes()
, below.
int SP_get_float(SP_term_ref t, double *d)
*d
the C double
corresponding to a Prolog
number.
int SP_get_atom(SP_term_ref t, SP_atom *a)
*a
the canonical representation of a Prolog
atom.
int SP_get_string(SP_term_ref t, char **name)
*name
a pointer to the encoded string
representing the name of a Prolog atom. This string must
not be modified.
int SP_get_address(SP_term_ref t, void **pointer)
*pointer
a C pointer from a Prolog term.
int SP_get_list_chars(SP_term_ref t, char **s)
*s
a zero-terminated array containing an encoded
string that corresponds to the given Prolog code-list. The array
is subject to reuse by other support functions, so if the value is going
to be used on a more than temporary basis, it must be moved elsewhere.
int SP_get_list_n_chars(SP_term_ref t, SP_term_ref tail, size_t n, size_t *w, char *s)
s
the encoded string representing the
character codes in the initial elements of list t
, so
that at most n
bytes are used. The number of bytes actually
written is assigned to *w
. tail
is set to the remainder
of the list. The array s
must have room for at least
n
bytes.
int SP_get_list_n_bytes(SP_term_ref t, SP_term_ref tail, size_t n, size_t *w, unsigned char *s)
s
the initial elements of
t
, which should hold a list of integers in the range [0,255], so
that at most n
bytes are used. The number of bytes actually
written is assigned to *w
. tail
is set to the remainder
of the list. The array s
must have room for at least
n
bytes.
int SP_get_integer_bytes(SP_term_ref tr, void *buf, size_t *pbuf_size, int native)
When called, tr
should refer to a Prolog integer; floating point
values are not accepted. *pbuf_size
should point at the size of
the buffer buf
, which will receive the result.
In the following, assume that the integer referred to by tr
requires
a minimum of size bytes to store (in twos-complement
representation).
tr
does not refer to a Prolog integer, zero is returned and
the other arguments are ignored.
*pbuf_size
is less than size, then *pbuf_size
is
updated to size and zero is returned. The fact that
*pbuf_size
has changed can be used to distinguish insufficient
buffer size from other possible errors. By calling
SP_get_integer_bytes()
with *pbuf_size
set to zero, you can
determine the buffer size needed; in this case, buf
is ignored.
*pbuf_size
is set to size.
native
is zero, buf
is filled with the twos complement
representation of the integer, with the least significant bytes stored
at lower indices in buf
. Note that all of buf
is filled, even
though only size bytes was needed.
native
is non-zero, buf
is assumed to point at a native
*pbuf_size
byte integral type. On most platforms, native integer
sizes of two (16-bit), four (32 bit) and eight (64 bytes) bytes are
supported. Note that *pbuf_size == 1
, which would correspond to
signed char
, is not supported with native
.
native
, zero is returned.
The following example gets a Prolog integer into a (presumably 64 bit)
long long
C integer.
{ long long x; // C99, GCC supports this size_t sz = sizeof x; if (!SP_get_integer_bytes(tr, &x, &sz, 1/* native */)) .. error handling .. .. use x .. // sz may have decreased }
int SP_get_number_chars(SP_term_ref t, char **s)
*s
a zero-terminated array of characters
corresponding to the printed representation of a Prolog number. The
array is subject to reuse by other support functions, so if the value is
going to be used on a more than temporary basis, it must be moved
elsewhere.
int SP_get_functor(SP_term_ref t, SP_atom *name, int *arity)
*name
and *arity
the canonical representation
and arity of the principal functor of a Prolog compound
term. If the value of t
is an atom, then that atom
is assigned to *name
and 0 is assigned to *arity
. This is
similar to calling functor/3
with the first argument
bound to a compound term or an atom and the second and
third arguments unbound.
int SP_get_list(SP_term_ref t, SP_term_ref head, SP_term_ref tail)
head
and tail
the head and tail of
a Prolog list.
int SP_get_arg(int i, SP_term_ref t, SP_term_ref arg)
arg
the i
:th argument of a Prolog
compound term. This is similar to calling arg/3
with the
third argument unbound.