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 be copied immediately. Use with caution - you must be certain that no PL_*() function is called before you use the memory because if garbage collection occurs, the value of s won't be properly updated - BUF_STACK is safe, but slower. Also, some flags can cause BUF_DISCARDABLE to be treated as BUF_STACK. See section 12.4.14.

BUF_STACK

Data is stored on a stack. The older BUF_RING is an alias for BUF_STACK. BUF_STACK is the default if BUF_MALLOC is not specified. BUF_STACK should not be used inside a loop, unless it is within a (PL_STRINGS_MARK-PL_STRINGS_RELEASE). 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. If BUF_MALLOC is specified, BUF_STACK is ignored. See section 12.4.14.

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.