Referring to ECLiPSe terms from C++

## B.3 Referring to ECLiPSe terms from C++

The data types EC_refs and EC_ref provide a means to have non-volatile references to ECLiPSe data from within C++ data structures. However, it must be kept in mind that ECLiPSe data structures are nevertheless subject to backtracking, which means they may be reset to an earlier status when the search engine requires it. Creating a reference to a data structure does not change that in any way. In particular, when the search engine fails beyond the state where the reference was set up, the reference disappears and is also reset to its earlier value.

EC_refs(int n)
  create a data structure capable of holding n non-volatile references to ECLiPSe data items. They are each initialised with a freshly created ECLiPSe variable.
EC_refs(int n,EC_word pw)
  create a data structure capable of holding n non-volatile references to ECLiPSe data items. They are all initialised with the value pw, which must be of a simple type.
∼EC_refs()
  destroy the ECLiPSe references. It is important that this is done, otherwise the ECLiPSe garbage collector will not be able to free the references data structures, which may eventually lead to memory overflow.
EC_word EC_refs::operator[ ](int i)
  return the ECLiPSe term referred to by the i’th reference.
void EC_refs::set(int i, EC_word new)
  assign the term new to the i’th reference. This is a backtrackable operation very similar to setarg/3.
EC_word list(EC_refs&)
  creates an ECLiPSe list containing all the elements of the EC_refs.
EC_ref()
EC_ref(EC_word pw)
∼EC_ref()
  analogous to the corresponding EC_refs constructors/destructor.
EC_ref& operator=(const EC_word)
  assign a value to the EC_ref.
EC_word(const EC_ref&)
  retrieves the ECLiPSe term referenced by the EC_ref.