Decomposing ECLiPSe terms in C

## C.2 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 an integer that fits into a C long, and if so, stores it via the pointer provided. Otherwise, the return code is RANGE_ERROR.
int ec_get_long_long(const pword,long long*)
  checks whether the ECLiPSe pword is an integer that fits into a C long long, and if so, stores it via the pointer provided. Otherwise, the return code is RANGE_ERROR.
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.