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.