Next: 6.9 All Solutions and Up: 6. Standard Predicates Previous: 6.7 Meta-Logical Contents Index

6.8 Manipulation of Atomic Terms

name(?Constant, ?CharList)

The standard predicate name/2 performs the conversion between a constant and its character list representation. If Constant is supplied (and is any atom or number), CharList is unified with a list of ASCII codes representing the ``name'' of the constant. In that case, CharList is exactly the list of ASCII character codes that appear in the printed representation of Constant. If on the other hand Constant is a variable, then CharList must be a proper list of ASCII character codes. In that case, name/2 will convert a list of ASCII characters that can represent a number to a number rather than to a character string. As a consequence of this, there are some atoms (for example '18') which cannot be constructed by using name/2. If conversion to an atom is preferred in these cases, the standard predicate atom_codes/2 should be used instead. The syntax for numbers that is accepted by name/2 is exactly the one which read/1 accepts. Predicate name/2 is provided for backwards compatibility. It is advisable that new programs use the predicates atom_codes/2 and number_codes/2 described below.

In Version 3.0 predicate name/2 is not yet implemented for converting from a real number to its character list representation, and if the representation of a real is provided as CharList, it will be converted to an atom.

If both of the arguments of name/2 are uninstantiated or CharList is not a proper list of ASCII characters, name/2 will abort and an error message will be sent to the standard error stream.

Examples:

                   | ?- name('Foo', L).
                   L = [70,111,111]

                   | ?- name([], L).
                   L = [91,93]

                   | ?- name(431, L).
                   L = [52,51,49]

                   | ?- name(X, [102,111,111]).
                   X = foo
 
                   | ?- name(X, []).
                   X = ''

                   | ?- name(X, "Foo").
                   X = 'Foo'

                   | ?- name(X, [52,51,49]).
                   X = 431

                   | ?- name(X, [45,48,50,49,51]), integer(X).
                   X = -213

                   | ?- name(3.14, L).
                   ++Error: Predicate name/2 for reals is not implemented yet
                   Aborting...

Error Cases

