1.11.13.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 *text, PlEncoding rep=ENC_INPUT)

PlAtom :: PlAtom(size_t len, const char *s, PlEncoding rep=ENC_INPUT)

PlAtom :: PlAtom(const wchar_t *text)

PlAtom :: PlAtom(const std::string& text, PlEncoding rep=ENC_INPUT)

PlAtom :: PlAtom(const std::wstring& text)

Create an atom from a string. The text is copied if a new atom is created. For the char* and std::string forms rep gives the byte encoding (see section 1.8.2); it defaults to ENC_INPUT. See PL_new_atom_mbchars() and PL_new_atom_wchars(). The constructors PlAtom(PlEncoding, len, s) and PlAtom(PlEncoding, std::string&) are [[deprecated]] in favour of the trailing-PlEncoding forms above.

PlAtom :: PlAtom(const PlTerm &t)

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 &a)

Compares the two atom-handles, returning true or false. 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 &a)

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=ENC_OUTPUT)

Returns the string representation of the atom.^{28If you wish to return a 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 (see section 1.8.2):

• PlEncoding::Latin1 - throws an exception if the text cannot be represented in ISO Latin-1.
• PlEncoding::UTF8 - UTF-8.
• PlEncoding::Locale - uses the locale to determine the representation.

The constants ENC_INPUT (PlEncoding::Latin1) and ENC_OUTPUT (PlEncoding::Locale) name the defaults used for constructing and returning text respectively.

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