12.4.3.3 Exchanging text using length and string

All internal text representation in SWI-Prolog is represented using char * plus length and allow for 0-bytes in them. The foreign library supports this by implementing a *_nchars() function for each applicable *_chars() function. Below we briefly present the signatures of these functions. For full documentation consult the *_chars() function.

int PL_get_atom_nchars(term_t t, size_t *len, char **s)

See PL_get_atom_chars().

int PL_get_list_nchars(term_t t, size_t *len, char **s)

See PL_get_list_chars().

int PL_get_nchars(term_t t, size_t *len, char **s, unsigned int flags)

See PL_get_chars(). The len pointer may be NULL.

int PL_put_atom_nchars(term_t t, size_t len, const char *s)

See PL_put_atom_chars().

int PL_put_string_nchars(term_t t, size_t len, const char *s)

See PL_put_string_chars().

int PL_put_list_ncodes(term_t t, size_t len, const char *s)

See PL_put_list_codes().

int PL_put_list_nchars(term_t t, size_t len, const char *s)

See PL_put_list_chars().

int PL_unify_atom_nchars(term_t t, size_t len, const char *s)

See PL_unify_atom_chars().

int PL_unify_string_nchars(term_t t, size_t len, const char *s)

See PL_unify_string_chars().

int PL_unify_list_ncodes(term_t t, size_t len, const char *s)

See PL_unify_codes().

int PL_unify_list_nchars(term_t t, size_t len, const char *s)

See PL_unify_list_chars().

In addition, the following functions are available for creating and inspecting atoms:

atom_t PL_new_atom_nchars(size_t len, const char *s)

Create a new atom as PL_new_atom(), but using the given length and characters. If len is (size_t)-1, it is computed from s using strlen(). See PL_new_atom() for error handling.

const char * PL_atom_nchars(atom_t a, size_t *len)

Extract the text and length of an atom. If you do not need the length, pass NULL as the value of len. If PL_atom_nchars() is called for a blob, NULL is returned.