3.18 Analysing and Constructing Atoms

These predicates convert between Prolog constants and lists of ASCII values. The predicates atom_chars/2, number_chars/2 and name/2 behave the same when converting from a constant to a list of ASCII values. When converting the other way around, atom_chars/2 will generate an atom, number_chars will generate a number or fail and name/2 will return a number if possible and an atom otherwise.

atom_chars(?Atom, ?String)

Convert between an atom and a list of ASCII values. If Atom is instantiated, if will be translated into a list of ASCII values and the result is unified with String. If Atom is unbound and String is a list of ASCII values, it will Atom will be unified with an atom constructed from this list.

atom_char(?Atom, ?ASCII)

Convert between character and ASCII value for a single character.

number_chars(?Number, ?String)

Similar to atom_chars/2, but converts between a number and its representation as a list of ASCII values. Fails silently if Atom is unbound and String does not describe a number.

name(?AtomOrInt, ?String)

String is a list of ASCII values describing Atom. Each of the arguments may be a variable, but not both. When String is bound to an ASCII value list describing an integer and Atom is a variable Atom will be unified with the integer value described by String (e.g. `name(N, "300"), 400 is N + 100' succeeds).

int_to_atom(+Int, +Base, -Atom)

Convert Int to an ASCII representation using base Base and unify the result with Atom. If Base <> 10 the base will be prepended to Atom. Base = 0 will try to interpret Int as an ASCII value and return 0'<c>. Otherwise 2 =<Base =< 36. Some examples are given below.

int_to_atom(45, 2, A)	-->	A = 2'101101
int_to_atom(97, 0, A)	-->	A = 0'a
int_to_atom(56, 10, A)	-->	A = 56

int_to_atom(+Int, -Atom)

Equivalent to int_to_atom(Int, 10, Atom).

term_to_atom(?Term, ?Atom)

Succeeds if Atom describes a term that unifies with Term. When Atom is instantiated Atom is converted and then unified with Term. Otherwise Term is ``written'' on Atom using write/1.

atom_to_term(+Atom, -Term, -Bindings)

Use Atom as input to read_variables/2 and return the read term in Term and the variable bindings in Bindings. Bindings is a list of Name = Var couples, thus providing access to the actual variable names. See also read_variables/2.

concat(?Atom1, ?Atom2, ?Atom3)

Atom3 forms the concatenation of Atom1 and Atom2. At least two of the arguments must be instantiated to atoms, integers or floating point numbers.

concat_atom(+List, -Atom)

List is a list of atoms, integers or floating point numbers. Succeeds if Atom can be unified with the concatenated elements of List. If List has exactly 2 elements it is equivalent to concat/3, allowing for variables in the list.

concat_atom(+List, +Separator, -Atom)

Creates an atom just like concat_atom/2, but inserts Separator between each pair of atoms. For example: ?- concat_atom([gnu, gnat], ', ', A). A = 'gnu, gnat'

atom_length(+Atom, -Length)

Succeeds if Atom is an atom of Length characters long. This predicate also works for integers and floats, expressing the number of characters output when given to write/1.

atom_prefix(+Atom, +Prefix)

Succeeds if Atom starts with the characters from Prefix. Its behaviour is equivalent to ?- concat(Prefix, _, Atom), but avoids the construction of an atom for the `remainder'.