- Documentation
- Reference manual
- Packages
- A C++ interface to SWI-Prolog
- A C++ interface to SWI-Prolog (Version 2)
- Overview of accessing and changing values (version 2)
- Converting PlTerm to native C and C++ types (version 2)
- Unification (version 2)
- Comparison (version 2)
- Analysing compound terms (version 2)
- Miscellaneous (version 2)
- The class PlTerm_string (version 2)
- The class PlCodeList (version 2)
- The class PlCharList (version 2)
- The class PlCompound (version 2)
- The class PlTail (version 2)
- The class PlTermv (version 2)
- The class PlAtom - Supporting Prolog constants (version 2)
- Classes for the recorded database: PlRecord and PlRecordExternalCopy
- Overview of accessing and changing values (version 2)
- A C++ interface to SWI-Prolog (Version 2)
- A C++ interface to SWI-Prolog
2.10.12 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:
2.10.12.1 Direct comparision to char *
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.
2.10.12.2 Direct comparision to PlAtom
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.
2.10.12.3 Extraction of the atom and comparison to PlAtom
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.10.12.2, but in nested if-then-else the extraction of the atom from the term is done only once.
2.10.12.4 Extraction of the atom and comparison to char *
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.
- PlAtom :: PlAtom(atom_t handle)
- Create from C-interface atom handle (
atom_t
). Used internally and for integration with the C-interface. - PlAtom :: PlAtom(const char_t *text)
- PlAtom :: PlAtom(const wchar *text)
- PlAtom :: PlAtom(const std::string& text)
- PlAtom :: PlAtom(const std::wstring& text)
- Create an atom from a string. The text is copied if a new atom is created. See PL_new_atom(), PL_new_atom_wchars(), PL_new_atom_nchars(), PL_new_atom_wchars().
- PlAtom :: PlAtom(const PlTerm &)
- If t represents an atom, the new instance represents this
atom. Otherwise a
type_error
is thrown. - int PlAtom::operator ==(const wchar_t *text)
- int PlAtom::operator ==(const char *text)
- int PlAtom::operator ==(const std::string& text)
- int PlAtom::operator ==(const std::wstring& text)
- Yields
true
if the atom represents text,false
otherwise. Performs a strcmp() or similar for this. - int PlAtom::operator ==(const PlAtom &)
- Compares the two atom-handles, returning
true
orfalse
. Because atoms are unique, there is no need to use strcmp() for this. - int PlAtom::operator !=(const wchar_t *text)
- int PlAtom::operator !=(const char *text)
- int PlAtom::operator !=(const std::string& text)
- int PlAtom::operator !=(const std::wstring& text)
- int PlAtom::operator !=(const PlAtom &)
- The inverse of the
operator.==
- bool is_valid()
- Verifies that the handle is valid. This can be used after calling a function that returns an atom handle, to check that a new atom was created.
- void reset()
- Sets the handle to an invalid valid - a subsequent call to is_null()
will return
true
. - const std::string as_string(PlEncoding enc=EncLocale)
- Returns the string representation of the atom.25If
you wish to return a
char*
from a function, you should not doreturn 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 withdetect_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 forenc
are:EncLatin1
- throws an exception if cannot be represented in ASCII.EncUTF8
EncLocale
- uses the locale to determine the representation.
- const std:wstring as_wstring()
- Returns the string representation of the atom. 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.
- void register_atom()
- See PL_register_atom().
- void unregister_atom()
- See PL_unregister_atom().
- void* blob_data(size_t *len, struct PL_blob_t **type)
- See PL_blob_data().