Did you know ... | Search Documentation: |
The class PlAtom - Supporting Prolog constants (version 2) |
Both for quick comparison as for quick building of lists of atoms, it is desirable to provide access to Prolog's atom-table, mapping handles to unique string-constants. If the handles of two atoms are different it is guaranteed they represent different text strings.
Suppose we want to test whether a term represents a certain atom, this interface presents a large number of alternatives:
Example:
PREDICATE(test, 1) { if ( A1 == "read" ) ...; }
This writes easily and is the preferred method is performance is not critical and only a few comparisons have to be made. It validates A1 to be a term-reference representing text (atom, string, integer or float) extracts the represented text and uses strcmp() to match the strings.
Example:
static PlAtom ATOM_read("read"); PREDICATE(test, 1) { if ( A1 == ATOM_read ) ...; }
This case raises a type_error
if A1 is not an
atom. Otherwise it extacts the atom-handle and compares it to the
atom-handle of the global PlAtom
object. This approach is
faster and provides more strict type-checking.
Example:
static PlAtom ATOM_read("read"); PREDICATE(test, 1) { PlAtom a1(A1); if ( a1 == ATOM_read ) ...; }
This approach is basically the same as section 2.11.12.2, but in nested if-then-else the extraction of the atom from the term is done only once.
Example:
PREDICATE(test, 1) { PlAtom a1(A1); if ( a1 == "read" ) ...; }
This approach extracts the atom once and for each test extracts the represented string from the atom and compares it. It avoids the need for global atom constructors.
atom_t
). Used
internally and for integration with the C-interface.type_error
is thrown.true
if the atom represents text, false
otherwise. Performs a strcmp() or similar for this.true
or
false
. Because atoms are unique, there is no need to use strcmp()
for this.==
operator.true
.char*
from a function, you should not
do return t.as_string().c_str()
because that will return a pointer into the stack (Gnu C++ or Clang
options -Wreturn-stack-address
or -Wreturn-local-addr
)
can sometimes catch this, as can the runtime address sanitizer
when run with detect_stack_use_after_return=1
.
This does not quote or escape any characters that would need to be
escaped if the atom were to be input to the Prolog parser. The possible
values for enc
are:
EncLatin1
- throws an exception if cannot be
represented in ASCII.EncUTF8
EncLocale
- uses the locale to determine the
representation.