These predicates convert between certain Prolog atomic values on one hand and lists of character codes (or, for atom_chars/2, characters) on the other. The Prolog atomic values can be atoms, characters (which are atoms of length 1), SWI-Prolog strings, as well as numbers (integers, floats and non-integer rationals).
The character codes, also known as code values, are integers. In SWI-Prolog, these integers are Unicode code points.bugOn Windows the range is limited to UCS-2, 0..65535.
To ease the pain of all text representation variations in the Prolog community, all SWI-Prolog predicates behave as flexible as possible. This implies the‘list-side’accepts both a character-code-list and a character-list and the‘atom-side’accepts all atomic types (atom, number and string). For example, the predicates atom_codes/2, number_codes/2 and name/2 behave the same in mode (+,-), i.e.,‘listwards’, from a constant to a list of character codes. When converting the other way around:
?- atom_codes(hello, X). X = [104, 101, 108, 108, 111].
The‘listwards’call to atom_codes/2 can also be written (functionally) using backquotes instead:
?- Cs = `hello`. Cs = [104, 101, 108, 108, 111].
Backquoted strings can be mostly found in the body of DCG rules that process lists of character codes.
Note that this is the default interpretation for backquotes. It can be changed on a per-module basis by setting the value of the Prolog flag back_quotes.
?- atom_chars(hello, X). X = [h, e, l, l, o]
syntax_error
exception is raised if CharList is instantiated to a ground,
proper list but does not represent a valid Prolog number.Following the ISO standard, the Prolog syntax for number allows for leading white space (including newlines) and does not allow for trailing white space.120ISO also allows for Prolog comments in leading white space. We--and most other implementations--believe this is incorrect. We also believe 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 also be achieved using format/3 and read_from_chars/2.
name(N,
"300"), 400 is N + 100 succeeds).This predicate is part of the Edinburgh tradition. It should be considered deprecated although, given its long tradition, it is unlikely to be removed from the system. It still has some value for converting input to a number or an atom (depending on the syntax). New code should consider the ISO predicates atom_codes/2, number_codes/2 or the SWI-Prolog predicate atom_number/2.
syntax_error exception is raised. Otherwise Term
is “written” on Atom using write_term/2
with the option
quoted(true). See also format/3, with_output_to/2
and
term_string/2.variable_names 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_term/2.
If Atom has no valid syntax, a syntax_error
exception is raised. If Atom only contains white space and/or
comments, an
syntax_error(end_of_string) exception is raised. New code
should use read_term_from_atom/3.?- atomic_concat(name, 42, X). X = name42.
atomic_list_concat(List,’’, Atom).?- atomic_list_concat([gnu, gnat], ', ', A). A = 'gnu, gnat'
The‘atomwards` transformation is usually called a string join operation in other programming languages.
The SWI-Prolog version of this predicate can also be used to split atoms by instantiating Separator and Atom as shown below. We kept this functionality to simplify porting old SWI-Prolog code where this predicate was called concat_atom/3. When used in mode (-,+,+), Separator must be a non-empty atom. See also split_string/4.
?- atomic_list_concat(L, -, 'gnu-gnat'). L = [gnu, gnat]
?- sub_atom(Atom, 0, _, _, Prefix).
Deprecated.Pick out a sub-atom of length 3 starting a 0-based index 2:
?- sub_atom(aaxyzbbb, 2, 3, After, SubAtom). After = 3, SubAtom = xyz.
The following example splits a string of the form <name>=<value> into the name part (an atom) and the value (a string).
name_value(String, Name, Value) :-
sub_atom(String, Before, _, After, "="),
!,
sub_atom(String, 0, Before, _, Name),
sub_atom(String, _, After, 0, Value).
This example defines a predicate that inserts a value at a position. Note that sub_string/5 is used here instead of sub_atom/5 to avoid the overhead of creating atoms for the intermediate results.
atom_insert(Str, Val, At, NewStr) :-
sub_string(Str, 0, At, A1, S1),
sub_string(Str, At, A1, _, S2),
atomic_list_concat([S1,Val,S2], NewStr).
On backtracking, matches are delivered in order left-to-right (i.e. Before increases monotonically):
?- sub_atom('xATGATGAxATGAxATGAx', Before, Length, After, 'ATGA').
Before = 1, Length = 4, After = 14 ;
Before = Length, Length = 4, After = 11 ;
Before = 9, Length = 4, After = 6 ;
Before = 14, Length = 4, After = 1 ;
false.
See also sub_string/5, the corresponding predicate for SWI-Prolog strings.