<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "../ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <reference xml:id="uffi.primitives">
  <title>Primitive Types</title>
  <partintro>
   <title>Overview</title>
   <para>
    Primitive types have a single value, these include
    characters, numbers, and pointers. They are all symbols in
    the keyword package.
   </para>
   <itemizedlist>
    <listitem>
     <para><constant>:char</constant> - Signed 8-bits. A
     dereferenced :char pointer returns an character.
     </para>
    </listitem>
    <listitem>
     <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
     pointer returns an character.
     </para>
    </listitem>
    <listitem>
     <para><constant>:byte</constant> - Signed 8-bits. A
     dereferenced :byte pointer returns an integer.
     </para>
    </listitem>
    <listitem>
     <para><constant>:unsigned-byte</constant> - Unsigned 8-bits. A
     dereferenced :unsigned-byte pointer returns an integer.
     </para>
    </listitem>
    <listitem>
     <para><constant>:short</constant> - Signed 16-bits.
     </para>
    </listitem>
    <listitem>
     <para><constant>:unsigned-short</constant> - Unsigned 16-bits.
     </para>
    </listitem>
    <listitem>
     <para><constant>:int</constant> - Signed 32-bits.</para>
    </listitem>
    <listitem>
     <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
    </listitem>
    <listitem>
     <para><constant>:long</constant> - Signed 32 or 64 bits, depending upon the platform.</para>
    </listitem>
    <listitem>
     <para><constant>:unsigned-long</constant> - Unsigned 32 or 64 bits, depending upon the platform.</para>
    </listitem>
    <listitem>
     <para><constant>:float</constant> - 32-bit floating point.</para>
    </listitem>
    <listitem>
     <para><constant>:double</constant> - 64-bit floating point.</para>
    </listitem>
    <listitem>
     <para><constant>:cstring</constant> - 
     A &NULL; terminated string used for passing and returning characters strings with a &C; function.
     </para>
    </listitem>
    <listitem>
     <para><constant>:void</constant> - 
     The absence of a value. Used to indicate that a function does not return a value.
     </para>
    </listitem>
    <listitem>
     <para><constant>:pointer-void</constant> - Points to a generic object.</para>
    </listitem>
    <listitem>
     <para><constant>*</constant> - Used to declare a pointer to an object</para>
    </listitem>
   </itemizedlist>
  </partintro>
  
  <refentry xml:id="uffi.def-constant">
   <refnamediv>
    <refname><function>def-constant</function></refname>
    <refpurpose>Binds a symbol to a constant. 
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <title>Macro</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>def-constant</funcdef>
      <paramdef><parameter>name</parameter></paramdef>
      <paramdef><parameter>value</parameter></paramdef>
      <paramdef><parameter>&key;</parameter></paramdef>
      <paramdef><parameter>export</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A symbol that will be bound to the value.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>value</parameter></term>
      <listitem>
       <para>An evaluated form that is bound the the name.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>export</parameter></term>
      <listitem>
       <para>When &t;, the name is exported from the current package. The default is &nil;</para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsynopsisdiv>

   <refsect1>
    <title>Description</title>
    <para>This is a thin wrapper around <function>defconstant</function>. It evaluates at
    compile-time and optionally exports the symbol from the package.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
     (def-constant pi2 (* 2 pi))
     (def-constant exported-pi2 (* 2 pi) :export t)</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Creates a new special variable..</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>
  
  <refentry xml:id="uffi.def-foreign-type">
   <refnamediv>
    <refname><function>def-foreign-type</function></refname>
    <refpurpose>Defines a new foreign type. 
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <title>Macro</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>def-foreign-type</funcdef>
      <paramdef><parameter>name</parameter></paramdef>
      <paramdef><parameter>type</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>

    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A symbol naming the new foreign type.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>value</parameter></term>
      <listitem>
       <para>A form that is not evaluated that defines the new
       foreign type.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsynopsisdiv>

   <refsect1>
    <title>Description</title>
    <para>Defines a new foreign type.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
     (def-foreign-type my-generic-pointer :pointer-void)
     (def-foreign-type a-double-float :double-float)
     (def-foreign-type char-ptr (* :char))</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Defines a new foreign type.
    </para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>
  
  <refentry xml:id="uffi.null-char-p">
   <refnamediv>
    <refname><function>null-char-p</function></refname>
    <refpurpose>Tests a character for &NULL; value.
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <title>Macro</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>null-char-p</funcdef>
      <paramdef><parameter>char</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <variablelist>
     <varlistentry>
      <term><parameter>char</parameter></term>
      <listitem>
       <para>A character or integer.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>returns</term>
      <listitem>
       <para>A boolean flag indicating if char is a &NULL; value.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsynopsisdiv>

   <refsect1>
    <title>Description</title>

    <para>A predicate testing if a character or integer is &NULL;. This
    abstracts the difference in implementations where some return a
    <computeroutput>character</computeroutput> and some return a
    <computeroutput>integer</computeroutput> whence dereferencing a
    <computeroutput>C</computeroutput> character pointer.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-array-pointer ca :unsigned-char)
  (let ((fs (convert-to-foreign-string "ab")))
    (values (null-char-p (deref-array fs 'ca 0))
    (null-char-p (deref-array fs 'ca 2))))
=> &nil;
   &t;</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>None.
    </para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>
 </reference>
</book>
<!-- Keep this comment at the end of the file
     Local variables:
     mode: nxml
     sgml-indent-step: 1
     nxml-child-indent: 1
     nxml-outline-child-indent: 0
     fill-column: 79
     End:
-->
