Decomposing ECLiPSe terms in C

The following group of functions type-check an ECLiPSe term and retrieve its contents if it is of the correct type. The return code is PSUCCEED for successful conversion. If a variable was encountered instead INSTANTIATION_FAULT is returned. Other unexpected types yield a TYPE_ERROR. Special cases are explained below.

int ec_get_string(const pword,char**)

checks whether the ECLiPSe pword is a string (or atom) and converts it to a C string. This string is volatile, ie. it should be copied when it is required to survive resuming of ECLiPSe.

int ec_get_string_length(const pword,char**,long*)

the same as ec_get_string(), but returns also the string's length. Note that ECLiPSe strings may contain null characters!

int ec_get_atom(const pword,dident*)

checks whether the ECLiPSe pword is an atom, and if so, return its dictionary identifier.

int ec_get_long(const pword,long*)

checks whether the ECLiPSe pword is a word-sized integer, and if so, returns it as a C long.

int ec_get_double(const pword,double*)

checks whether the ECLiPSe pword is a floating point number, and if so, returns it as an C double.

int ec_get_nil(const pword)

checks whether the ECLiPSe pword is nil, the empty list.

int ec_get_list(const pword,pword*,pword*)

checks whether the ECLiPSe pword is a list, and if so, returns its head and tail. If it is nil, the return code is PFAIL.

int ec_get_functor(pword,dident*)

checks whether the ECLiPSe pword is a structure, and if so, returns the functor.

int ec_get_arg(const int n,pword,pword*)

checks whether the ECLiPSe pword is a structure, and if so, returns the n'th argument. The return code is RANGE_ERROR if the argument index is out of range.

int ec_arity(pword)

returns the arity (number of arguments) of an ECLiPSe pword if it is a structure, otherwise zero.

int ec_get_handle(const pword,const t_ext_type*,t_ext_ptr*)

checks whether the ECLiPSe pword is a handle whose method table matches the given one, and if so, the data pointer is returned.

int ec_is_var(const pword)

checks whether the ECLiPSe pword is a variable. Note that the return values are PSUCCEED are PFAIL rather than standard C truth values.