Analysing and constructing atoms

These predicates convert between Prolog constants and lists of ASCII values. The predicates atom_codes2, number_codes2 and name2 behave the same when converting from a constant to a list of ASCII values. When converting the other way around, atom_codes2 will generate an atom, number_codes2 will generate a number or exception and name2 will return a number if possible and an atom otherwise.

The ISO standard defines atom_chars2 to describe the `broken-up' atom as a list of one-character atoms instead of a list of codes. Upto version 3.2.x, SWI-Prolog's atom_chars2 behaved, compatible to Quintus and SICStus Prolog, like atom_codes. As of 3.3.x SWI-Prolog atom_codes2 and atom_chars2 are compliant to the ISO standard.

To ease the pain of all variations in the Prolog community, all SWI-Prolog predicates behave as flexible as possible. This implies the `list-side' accepts either a code-list or a char-list and the `atom-side' accept all atomic types (atom, number and string).

atom_codes2?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_chars2?Atom, ?CharList As atom_codes2, but CharList is a list of one-character atoms rather than a list of ASCII values^2.9.

char_code2?Atom, ?ASCII Convert between character and ASCII value for a single character.^2.10 number_chars2?Number, ?CharList Similar to atom_chars2, but converts between a number and its representation as a list of one-character atoms. Fails with a representation_error if Number is unbound and CharList does not describe a number. number_codes2?Number, ?CodeList As number_chars2, but converts to a list of character codes (normally ASCII values) rather than one-character atoms. In the mode -, +, both predicates behave identically to improve handling of non-ISO source. name2?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_atom3+Int, +Base, -Atom Convert Int to an ASCII representation using base Base and unify the result with Atom. If $\arg{Base} \not= 10$ the base will be prepended to Atom. $\arg{Base} = 0$ will try to interpret Int as an ASCII value and return 0'c. Otherwise $2 \leq \arg{Base} \leq 36$. Some examples are given below.

int_to_atom(45, 2, A)	$\longrightarrow$	$A = 2'101101$
int_to_atom(97, 0, A)	$\longrightarrow$	$A = 0'a$
int_to_atom(56, 10, A)	$\longrightarrow$	$A = 56$

int_to_atom2+Int, -Atom Equivalent to int_to_atom(Int, 10, Atom). term_to_atom2?Term, ?Atom Succeeds if Atom describes a term that unifies with Term. When Atom is instantiated Atom is converted and then unified with Term. If Atom has no valid syntax, a syntax_error exception is raised. Otherwise Term is ``written'' on Atom using write1. atom_to_term3+Atom, -Term, -Bindings Use Atom as input to read_term2 using the option variable_names and return the read term in Term and the variable bindings in Bindings. Bindings is a list of $\arg{Name} = \arg{Var}$ couples, thus providing access to the actual variable names. See also read_term2. If Atom has no valid syntax, a syntax_error exception is raised. atom_concat3?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. For ISO compliance, the instantiation-pattern -, -, + is allowed too, non-deterministically splitting the 3-th argument into two parts (as append3 does for lists). See also string_concat3. concat_atom2+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 atom_concat3, allowing for variables in the list. concat_atom3+List, +Separator, -Atom Creates an atom just like concat_atom2, but inserts Separator between each pair of atoms. For example:

atom_length2+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 write1. atom_prefix2+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'. sub_atom5+Atom, ?Before, ?Len, ?After, ?Sub ISO predicate for breaking atoms. It maintains the following relation: Sub is a sub-atom of Atom that starts at Before, has Len characters and Atom contains After characters after the match.

The implementation minimalises non-determinism and creation of atoms. This is a very flexible predicate that can do search, prefix- and suffix-matching, etc.