2.8 Porting from version 1 to version 2

SWI-cpp2.h is not stand-alone; it needs SWI-cpp2.cpp to implement some functions. The easiest way of taking care of this is to add #include <SWI-cpp2.cpp> in your "main" file; alternatively, you can create another source file that contains the "include" statement.

The easiest way of porting from SWI-cpp.h to SWI-cpp2.h is to change the #include "SWI-cpp.h" to #include "SWI-cpp2.h" and look at the warning and error messages. Where possible, version 2 keeps old interfaces with a "deprecated" flag if there is a better way of doing things with version 2.

For convenience when calling PL_*() functions, the Plx_*() wrapper functions add error checking. Also, most of the PL_*() functions that work with term_t, atom_t, etc. have corresponding methods in PlTerm, PlAtom, etc.

Here is a list of typical changes:

• Replace PlTerm() constructor with PlTerm_var() for uninstantiated variables, PlTerm_atom(a) for atoms, PlTerm_term_t(t) for the raw term_t, PlTerm_integer(i), PlTerm_float(v), or PlTerm_pointer(p).

• Examine uses of char* or wchar_t and replace them by std::string or std::wstring if appropriate. For example, cout << "Hello " << (char*)A1 << endl can be replaced by cout << "Hello " << A1.as_string() << endl. In general, std::string is safer than char* because the latter can potentially point to freed memory.

• Instead of returning false from a predicate for failure, you can do throw PlFail(). This mechanism is also used by PlCheckFail(rc). Note that throwing an exception is slower than returning false, so performance-critical code should avoid PlCheckFail(rc) if failure is expected to happen often.

• You can use the PlCheck_PL(rc) to check the return code from a function in SWI-Prolog and throw a PlFail exception to short-circuit execution and return failure (false) to Prolog (or throw a PlException if there was a Prolog error.

• PlAtom::handle has been replaced by PlAtom::C_.

• PlTerm::ref has been replaced by PlAtom::C_.

• PlFunctor::functor has been replaced by PlAtom::C_.

• The operator = for unification has been deprecated, replaced by various unify_*() methods (PlTerm::unify_term(t2), PlTerm::unify_atom(a), etc.).

• The various "cast" operators have been deprecated or deleted; you should use the various "getter" methods. For example, static_cast<char*>(t) is replaced by t.as_string().c_str() (and you should prefer t.as_striong(); static_cast<int32_t>(t) is replaced by t.as_int32_t(), etc.

• It is recommended that you do not use int or long because of problems porting between Unix and Windows platforms; instead, use int32_t, int64_t, uint32_t, uint64_t, etc.