Converting between Atoms and Strings

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:
Pointer to a null-terminated string of characters (C convention for strings)

Returns a pointer to a string representing atom. This string should not be overwritten by the foreign function.

QP_atom_from_string(string)


string
Pointer to a null-terminated string of characters (C convention for strings)

Returns:
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
Pointer to a QP_atom (that is, an unsigned integer passed by reference)
pointer_to_padded_string
Pointer to a character array
pointer_to_length
Pointer to an integer (that is, an integer passed by reference)
Returns:
integer

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
Pointer to a QP_atom (that is, an unsigned integer passed by reference)
pointer_to_padded_string
Pointer to a character array
pointer_to_length
Pointer to an integer (that is, an integer passed by reference)
Returns:
integer

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.