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.
