doc/ref_primitive.xml

   1 <?xml version='1.0' ?>   <!-- Mode: Docbook -->
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.xml">
   5 %myents;
   6 ]>
   7
   8 <reference id="primitives">
   9    <title>Primitive Types</title>
  10           <partintro>
  11           <title>Overview</title>
  12         <para>
  13           Primitive types have a single value, these include
  14           characters, numbers, and pointers. They are all symbols in
  15           the keyword package.
  16         </para>
  17         <itemizedlist>
  18           <listitem>
  19             <para><constant>:char</constant> - Signed 8-bits. A
  20 dereferenced :char pointer returns an character.</para>
  21           </listitem>
  22           <listitem>
  23             <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
  24 pointer returns an character.</para>
  25           </listitem>
  26           <listitem>
  27             <para><constant>:byte</constant> - Signed 8-bits. A
  28 dereferenced :byte pointer returns an integer.</para>
  29           </listitem>
  30           <listitem>
  31             <para><constant>:unsigned-byte</constant> - Unsigned 8-bits. A
  32 dereferenced :unsigned-byte pointer returns an integer.</para>
  33           </listitem>
  34           <listitem>
  35             <para><constant>:short</constant> - Signed 16-bits.</para>
  36           </listitem>
  37           <listitem>
  38             <para><constant>:unsigned-short</constant> - Unsigned 16-bits.</para>
  39           </listitem>
  40           <listitem>
  41             <para><constant>:int</constant> - Signed 32-bits.</para>
  42           </listitem>
  43           <listitem>
  44             <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
  45           </listitem>
  46           <listitem>
  47             <para><constant>:long</constant> - Signed 32 or 64 bits, depending upon the platform.</para>
  48           </listitem>
  49           <listitem>
  50             <para><constant>:unsigned-long</constant> - Unsigned 32 or 64 bits, depending upon the platform.</para>
  51           </listitem>
  52           <listitem>
  53             <para><constant>:float</constant> - 32-bit floating point.</para>
  54           </listitem>
  55           <listitem>
  56             <para><constant>:double</constant> - 64-bit floating point.</para>
  57           </listitem>
  58           <listitem>
  59             <para><constant>:cstring</constant> -
  60 A &null; terminated string used for passing and returning characters strings with a &c; function.
  61             </para>
  62           </listitem>
  63           <listitem>
  64             <para><constant>:void</constant> -
  65 The absence of a value. Used to indicate that a function does not return a value.</para>
  66           </listitem>
  67           <listitem>
  68             <para><constant>:pointer-void</constant> -
  69 Points to a generic object.</para>
  70           </listitem>
  71           <listitem>
  72             <para><constant>*</constant> - Used to declare a pointer to an object</para>
  73           </listitem>
  74         </itemizedlist>
  75       </partintro>
  76
  77       <refentry id="def-constant">
  78         <refnamediv>
  79           <refname>def-constant</refname>
  80         <refpurpose>Binds a symbol to a constant.
  81         </refpurpose>
  82         <refclass>Macro</refclass>
  83       </refnamediv>
  84       <refsynopsisdiv>
  85         <title>Syntax</title>
  86         <synopsis>
  87           <function>def-constant</function> <replaceable>name value &amp;key export</replaceable>
  88         </synopsis>
  89       </refsynopsisdiv>
  90       <refsect1>
  91         <title>Arguments and Values</title>
  92         <variablelist>
  93           <varlistentry>
  94             <term><parameter>name</parameter></term>
  95             <listitem>
  96               <para>A symbol that will be bound to the value.
  97               </para>
  98             </listitem>
  99           </varlistentry>
 100           <varlistentry>
 101             <term><parameter>value</parameter></term>
 102             <listitem>
 103               <para>An evaluated form that is bound the the name.
 104               </para>
 105             </listitem>
 106           </varlistentry>
 107           <varlistentry>
 108             <term><parameter>export</parameter></term>
 109             <listitem>
 110               <para>When &t;, the name is exported from the current package. The default is &nil;</para>
 111             </listitem>
 112           </varlistentry>
 113         </variablelist>
 114       </refsect1>
 115       <refsect1>
 116         <title>Description</title>
 117         <para>
 118           This is a thin wrapper around
 119           <function>defconstant</function>. It evaluates at
 120             compile-time and optionally exports the symbol from the package.
 121         </para>
 122       </refsect1>
 123       <refsect1>
 124         <title>Examples</title>
 125         <programlisting>
 126 (def-constant pi2 (* 2 pi))
 127 (def-constant exported-pi2 (* 2 pi) :export t)
 128         </programlisting>
 129       </refsect1>
 130       <refsect1>
 131         <title>Side Effects</title>
 132         <para>Creates a new special variable..</para>
 133       </refsect1>
 134       <refsect1>
 135         <title>Affected by</title>
 136         <para>None.</para>
 137       </refsect1>
 138       <refsect1>
 139         <title>Exceptional Situations</title>
 140         <para>None.</para>
 141       </refsect1>
 142     </refentry>
 143
 144     <refentry id="def-foreign-type">
 145         <refnamediv>
 146           <refname>def-foreign-type</refname>
 147         <refpurpose>Defines a new foreign type.
 148         </refpurpose>
 149         <refclass>Macro</refclass>
 150       </refnamediv>
 151       <refsect1>
 152         <title>Syntax</title>
 153 <synopsis>
 154           <function>def-foreign-type</function> <replaceable>name type</replaceable>
 155 </synopsis>
 156       </refsect1>
 157       <refsect1>
 158         <title>Arguments and Values</title>
 159         <variablelist>
 160           <varlistentry>
 161             <term><parameter>name</parameter></term>
 162             <listitem>
 163               <para>A symbol naming the new foreign type.
 164               </para>
 165             </listitem>
 166           </varlistentry>
 167           <varlistentry>
 168             <term><parameter>value</parameter></term>
 169             <listitem>
 170               <para>A form that is not evaluated that defines the new
 171 foreign type.
 172               </para>
 173             </listitem>
 174           </varlistentry>
 175         </variablelist>
 176       </refsect1>
 177       <refsect1>
 178         <title>Description</title>
 179         <para>Defines a new foreign type.
 180         </para>
 181       </refsect1>
 182       <refsect1>
 183         <title>Examples</title>
 184         <programlisting>
 185 (def-foreign-type my-generic-pointer :pointer-void)
 186 (def-foreign-type a-double-float :double-float)
 187 (def-foreign-type char-ptr (* :char))
 188         </programlisting>
 189       </refsect1>
 190       <refsect1>
 191         <title>Side Effects</title>
 192         <para>Defines a new foreign type.
 193         </para>
 194       </refsect1>
 195       <refsect1>
 196         <title>Affected by</title>
 197         <para>None.</para>
 198       </refsect1>
 199       <refsect1>
 200         <title>Exceptional Situations</title>
 201         <para>None.</para>
 202       </refsect1>
 203     </refentry>
 204
 205     <refentry id="null-char-p">
 206         <refnamediv>
 207           <refname>null-char-p</refname>
 208         <refpurpose>Tests a character for &null; value.
 209         </refpurpose>
 210         <refclass>Macro</refclass>
 211       </refnamediv>
 212       <refsect1>
 213         <title>Syntax</title>
 214 <synopsis>
 215           <function>null-char-p</function> <replaceable>char</replaceable> => <returnvalue>is-null</returnvalue>
 216 </synopsis>
 217       </refsect1>
 218       <refsect1>
 219         <title>Arguments and Values</title>
 220         <variablelist>
 221           <varlistentry>
 222             <term><parameter>char</parameter></term>
 223             <listitem>
 224               <para>A character or integer.
 225               </para>
 226             </listitem>
 227           </varlistentry>
 228           <varlistentry>
 229             <term><parameter>is-null</parameter></term>
 230             <listitem>
 231               <para>A boolean flag indicating if char is a &null; value.
 232               </para>
 233             </listitem>
 234           </varlistentry>
 235         </variablelist>
 236       </refsect1>
 237       <refsect1>
 238         <title>Description</title>
 239         <para>
 240           A predicate testing if a character or integer is &null;. This
 241 abstracts the difference in implementations where some return a
 242 <computeroutput>character</computeroutput> and some return a
 243 <computeroutput>integer</computeroutput> whence dereferencing a
 244 <computeroutput>C</computeroutput> character pointer.
 245         </para>
 246       </refsect1>
 247       <refsect1>
 248         <title>Examples</title>
 249         <programlisting>
 250 (def-array-pointer ca :unsigned-char)
 251 (let ((fs (convert-to-foreign-string "ab")))
 252    (values (null-char-p (deref-array fs 'ca 0))
 253            (null-char-p (deref-array fs 'ca 2))))
 254 => &nil;
 255    &t;
 256         </programlisting>
 257       </refsect1>
 258       <refsect1>
 259         <title>Side Effects</title>
 260         <para>None.
 261         </para>
 262       </refsect1>
 263       <refsect1>
 264         <title>Affected by</title>
 265         <para>None.</para>
 266       </refsect1>
 267       <refsect1>
 268         <title>Exceptional Situations</title>
 269         <para>None.</para>
 270       </refsect1>
 271     </refentry>
 272   </reference>