 
 
 
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.
 
 
