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.19.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().
- 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 of character codes.
- CVT_INTEGER
- Convert if term is an integer.
- CVT_RATIONAL
- Convert if term is an rational number. The number is 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 or float. Equivalent
to
CVT_INTEGER|CVT_RATIONAL|CVT_FLOAT
- CVT_ATOMIC
- Convert if term is atomic.
- CVT_VARIABLE
- Convert variable to print-name
- 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_WRITE_CANONICAL
- As
CVT_WRITE, but using write_canonical/2.
- CVT_WRITEQ
- As
CVT_WRITE, but using writeq/2.
- CVT_ALL
- Convert if term is any of the above, except for
CVT_VARIABLE
and
CVT_WRITE*.
- 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.
