4.22
Analysing and Constructing Atoms
These predicates convert between Prolog constants and lists of character codes. The predicates atom codes/2, number codes/2andname/2behave the same when converting from a con- stant to a list of character codes. When converting the other way around, atom codes/2 will generate an atom,number codes/2will generate a number or exception andname/2will return a number if possible and an atom otherwise.
The ISO standard defines atom chars/2 to describe the ‘broken-up’ atom as a list of one- character atoms instead of a list of codes. Up to version 3.2.x, SWI-Prolog’s atom chars/2 behaved like atom codes, compatible with Quintus and SICStus Prolog. As of 3.3.x, SWI-Prolog atom codes/2andatom chars/2are 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’ accepts all atomic types (atom, number and string).
atom codes(?Atom, ?String) [ISO]
Convert between an atom and a list of character codes. IfAtomis instantiated, it will be trans- lated into a list of character codes and the result is unified withString. IfAtomis unbound and Stringis a list of character codes,Atomwill be unified with an atom constructed from this list.
atom chars(?Atom, ?CharList) [ISO]
Asatom codes/2, butCharListis a list of one-character atoms rather than a list of character codes.66
?- atom_chars(hello, X). X = [h, e, l, l, o]
char code(?Atom, ?Code) [ISO]
Convert between character and character code for a single character.67
number chars(?Number, ?CharList) [ISO]
Similar toatom chars/2, but converts between a number and its representation as a list of one-character atoms. Fails with asyntax errorifNumberis unbound orCharListdoes not describe a number. Following the ISO standard, it allows for leadingwhite space (including newlines) and does not allow fortrailingwhite space.68
number codes(?Number, ?CodeList) [ISO]
As number chars/2, but converts to a list of character codes rather than one-character atoms. In the mode (-, +), both predicates behave identically to improve handling of non-ISO source.
66Up to version 3.2.x,atom chars/2behaved as the currentatom codes/2. The current definition is compliant
with the ISO standard.
67This is also calledatom char/2in older versions of SWI-Prolog as well as some other Prolog implementations. The
atom char/2predicate is available from the librarybackcomp.pl
68
ISO also allows for Prolog comments in leading white space. We–and most other implementations–believe this is incorrect. We also beleive it would have been better not to allow for white space, or to allow for both leading and trailing white space. Prolog syntax-based conversion can be achieved usingformat/3andread from chars/2.
atom number(?Atom, ?Number)
Realises the popular combination of atom codes/2 and number codes/2 to convert between atom and number (integer or float) in one predicate, avoiding the intermediate list. Unlike the ISOnumber codes/2predicates,atom number/2fails silently in mode (+,-) if Atomdoes not represent a number.69 See alsoatomic list concat/2for assembling an atom from atoms and numbers.
name(?Atomic, ?CodeList)
CodeList is a list of character codes representing the same text asAtomic. Each of the argu- ments may be a variable, but not both. When CodeListdescribes an integer or floating point number andAtomic is a variable,Atomicwill be unified with the numeric value described by CodeList (e.g., name(N, "300"), 400 is N + 100 succeeds). If CodeList is not a representation of a number, Atomic will be unified with the atom with the name given by the character code list. WhenAtomicis an atom or number, the unquoted print representation of it as a character code list will be unified withCodeList.
Note that it is not possible to produce the atom ’300’ using name/2, and that name(300, CodeList), name(’300’, CodeList) succeeds. For these reasons, new code should consider using the ISO predicatesatom codes/2ornumber codes/2.70 See alsoatom number/2.
term to atom(?Term, ?Atom)
True if Atom describes a term that unifies with Term. When Atom is instantiated, Atom is parsed and the result unified with Term. If Atom has no valid syntax, a syntax error exception is raised. Otherwise Term is “written” on Atom using write term/2 with the optionquoted(true). See alsoformat/3,with output to/2andterm string/2.
atom to term(+Atom, -Term, -Bindings) [deprecated]
Use Atom as input to read term/2 using the option variable names and return the read term in Termand the variable bindings in Bindings. Bindings is a list of Name = Var couples, thus providing access to the actual variable names. See also read term/2. If Atom has no valid syntax, a syntax error exception is raised. New code should use read term from atom/3.
atom concat(?Atom1, ?Atom2, ?Atom3) [ISO]
Atom3forms the concatenation ofAtom1andAtom2. At least two of the arguments must be instantiated to atoms. This predicate also allows for the mode (-,-,+), non-deterministically splitting the 3rd argument into two parts (asappend/3does for lists). SWI-Prolog allows for atomic arguments. Portable code must use atomic concat/3 if non-atom arguments are involved.
atomic concat(+Atomic1, +Atomic2, -Atom)
Atomrepresents the text after converting Atomic1andAtomic2to text and concatenating the result:
69
Versions prior to 6.1.7 raise a syntax error, compliant tonumber codes/2
70
Unfortunately, the ISO predicates provide no neat way to check that a string can be interpreted as a number. The most sensible way is to usecatch/3to catch the exception fromnumber codes/2; however, this is both slow and cumbersome. We consider making, e.g.,number codes(N, "abc")fail silently in future versions.
4.22. ANALYSING AND CONSTRUCTING ATOMS 167
?- atomic_concat(name, 42, X). X = name42.
atomic list concat(+List, -Atom) [commons]
List is a list of strings, atoms, integers or floating point numbers. Succeeds ifAtom can be unified with the concatenated elements ofList. Equivalent toatomic list concat(List, ”, Atom).
atomic list concat(+List, +Separator, -Atom) [commons]
Creates an atom just likeatomic list concat/2, but insertsSeparatorbetween each pair of inputs. For example:
?- atomic_list_concat([gnu, gnat], ’, ’, A). A = ’gnu, gnat’
The SWI-Prolog version of this predicate can also be used to split atoms by instantiatingSepa- ratorandAtomas shown below. We kept this functionality to simplify porting old SWI-Prolog code where this predicate was calledconcat atom/3. When used in mode (-,+,+),Separator must be a non-empty atom. See alsosplit string/4.
?- atomic_list_concat(L, -, ’gnu-gnat’). L = [gnu, gnat]
atom length(+Atom, -Length) [ISO]
True if Atom is an atom of Length characters. The SWI-Prolog version accepts all atomic types, as well as code-lists and character-lists. New code should avoid this feature and use write length/3to get the number of characters that would be written if the argument was handed towrite term/3.
atom prefix(+Atom, +Prefix) [deprecated]
True if Atom starts with the characters from Prefix. Its behaviour is equivalent to ?- sub atom(Atom, 0, , , Prefix). Deprecated.
sub atom(+Atom, ?Before, ?Len, ?After, ?Sub) [ISO]
ISO predicate for breaking atoms. It maintains the following relation: Subis a sub-atom of Atom that starts at Before, has Len characters, and Atom contains After characters after the match.
?- sub_atom(abc, 1, 1, A, S). A = 1, S = b
The implementation minimises non-determinism and creation of atoms. This is a flexible pred- icate that can do search, prefix- and suffix-matching, etc.
sub atom icasechk(+Haystack, ?Start, +Needle) [semidet] True when Needle is a sub atom of Haystack starting at Start. The match is ‘half case in- sensitive’, i.e., uppercase letters in Needle only match themselves, while lowercase letters in Needlematch case insensitively. Startis the first 0-based offset insideHaystackwhereNeedle matches.71