instantiation_error: Both arguments are uninstantiated, or argument 2 of name/2 contains a variable or is not a proper list.
domain_error(atom_or_number_or_variable,Constant): Constant is not a variable, an atom or a number.
domain_error(list_of_character,CharList: CharList is not a list of ASCII characters.
system_error: Constant is a real number (conversion from a real to its character list representation is not implemented yet).

atom_codes(?Atom, ?CharCodeList)

The standard predicate atom_codes/2 performs the conversion between an atom and its character list representation. If Atom is supplied (and is an atom), CharList is unified with a list of ASCII codes representing the ``name'' of that atom. In that case, CharList is exactly the list of ASCII character codes that appear in the printed representation of Atom. If on the other hand Atom is a variable, then CharList must be a proper list of ASCII character codes. In that case, Atom is instantiated to an atom containing exactly those characters, even if the characters look like the printed representation of a number.

If both of the arguments of atom_codes/2 are uninstantiated or CharList is not a proper list of ASCII characters, atom_codes/2 aborts, and an error message will be sent to the standard error stream.

Examples:

                   | ?- atom_codes('Foo', L).
                   L = [70,111,111]

                   | ?- atom_codes([], L).
                   L = [91,93]

                   | ?- atom_codes(X, [102,111,111]).
                   X = foo
 
                   | ?- atom_codes(X, []).
                   X = ''

                   | ?- atom_codes(X, "Foo").
                   X = 'Foo'

                   | ?- atom_codes(X, [52,51,49]).
                   X = '431'

                   | ?- atom_codes(X, [52,51,49]), integer(X).
                   no

                   | ?- atom_codes(X, [52,Y,49]).
                   ! Instantiation error in argument 2 of atom_codes/2
                   ! Aborting...

                   | ?- atom_codes(431, L).
                   ! Type error: in argument 1 of atom_codes/2
                   ! atom expected, but something else found
                   ! Aborting...

                   | ?- atom_codes(X, [52,300,49]).
                   ! Range error: in argument 2 of atom_codes/2
                   ! ASCII code expected, but 300 found
                   ! Aborting...

Error Cases

instantiation_error: Both arguments are uninstantiated, or argument 2 is not a proper list, or it contains a variable.
domain_error(atom_or_variable,Atom): Atom is not a variable or an atom.
domain_error(listof_character,CharList): CharList is not a list of ASCII characters.

atom_chars(?Number, ?CharAtomList)

Like atom_codes, but the list returned (or input) is a list of characters as atoms rather than ASCII codes. For instance, atom_chars(abc,X) binds X to the list [a,b,c] instead of [97,98,99].

number_codes(?Number, ?CharCodeList)

The standard predicate number_codes/2 performs the conversion between a number and its character list representation. If Number is supplied (and is a number), CharList is unified with a list of ASCII codes comprising the printed representation of that Number. If on the other hand Number is a variable, then CharList must be a proper list of ASCII character codes that corresponds to the correct syntax of a number (either integer or float) In that case, Number is instantiated to that number, otherwise number_codes/2 will simply fail.

If both of the arguments of number_codes/2 are uninstantiated or CharList is not a proper list of ASCII characters, number_codes/2 aborts, and an error message will be sent to the standard error stream.

Examples:

                   | ?- number_codes(123, L).
                   L = [49,50,51];

                   | ?- number_codes(N, [49,50,51]), integer(N).
                   N = 123

                   | ?- number_codes(31.4e+10, L).
                   L = [51,46,49,51,57,57,57,55,69,43,49,48]

                   | ?- number_codes(N, "314e+8").
                   N = 3.14e+10

                   | ?- number_codes(foo, L).
                   ! Type error: in argument 1 of number_codes/2
                   ! number expected, but something else found
                   ! Aborting...

Error Cases

instantiation_error: Both arguments are uninstantiated, or argument 2 is not a proper list, or it contains a variable.
domain_error(atom_or_variable,Number): Number is not a variable or a number.
domain_error(listof_character,CharList): CharList is not a list of ASCII characters.

number_chars(?Number, ?CharAtomList)

Like number_codes, but the list returned (or input) is a list of characters as atoms rather than ASCII codes. For instance, number_chars(123,X) binds X to the list ['1','2','3'] instead of [49,50,51].

number_digits(?Number, ?DigitList)

Like number_chars, but the list returned (or input) is a list of digits as numbers rather than ASCII codes (for floats, the atom '.', '+' or '-', and 'e' will also be present in the list). For instance, number_digits(123,X) binds X to the list [1,2,3] instead of ['1','2','3'], and number_digits(123.45,X) binds X to [1,.,2,3,4,5,0,0,e,+,0,2].

atom_concat(Atom1,Atom2,Atom3)

ISO

Usage: atom_concat(?Atom,?Atom,+Atom)

Usage: atom_concat(+Atom,+Atom,-Atom)

term_to_atom(+Term,-Atom,+Options)

string
Converts +Term to an atomic form according to a list of write options, Options, that are similar to those used by write_term/[2,3]. The various options of term_to_atom/[2,3] are especially useful for the interface from C to XSB (see Calling XSB from C in Volume 2 of this manual).

quoted(+Bool). If Bool = true, then atoms and functors that can't be read back by read/1 are quoted, if Bool = false, each atom and functor is written as its unquoted name. Default value is false.
ignore_ops(+Bool). If Bool = true each compound term is output in functional notation; list braces are ignored, as are all explicitly defined operators. If Bool = canonical, bracked list notation is used. Default value is canonical. The corresponding value of false, that would enable operator precedence, is not yet implemented.
numbervars(+Bool). If Bool = true, a term of the form '$VAR'(N) where N is an integer, is output as a variable name consisting of a capital letter possibly followed by an integer. A term of the form '$VAR'(Atom) where Atom is an atom, is output as itself (without quotes). Finally, a term of the form '$VAR'(String) where String is a character string, is output as the atom corresponding to this character string. If bool is false this cases are not treated in any special way. Default value is false.

Error Cases

Options is a variable
- instantiation_error
Options neither a variable nor a list
- type_error(list,Options)
Options contains a variable element, O
- instantiation_error
Options contains an element O that is neither a variable nor a write option.
- domain_error(write_option,O)

Examples:

| ?- term_to_atom(f(a,1,X,['3cpio',d(3),'$VAR'("Foo")]),F,[]).

X = _h131
F = f(a,1,_h0,[3cpio,d(3),$VAR([70,111,111])])

yes
| ?- term_to_atom(f(a,1,X,['3cpio',d(3),'$VAR'("Foo")]),F,[numbervars(true)]).

X = _h131
F = f(a,1,_h0,[3cpio,d(3),Foo])

yes
| ?- term_to_atom(f(a,1,X,['3cpio',d(3),'$VAR'("Foo")]),F,[numbervars(true),quoted(true)]).

X = _h131
F = f(a,1,_h0,['3cpio',d(3),Foo])

yes
| ?- term_to_atom(f(a,1,X,['3cpio',d(3),'$VAR'("Foo")]),F,[numbervars(true),quoted(true),ignore_ops(true)]).

X = _h131
F = f(a,1,_h0,'.'('3cpio','.'(d(3),'.'(Foo,[]))))

yes

term_to_atom(+Term,-Atom)

string
This predicate converts an arbitrary Prolog term Term into an atom, putting the result in Atom. It is defined using the default options for term_to_atom/3, e.g. ignore_ops(canonical), quoted(false), and numbervars(false).

term_to_codes(+Term,-CodeList,+OptionList)

string
This predicate is used in the definition of term_to_atom/3 but only converts a term into a list of ASCII codes, and does not intern the list as an atom.

term_to_codes(+Term,-CodeList)

string
This predicate converts a term to a list of ASCII codes. It is defined using the default options for term_to_atom/3, e.g. ignore_ops(canonical), quoted(false), and numbervars(false).

gc_atoms

Explicitly invokes the garbage collector for atoms that are created, but no longer needed. By default, gc_atoms/1 is called automatically, unless the xsb_flag atom_garbage_collection is set to false, or if more than one thread is active. However there are reasons why a user may need to invoke atom table garbage collection. First, in Version 3.0, if atom table garbage collection is invoked automatically, and it occurs periodically on heap garbage collection, or if numerous asserts and retracts have taken place. These heuristics overlook certain cases where numerous atoms may be created without invoking the garbage collector - e.g. through repeated uses of format_write_string/3. In addition if user-defined C code contains pointers to XSB's atom table, atom table garbage collection will be unsafe, as XSB has no way to detect such pointers in external code. In such cases, atom table garbage collection should be turned off, and reinvoked at a point where the external pointers are no longer used.

Next: 6.9 All Solutions and Up: 6. Standard Predicates Previous: 6.7 Meta-Logical Contents Index

Terrance Swift 2007-10-05