doc/ref_aggregate.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="aggregates">
   9     <title>Aggregate Types</title>
  10     <partintro>
  11       <title>Overview</title>
  12       <para>
  13         Aggregate types are comprised of one or more primitive types.
  14       </para>
  15     </partintro>
  16
  17     <refentry id="def-enum">
  18       <refnamediv>
  19         <refname>def-enum</refname>
  20         <refpurpose>Defines a &c; enumeration.
  21         </refpurpose>
  22         <refclass>Macro</refclass>
  23       </refnamediv>
  24       <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27           <function>def-enum</function> <replaceable>name fields &amp;key separator-string</replaceable>
  28         </synopsis>
  29       </refsynopsisdiv>
  30       <refsect1>
  31         <title>Arguments and Values</title>
  32         <variablelist>
  33           <varlistentry>
  34             <term><parameter>name</parameter></term>
  35             <listitem>
  36               <para>A symbol that names the enumeration.
  37               </para>
  38             </listitem>
  39           </varlistentry>
  40           <varlistentry>
  41             <term><parameter>fields</parameter></term>
  42             <listitem>
  43               <para>A list of field defintions. Each definition can be
  44 a symbol or a list of two elements. Symbols get assigned a value of the
  45 current counter which starts at <computeroutput>0</computeroutput> and
  46 increments by <computeroutput>1</computeroutput> for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second
  47 position is the value to assign the the symbol. The current counter gets set
  48 to <computeroutput>1+</computeroutput> this value.
  49               </para>
  50             </listitem>
  51           </varlistentry>
  52           <varlistentry>
  53             <term><parameter>separator-string</parameter></term>
  54             <listitem>
  55               <para>A string that governs the creation of constants. The
  56 default is <computeroutput>"#"</computeroutput>.</para>
  57             </listitem>
  58           </varlistentry>
  59         </variablelist>
  60       </refsect1>
  61       <refsect1>
  62         <title>Description</title>
  63         <para>
  64           Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
  65 values are created by the <function>concatenation</function> of the
  66 enumeration name, separator-string, and field symbol. Also creates
  67 a foreign type with the name <parameter>name</parameter> of type
  68 <constant>:int</constant>.
  69         </para>
  70       </refsect1>
  71       <refsect1>
  72         <title>Examples</title>
  73         <screen>
  74 (def-enum abc (:a :b :c))
  75 ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
  76 ;; the foreign type "abc" to be :int
  77
  78 (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
  79 ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
  80 ;; the foreign type efoo to be :int
  81         </screen>
  82       </refsect1>
  83       <refsect1>
  84         <title>Side Effects</title>
  85         <para>Creates a :int foreign type, defines constants.</para>
  86       </refsect1>
  87       <refsect1>
  88         <title>Affected by</title>
  89         <para>None.</para>
  90       </refsect1>
  91       <refsect1>
  92         <title>Exceptional Situations</title>
  93         <para>None.</para>
  94       </refsect1>
  95     </refentry>
  96
  97
  98       <refentry id="def-struct">
  99         <refnamediv>
 100           <refname>def-struct</refname>
 101         <refpurpose>Defines a &c; structure.
 102         </refpurpose>
 103         <refclass>Macro</refclass>
 104       </refnamediv>
 105       <refsynopsisdiv>
 106         <title>Syntax</title>
 107         <synopsis>
 108           <function>def-struct</function> <replaceable>name &amp;rest fields</replaceable>
 109         </synopsis>
 110       </refsynopsisdiv>
 111       <refsect1>
 112         <title>Arguments and Values</title>
 113         <variablelist>
 114           <varlistentry>
 115             <term><parameter>name</parameter></term>
 116             <listitem>
 117               <para>A symbol that names the structure.
 118               </para>
 119             </listitem>
 120           </varlistentry>
 121           <varlistentry>
 122             <term><parameter>fields</parameter></term>
 123             <listitem>
 124               <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
 125               </para>
 126             </listitem>
 127           </varlistentry>
 128         </variablelist>
 129       </refsect1>
 130       <refsect1>
 131         <title>Description</title>
 132         <para>
 133           Declares a structure. A special type is available as a slot
 134 in the field. It is a pointer that points to an instance of the parent
 135 structure. It's type is <constant>:pointer-self</constant>.
 136
 137         </para>
 138       </refsect1>
 139       <refsect1>
 140         <title>Examples</title>
 141         <screen>
 142 (def-struct foo (a :unsigned-int)
 143                 (b (* :char))
 144                 (c (:array :int 10))
 145                 (next :pointer-self))
 146         </screen>
 147       </refsect1>
 148       <refsect1>
 149         <title>Side Effects</title>
 150         <para>Creates a foreign type.</para>
 151       </refsect1>
 152       <refsect1>
 153         <title>Affected by</title>
 154         <para>None.</para>
 155       </refsect1>
 156       <refsect1>
 157         <title>Exceptional Situations</title>
 158         <para>None.</para>
 159       </refsect1>
 160     </refentry>
 161
 162
 163     <refentry id="get-slot-value">
 164       <refnamediv>
 165         <refname>get-slot-value</refname>
 166         <refpurpose>Retrieves a value from a slot of a structure.
 167         </refpurpose>
 168         <refclass>Macro</refclass>
 169       </refnamediv>
 170       <refsynopsisdiv>
 171         <title>Syntax</title>
 172         <synopsis>
 173           <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
 174         </synopsis>
 175       </refsynopsisdiv>
 176       <refsect1>
 177         <title>Arguments and Values</title>
 178         <variablelist>
 179           <varlistentry>
 180             <term><parameter>obj</parameter></term>
 181             <listitem>
 182               <para>A pointer to foreign structure.
 183               </para>
 184             </listitem>
 185           </varlistentry>
 186           <varlistentry>
 187             <term><parameter>type</parameter></term>
 188             <listitem>
 189               <para>A name of the foreign structure.
 190               </para>
 191             </listitem>
 192           </varlistentry>
 193           <varlistentry>
 194             <term><parameter>field</parameter></term>
 195             <listitem>
 196               <para>A name of the desired field in foreign structure.
 197               </para>
 198             </listitem>
 199           </varlistentry>
 200           <varlistentry>
 201             <term><returnvalue>value</returnvalue></term>
 202             <listitem>
 203               <para>The value of the field in the structure.
 204               </para>
 205             </listitem>
 206           </varlistentry>
 207         </variablelist>
 208       </refsect1>
 209       <refsect1>
 210         <title>Description</title>
 211         <para>
 212           Accesses a slot value from a structure.
 213         </para>
 214       </refsect1>
 215       <refsect1>
 216         <title>Examples</title>
 217         <screen>
 218 (get-slot-value foo-ptr 'foo-structure 'field-name)
 219         </screen>
 220       </refsect1>
 221       <refsect1>
 222         <title>Side Effects</title>
 223         <para>None.</para>
 224       </refsect1>
 225       <refsect1>
 226         <title>Affected by</title>
 227         <para>None.</para>
 228       </refsect1>
 229       <refsect1>
 230         <title>Exceptional Situations</title>
 231         <para>None.</para>
 232       </refsect1>
 233     </refentry>
 234
 235     <refentry id="get-slot-pointer">
 236       <refnamediv>
 237         <refname>get-slot-pointer</refname>
 238         <refpurpose>Retrieves a pointer from a slot of a structure.
 239         </refpurpose>
 240         <refclass>Macro</refclass>
 241       </refnamediv>
 242       <refsynopsisdiv>
 243         <title>Syntax</title>
 244         <synopsis>
 245           <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
 246         </synopsis>
 247       </refsynopsisdiv>
 248       <refsect1>
 249         <title>Arguments and Values</title>
 250         <variablelist>
 251           <varlistentry>
 252             <term><parameter>obj</parameter></term>
 253             <listitem>
 254               <para>A pointer to foreign structure.
 255               </para>
 256             </listitem>
 257           </varlistentry>
 258           <varlistentry>
 259             <term><parameter>type</parameter></term>
 260             <listitem>
 261               <para>A name of the foreign structure.
 262               </para>
 263             </listitem>
 264           </varlistentry>
 265           <varlistentry>
 266             <term><parameter>field</parameter></term>
 267             <listitem>
 268               <para>A name of the desired field in foreign structure.
 269               </para>
 270             </listitem>
 271           </varlistentry>
 272           <varlistentry>
 273             <term><returnvalue>pointer</returnvalue></term>
 274             <listitem>
 275               <para>The value of the field in the structure.
 276               </para>
 277             </listitem>
 278           </varlistentry>
 279         </variablelist>
 280       </refsect1>
 281       <refsect1>
 282         <title>Description</title>
 283         <para>
 284           This is similar to <function>get-slot-value</function>. It
 285           is used when the value of a slot is a pointer type.
 286         </para>
 287       </refsect1>
 288       <refsect1>
 289         <title>Examples</title>
 290         <screen>
 291 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
 292         </screen>
 293       </refsect1>
 294       <refsect1>
 295         <title>Side Effects</title>
 296         <para>None.</para>
 297       </refsect1>
 298       <refsect1>
 299         <title>Affected by</title>
 300         <para>None.</para>
 301       </refsect1>
 302       <refsect1>
 303         <title>Exceptional Situations</title>
 304         <para>None.</para>
 305       </refsect1>
 306     </refentry>
 307
 308
 309     <refentry id="def-array-pointer">
 310       <refnamediv>
 311         <refname>def-array-pointer</refname>
 312         <refpurpose>Defines a pointer to a array of type.
 313         </refpurpose>
 314         <refclass>Macro</refclass>
 315       </refnamediv>
 316       <refsynopsisdiv>
 317         <title>Syntax</title>
 318         <synopsis>
 319           <function>def-array-pointer</function> <replaceable>name type</replaceable>
 320         </synopsis>
 321       </refsynopsisdiv>
 322       <refsect1>
 323         <title>Arguments and Values</title>
 324         <variablelist>
 325           <varlistentry>
 326             <term><parameter>name</parameter></term>
 327             <listitem>
 328               <para>A name of the new foreign type.
 329               </para>
 330             </listitem>
 331           </varlistentry>
 332           <varlistentry>
 333             <term><parameter>type</parameter></term>
 334             <listitem>
 335               <para>The foreign type of the array elements.
 336               </para>
 337             </listitem>
 338           </varlistentry>
 339         </variablelist>
 340       </refsect1>
 341       <refsect1>
 342         <title>Description</title>
 343         <para>
 344           Defines a type tat is a pointer to an array of type.
 345         </para>
 346       </refsect1>
 347       <refsect1>
 348         <title>Examples</title>
 349         <screen>
 350 (def-array-pointer byte-array-pointer :unsigned-char)
 351         </screen>
 352       </refsect1>
 353       <refsect1>
 354         <title>Side Effects</title>
 355         <para>Defines a new foreign type.</para>
 356       </refsect1>
 357       <refsect1>
 358         <title>Affected by</title>
 359         <para>None.</para>
 360       </refsect1>
 361       <refsect1>
 362         <title>Exceptional Situations</title>
 363         <para>None.</para>
 364       </refsect1>
 365     </refentry>
 366
 367
 368     <refentry id="deref-array">
 369       <refnamediv>
 370         <refname>deref-array</refname>
 371         <refpurpose>Deference an array.
 372         </refpurpose>
 373         <refclass>Macro</refclass>
 374       </refnamediv>
 375       <refsynopsisdiv>
 376         <title>Syntax</title>
 377         <synopsis>
 378           <function>deref-array</function> <replaceable>array type positon</replaceable> => <returnvalue>value</returnvalue>
 379         </synopsis>
 380       </refsynopsisdiv>
 381       <refsect1>
 382         <title>Arguments and Values</title>
 383         <variablelist>
 384           <varlistentry>
 385             <term><parameter>array</parameter></term>
 386             <listitem>
 387               <para>A foreign array.
 388               </para>
 389             </listitem>
 390           </varlistentry>
 391           <varlistentry>
 392             <term><parameter>type</parameter></term>
 393             <listitem>
 394               <para>The foreign type of the array.
 395               </para>
 396             </listitem>
 397           </varlistentry>
 398           <varlistentry>
 399             <term><parameter>position</parameter></term>
 400             <listitem>
 401               <para>An integer specifying the position to retrieve from
 402 the array.
 403               </para>
 404             </listitem>
 405           </varlistentry>
 406           <varlistentry>
 407             <term><returnvalue>value</returnvalue></term>
 408             <listitem>
 409               <para>The value stored in the position of the array.
 410               </para>
 411             </listitem>
 412           </varlistentry>
 413         </variablelist>
 414       </refsect1>
 415       <refsect1>
 416         <title>Description</title>
 417         <para>
 418           Dereferences (retrieves) the value of an array element.
 419         </para>
 420       </refsect1>
 421       <refsect1>
 422         <title>Examples</title>
 423         <screen>
 424 (def-array-pointer ca :char)
 425 (let ((fs (convert-to-foreign-string "ab")))
 426    (values (null-char-p (deref-array fs 'ca 0))
 427            (null-char-p (deref-array fs 'ca 2))))
 428 => &nil;
 429    &t;
 430         </screen>
 431       </refsect1>
 432       <refsect1>
 433         <title>Notes</title>
 434         <para>
 435   The TYPE argument is ignored for CL implementations other than
 436   AllegroCL. If you want to cast a pointer to another type use
 437   WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
 438         </para>
 439       </refsect1>
 440       <refsect1>
 441         <title>Side Effects</title>
 442         <para>None.</para>
 443       </refsect1>
 444       <refsect1>
 445         <title>Affected by</title>
 446         <para>None.</para>
 447       </refsect1>
 448       <refsect1>
 449         <title>Exceptional Situations</title>
 450         <para>None.</para>
 451       </refsect1>
 452     </refentry>
 453
 454     <refentry id="def-union">
 455       <refnamediv>
 456         <refname>def-union</refname>
 457         <refpurpose>Defines a foreign union type.
 458         </refpurpose>
 459         <refclass>Macro</refclass>
 460       </refnamediv>
 461       <refsynopsisdiv>
 462         <title>Syntax</title>
 463         <synopsis>
 464           <function>def-union</function> <replaceable>name &amp;rest fields</replaceable>
 465         </synopsis>
 466       </refsynopsisdiv>
 467       <refsect1>
 468         <title>Arguments and Values</title>
 469         <variablelist>
 470           <varlistentry>
 471             <term><parameter>name</parameter></term>
 472             <listitem>
 473               <para>A name of the new union type.
 474               </para>
 475             </listitem>
 476           </varlistentry>
 477           <varlistentry>
 478             <term><parameter>fields</parameter></term>
 479             <listitem>
 480               <para>A list of fields of the union.
 481               </para>
 482             </listitem>
 483           </varlistentry>
 484         </variablelist>
 485       </refsect1>
 486       <refsect1>
 487         <title>Description</title>
 488         <para>
 489           Defines a foreign union type.
 490         </para>
 491       </refsect1>
 492       <refsect1>
 493         <title>Examples</title>
 494         <screen>
 495 (def-union test-union
 496   (a-char :char)
 497   (an-int :int))
 498
 499 (let ((u (allocate-foreign-object 'test-union))
 500   (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
 501   (prog1
 502     (ensure-char-character (get-slot-value u 'test-union 'a-char))
 503     (free-foreign-object u)))
 504 => #\A
 505         </screen>
 506       </refsect1>
 507       <refsect1>
 508         <title>Side Effects</title>
 509         <para>Defines a new foreign type.</para>
 510       </refsect1>
 511       <refsect1>
 512         <title>Affected by</title>
 513         <para>None.</para>
 514       </refsect1>
 515       <refsect1>
 516         <title>Exceptional Situations</title>
 517         <para>None.</para>
 518       </refsect1>
 519     </refentry>
 520
 521 </reference>
 522