c('PL_get_chars')

Availability:C-language interface function

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 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 copied immediately.
BUF_STACK: Data is stored on a stack. The older BUF_RING is an alias for BUF_STACK. 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.
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.