C.3  Referring to ECLⁱPS^e terms from C

The data types ec_refs and ec_ref provide a means to have non-volatile references to ECLⁱPS^e data from within C data structures. However, it must be kept in mind that ECLⁱPS^e 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 ec_refs_create(int n,const pword pw)

create a data structure capable of holding n non-volatile references to ECLⁱPS^e data items. They are initialised with the value pw, which must be of a simple type.

ec_refs ec_refs_create_newvars(int)

like ec_refs_create(), but each item is initialised to a freshly created ECLⁱPS^e variable.

void ec_refs_destroy(ec_refs)

destroy the ECLⁱPS^e references. It is important that this is done, otherwise the ECLⁱPS^e garbage collector will not be able to free the references data structures, which may eventually lead to memory overflow.

void ec_refs_set(ec_refs,int i,const pword pw)

set the i’th reference to the ECLⁱPS^e term pw. This setting is subject to the ECLⁱPS^e engine’s undo-mechanism on backtracking.

pword ec_refs_get(const ec_refs,int i)

return the ECLⁱPS^e term referred to by the i’th reference.

int ec_refs_size(const ec_refs)

return the capacity of the ec_refs data structure.

ec_ref ec_ref_create(pword)

like ec_refs_create() for a single reference.

ec_ref ec_ref_create_newvar()

analogous to ec_refs_create_newvars().

void ec_ref_destroy(ec_ref)

analogous to ec_refs_destroy().

void ec_ref_set(ec_ref,const pword)

analogous to ec_refs_set().

pword ec_ref_get(const ec_ref)

analogous to ec_refs_get().