/usr/lib/swi-prolog/doc/Manual/manipatom.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 4.20</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="manipterm.html">
<LINK REL=next HREF="chartype.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="manipterm.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="chartype.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.20"><SPAN class="sec-nr">4.20</SPAN> <SPAN class="sec-title">Analysing 
and Constructing Atoms</SPAN></A></H2>

<A NAME="sec:manipatom"></A>

<P>These predicates convert between Prolog constants and lists of 
character codes. The predicates <A NAME="idx:atomcodes2:935"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A>, <A NAME="idx:numbercodes2:936"></A><A class="pred" href="manipatom.html#number_codes/2">number_codes/2</A> 
and <A NAME="idx:name2:937"></A><A class="pred" href="manipatom.html#name/2">name/2</A> 
behave the same when converting from a constant to a list of character 
codes. When converting the other way around, <A NAME="idx:atomcodes2:938"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A> 
will generate an atom, <A NAME="idx:numbercodes2:939"></A><A class="pred" href="manipatom.html#number_codes/2">number_codes/2</A> 
will generate a number or exception and <A NAME="idx:name2:940"></A><A class="pred" href="manipatom.html#name/2">name/2</A> 
will return a number if possible and an atom otherwise.

<P>The ISO standard defines <A NAME="idx:atomchars2:941"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A> 
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 <A NAME="idx:atomchars2:942"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A> 
behaved, compatible with Quintus and SICStus Prolog, like atom_codes. As 
of 3.3.x SWI-Prolog
<A NAME="idx:atomcodes2:943"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A> 
and <A NAME="idx:atomchars2:944"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A> 
are compliant to the ISO standard.

