Four functions are provided to enable foreign functions to translate from one representation of an atom to another. The first two functions are most useful for C: they convert between canonical atoms and null-terminated C strings. The other two functions are most useful for Pascal and FORTRAN: they convert between canonical atoms and blank-padded character arrays.
QP_string_from_atom(atom)
atom
QP_atom
(that is, an unsigned integer passed by value)
Returns a pointer to a string representing atom
. This
string should not be overwritten by the foreign function.
QP_atom_from_string(string)
string
QP_atom
Returns the canonical representation of the atom whose printed
representation is string
.
The string is copied, and the foreign function can
reuse the string and its space.
QP_padded_string_from_atom(pointer_to_atom,
pointer_to_padded_string, pointer_to_length)
pointer_to_atom
QP_atom
(that is, an
unsigned integer passed by reference)
pointer_to_padded_string
pointer_to_length
Fills in the character array of length *pointer_to_length
with the string
representation of the atom. The string is truncated or blank-padded
to *pointer_to_length
if the length of the atom is greater than or less than
*pointer_to_length
, respectively. The length of the atom (not *pointer_to_length
) is
returned as the function value.
QP_atom_from_padded_string(pointer_to_atom,
pointer_to_padded_string, pointer_to_length)
pointer_to_atom
QP_atom
(that is, an
unsigned integer passed by reference)
pointer_to_padded_string
pointer_to_length
Sets *pointer_to_atom
to the canonical representation of the atom whose printed
representation is the string (less any trailing blanks) contained in
the character array of length *pointer_to_length
. Returns the length of the
resulting atom (not *pointer_to_length
) as the function value.
Below are C specifications of these functions. Note that the arguments of the last two functions are passed by reference. Hence, the last two functions can be called directly from Pascal or FORTRAN. The first two functions are designed to be called from C, in which all parameters are passed by value.
char * QP_string_from_atom(atom) QP_atom atom; QP_atom QP_atom_from_string(string) char *string; int QP_padded_string_from_atom(atom,string,length) QP_atom *atom; char *string; int *length; int QP_atom_from_padded_string(atom,string,length) QP_atom *atom; char *string; int *length;
Canonical atoms are particularly useful as constants, to be used in passing back results from foreign functions. The above functions can be used to initialize tables of such constants.
These functions can only be called from languages other than C if those languages have a C-compatible calling convention for passing integers and pointers. For example, this is true for both Pascal and FORTRAN running under UNIX 4.2 BSD. See the appropriate Quintus Prolog Release Notes for any further details pertaining to your system.