doc/ref_primitive.xml

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