<P>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).

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="atom_codes/2"><STRONG>atom_codes</STRONG>(<VAR>?Atom, 
?String</VAR>)</A></DT>
<DD class="defbody">
Convert between an atom and a list of character codes. If
<VAR>Atom</VAR> is instantiated, if will be translated into a list of 
character codes and the result is unified with <VAR>String</VAR>. If <VAR>Atom</VAR> 
is unbound and <VAR>String</VAR> is a list of character codes, it will
<VAR>Atom</VAR> will be unified with an atom constructed from this list.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="atom_chars/2"><STRONG>atom_chars</STRONG>(<VAR>?Atom, 
?CharList</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:atomcodes2:945"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A>, 
but <VAR>CharList</VAR> is a list of one-character atoms rather than a 
list of character codes<SUP class="fn">53<SPAN class="fn-text">Up-to 
version 3.2.x, <A NAME="idx:atomchars2:946"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A> 
behaved as the current <A NAME="idx:atomcodes2:947"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A>. 
The current definition is compliant with the ISO standard</SPAN></SUP>.

<PRE class="code">
?- atom_chars(hello, X).

X = [h, e, l, l, o]
</PRE>

</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="char_code/2"><STRONG>char_code</STRONG>(<VAR>?Atom, 
?Code</VAR>)</A></DT>
<DD class="defbody">
Convert between character and character code for a single character.<SUP class="fn">54<SPAN class="fn-text">This 
is also called atom_char/2 in older versions of SWI-Prolog as well as 
some other Prolog implementations. The atom_char/2 predicate is 
available from the library <CODE>backcomp.pl</CODE></SPAN></SUP></DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="number_chars/2"><STRONG>number_chars</STRONG>(<VAR>?Number, 
?CharList</VAR>)</A></DT>
<DD class="defbody">
Similar to <A NAME="idx:atomchars2:948"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A>, 
but converts between a number and its representation as a list of 
one-character atoms. Fails with a
<CODE>syntax_error</CODE> if <VAR>Number</VAR> is unbound and <VAR>CharList</VAR> 
does not describe a number. Following the ISO standard, it allows for
<EM>leading</EM> white space (including newlines) and does not allow for
<EM>trailing</EM> white space.<SUP class="fn">55<SPAN class="fn-text">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 using <A NAME="idx:format3:949"></A><A class="pred" href="format.html#format/3">format/3</A> 
and <A NAME="idx:readfromchars2:950"></A><A class="pred" href="charsio.html#read_from_chars/2">read_from_chars/2</A>.</SPAN></SUP></DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="number_codes/2"><STRONG>number_codes</STRONG>(<VAR>?Number, 
?CodeList</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:numberchars2:951"></A><A class="pred" href="manipatom.html#number_chars/2">number_chars/2</A>, 
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.</DD>
<DT class="pubdef"><A NAME="atom_number/2"><STRONG>atom_number</STRONG>(<VAR>?Atom, 
?Number</VAR>)</A></DT>
<DD class="defbody">
Realises the popular combination of <A NAME="idx:atomcodes2:952"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A> 
and <A NAME="idx:numbercodes2:953"></A><A class="pred" href="manipatom.html#number_codes/2">number_codes/2</A> 
to convert between atom and number (integer or float) in one predicate, 
avoiding the intermediate list. Calling in mode +,- to convert numbers 
represented as atoms is often good style. Converting numbers to atoms, 
which in turn are assembled into larger units before communication them 
to the outside world is bad style. Consider using streams or
<A NAME="idx:withoutputto2:954"></A><A class="pred" href="IO.html#with_output_to/2">with_output_to/2</A> 
to reduce the number of expensive intermediate atoms.</DD>
<DT class="pubdef"><A NAME="name/2"><STRONG>name</STRONG>(<VAR>?AtomOrInt, 
?String</VAR>)</A></DT>
<DD class="defbody">
<VAR>String</VAR> is a list of character codes representing the same 
text as <VAR>Atom</VAR>. Each of the arguments may be a variable, but 
not both. When <VAR>String</VAR> is bound to an character code list 
describing an integer and <VAR>Atom</VAR> is a variable <VAR>Atom</VAR> 
will be unified with the integer value described by <VAR>String</VAR> 
(e.g., `<CODE>name(N, "300"), 400 is N + 100</CODE>' succeeds). New code 
should consider using the ISO predicates <A NAME="idx:atomcodes2:955"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A> 
or <A NAME="idx:numbercodes2:956"></A><A class="pred" href="manipatom.html#number_codes/2">number_codes/2</A>.<SUP class="fn">56<SPAN class="fn-text">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 use <A NAME="idx:catch3:957"></A><A class="pred" href="exception.html#catch/3">catch/3</A> 
to catch the exception from <A NAME="idx:numbercodes2:958"></A><A class="pred" href="manipatom.html#number_codes/2">number_codes/2</A>, 
however this is both slow and cumbersome.</SPAN></SUP></DD>
<DT class="pubdef"><A NAME="term_to_atom/2"><STRONG>term_to_atom</STRONG>(<VAR>?Term, 
?Atom</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Atom</VAR> describes a term that unifies with <VAR>Term</VAR>. 
When
<VAR>Atom</VAR> is instantiated <VAR>Atom</VAR> is converted and then 
unified with
<VAR>Term</VAR>. If <VAR>Atom</VAR> has no valid syntax, a <CODE>syntax_error</CODE> 
exception is raised. Otherwise <VAR>Term</VAR> is ``written'' on <VAR>Atom</VAR> 
using <A NAME="idx:writeterm2:959"></A><A class="pred" href="termrw.html#write_term/2">write_term/2</A> 
with the option <CODE>quoted(true)</CODE>. See also
<A NAME="idx:format3:960"></A><A class="pred" href="format.html#format/3">format/3</A> 
and <A NAME="idx:withoutputto2:961"></A><A class="pred" href="IO.html#with_output_to/2">with_output_to/2</A>.</DD>
<DT class="pubdef"><A NAME="atom_to_term/3"><STRONG>atom_to_term</STRONG>(<VAR>+Atom, 
-Term, -Bindings</VAR>)</A></DT>
<DD class="defbody">
Use <VAR>Atom</VAR> as input to <A NAME="idx:readterm2:962"></A><A class="pred" href="termrw.html#read_term/2">read_term/2</A> 
using the option
<CODE>variable_names</CODE> and return the read term in <VAR>Term</VAR> 
and the variable bindings in <VAR>Bindings</VAR>. <VAR>Bindings</VAR> is 
a list of
<VAR><VAR>Name</VAR> = <VAR>Var</VAR></VAR> couples, thus providing 
access to the actual variable names. See also <A NAME="idx:readterm2:963"></A><A class="pred" href="termrw.html#read_term/2">read_term/2</A>. 
If <VAR>Atom</VAR> has no valid syntax, a <CODE>syntax_error</CODE> 
exception is raised.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="atom_concat/3"><STRONG>atom_concat</STRONG>(<VAR>?Atom1, 
?Atom2, ?Atom3</VAR>)</A></DT>
<DD class="defbody">
<VAR>Atom3</VAR> forms the concatenation of <VAR>Atom1</VAR> and <VAR>Atom2</VAR>. 
At least two of the arguments must be instantiated to atoms. This 
predicate also allows for the mode (-,-,+), non-deterministically 
splitting the 3-th argument into two parts (as <A NAME="idx:append3:964"></A><A class="pred" href="lists.html#append/3">append/3</A> 
does for lists). SWI-Prolog allows for atomic arguments. Portable code 
must use <A NAME="idx:atomicconcat3:965"></A><A class="pred" href="manipatom.html#atomic_concat/3">atomic_concat/3</A> 
if non-atom arguments are involved.</DD>
<DT class="pubdef"><A NAME="atomic_concat/3"><STRONG>atomic_concat</STRONG>(<VAR>+Atomic1, 
+Atomic2, -Atom</VAR>)</A></DT>
<DD class="defbody">
<VAR>Atom</VAR> represents the text after converting <VAR>Atomic1</VAR> 
and
<VAR>Atomic2</VAR> to text and concatenating the result:

<PRE class="code">
?- atomic_concat(name, 42, X).
X = name42.
</PRE>

</DD>
<DT class="pubdef"><span class="pred-tag">[commons]</span><A NAME="atomic_list_concat/2"><STRONG>atomic_list_concat</STRONG>(<VAR>+List, 
-Atom</VAR>)</A></DT>
<DD class="defbody">
<VAR>List</VAR> is a list of atoms, integers or floating point numbers. 
Succeeds if <VAR>Atom</VAR> can be unified with the concatenated 
elements of <VAR>List</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[commons]</span><A NAME="atomic_list_concat/3"><STRONG>atomic_list_concat</STRONG>(<VAR>+List, 
+Separator, ?Atom</VAR>)</A></DT>
<DD class="defbody">
Creates an atom just like <A NAME="idx:atomiclistconcat2:966"></A><A class="pred" href="manipatom.html#atomic_list_concat/2">atomic_list_concat/2</A>, 
but inserts <VAR>Separator</VAR> between each pair of atoms. For 
example:

<PRE class="code">
?- atomic_list_concat([gnu, gnat], ', ', A).

A = 'gnu, gnat'
</PRE>

<P>The SWI-Prolog version of this predicate can also be used to split 
atoms by instantiating <VAR>Separator</VAR> and <VAR>Atom</VAR> as shown 
below. We kept this functionality to simplify porting old SWI-Prolog 
code where this predicate was called <A NAME="idx:concatatom3:967"></A><SPAN class="pred-ext">concat_atom/3</SPAN>.

<PRE class="code">
?- atomic_list_concat(L, -, 'gnu-gnat').

L = [gnu, gnat]
</PRE>

</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="atom_length/2"><STRONG>atom_length</STRONG>(<VAR>+Atom, 
-Length</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Atom</VAR> is an atom of <VAR>Length</VAR> characters long. 
This predicate also works for strings (see <A class="sec" href="strings.html">section 
4.22</A>). If the prolog flag <A class="flag" href="flags.html#flag:iso">iso</A> 
is <EM>not</EM> set, it also accepts integers and floats, expressing the 
number of characters output when given to <A NAME="idx:write1:968"></A><A class="pred" href="termrw.html#write/1">write/1</A> 
as well as code-lists and character-lists, expressing the length of the 
list.<SUP class="fn">bug<SPAN class="fn-text">Note that <CODE>[]</CODE> 
is both an atom an empty code/character list. The predicate <A NAME="idx:atomlength2:969"></A><A class="pred" href="manipatom.html#atom_length/2">atom_length/2</A> 
returns 2 for this atom.</SPAN></SUP></DD>
<DT class="pubdef"><A NAME="atom_prefix/2"><STRONG>atom_prefix</STRONG>(<VAR>+Atom, 
+Prefix</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Atom</VAR> starts with the characters from <VAR>Prefix</VAR>. 
Its behaviour is equivalent to
<CODE>?- sub_atom(<VAR>Atom</VAR>, 0, _, _, <VAR>Prefix</VAR>)</CODE>. 
Depreciated.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="sub_atom/5"><STRONG>sub_atom</STRONG>(<VAR>+Atom, 
?Before, ?Len, ?After, ?Sub</VAR>)</A></DT>
<DD class="defbody">
ISO predicate for breaking atoms. It maintains the following relation:
<VAR>Sub</VAR> is a sub-atom of <VAR>Atom</VAR> that starts at <VAR>Before</VAR>, 
has
<VAR>Len</VAR> characters and <VAR>Atom</VAR> contains <VAR>After</VAR> 
characters after the match.

<PRE class="code">
?- sub_atom(abc, 1, 1, A, S).

A = 1, S = b
</PRE>

<P>The implementation minimises non-determinism and creation of atoms. 
This is a very flexible predicate that can do search, prefix- and 
suffix-matching, etc.
</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / manipatom.html
