c('PL_get_arg_values')

Availability:C-language interface function

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.