See also section 2.4.3.
The general philosophy for C++ classes is that a "half-created" object should not be possible - that is, the constructor should either succeed with a completely usable object or it should throw an exception. This API tries to follow that philosophy, but there are some important exceptions and caveats. (For more on how the C++ and Prolog exceptions interrelate, see section 2.16.)
The various classes (PlAtom, PlTerm, etc.)
are thin wrappers around the C interface's types (atom_t,
term_t, etc.). As such they inherit the concept of "null"
from these types (which is abstracted as PlAtom::null,
PlTerm::null, etc., which typically is equivalent to
0). You can check whether the object is "fully created" by
using the verify() method - it will throw an exception if the
object is null.
However, most of the classes have constructors that create a "complete" object. For example,
PlAtom foo("foo");
will ensure that the object foo is useable and will
throw an exception if the atom can't be created.
To help avoid programming errors, most of the classes do not have a
default "empty" constructor. For example, if you with to create a
PlAtom that is uninitialized, you must explicitly use
PlAtom(PlAtom::null). This make some code a bit more
cumbersome because you can't omit the default constructors in struct
initalizers.
Many of the classes wrap long-lived items, such as atoms, functors,
predicates, or modules. For these, it's often a good idea to define them
as static variables that get created at load time, so that
a lookup for each use isn't needed (atoms are unique, so
PlAtom("foo") requires a lookup for an atom foo
and creates one if it isn't found). Sometimes, it's desirable to create
them "lazily", such as:
static PlAtom foo(PlAtom::null};
...
if ( foo.is_null() )
foo = PlAtom("foo");
The class PlTerm (which wraps term_t) is
the most used. Although a PlTerm object can be created from
a term_t value, it is intended to be used with a
constructor that gives it an initial value. The default constructor
calls PL_new_term_ref() and throws an exception if this fails.
The various constructors are described in
section 2.9.1. Note that the
default constructor is not public; to create a "variable" term, you
should use the subclass constructor PlTerm_var().