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_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 or 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.13.
- 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.
