c('PL_new_atom')

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
      - Atoms and functors
        
        PL_new_atom()
        
        PL_new_atom_mbchars()
        
        PL_atom_chars()
        
        PL_new_functor()
        
        PL_functor_name()
        
        PL_functor_arity()
        
        Atoms and atom garbage collection
- Packages

provide for communication using atoms and functors.

atom_t PL_new_atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced (see section 12.4.2.1). Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (atom_t)0.

The following atoms are provided as macros, giving access to the empty list symbol and the name of the list constructor. Prior to version 7, ATOM_nil is the same as PL_new_atom("[]") and ATOM_dot is the same as PL_new_atom("."). This is no longer the case in SWI-Prolog version 7.

atom_t ATOM_nil(A): tomic constant that represents the empty list. It is advised to use PL_get_nil(), PL_put_nil() or PL_unify_nil() where applicable.
atom_t ATOM_dot(A): tomic constant that represents the name of the list constructor. The list constructor itself is created using PL_new_functor(ATOM_dot,2). It is advised to use PL_get_list(), PL_put_list() or PL_unify_list() where applicable.

atom_t PL_new_atom_mbchars(int rep, size_t len, const char *s)

This function generalizes PL_new_atom() and PL_new_atom_nchars() while allowing for multiple encodings. The rep argument is one of REP_ISO_LATIN_1, REP_UTF8 or REP_MB. If len is (size_t)-1, it is computed from s using strlen(). Raises an exception if s violates rep and returns (atom_t)0. For other error conditions, see PL_new_atom().

int PL_atom_mbchars(atom_t atom, size_t len, char *s, unsigned int flags)

This function generalizes fetching the text associated with an atom. The encoding depends on the flags REP_UTF8, REP_MB or REP_ISO_LATIN_1. Storage is defined by the BUF_* flags as described with PL_get_chars(). The flag CVT_EXCEPTION defines whether or not the function fails silently or raises a Prolog exception. This function may fail because atom is not a text atom but a blob (see section 12.4.9), conversion to the requested encoding is not possible or a resource error occurs.

const char* PL_atom_chars(atom_t atom)

Deprecated. This function returns a pointer to the content represented by the atom or blob regardless of its type. New code that uses blobs should use the blob functions such as PL_blob_data() to get a pointer to the content, the size of the content, and the type of the content. Most applications that need to get text from a term_t handle should use PL_atom_nchars(), PL_atom_wchars(), or PL_atom_mbchars(). If it is known that atom is a classical Prolog text atom, one can use PL_atom_nchars() to obtain the C string and its length (for ISO-Latin-1 atoms) or PL_atom_wchars() to obtain a C wide string (wchar_t).

functor_t PL_new_functor(atom_t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session. Future versions may garbage collect functors as part of atom garbage collection. Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (atom_t)0.

atom_t PL_functor_name(functor_t f)

Return an atom representing the name of the given functor.

size_t PL_functor_arity(functor_t f)

Return the arity of the given functor.