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