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. This is generalized
 213           and can be used with <function>setf</function>.
 214         </para>
 215       </refsect1>
 216       <refsect1>
 217         <title>Examples</title>
 218         <screen>
 219 (get-slot-value foo-ptr 'foo-structure 'field-name)
 220 (setf (get-slot-value foo-ptr 'foo-structure 'field-name) 10)
 221         </screen>
 222       </refsect1>
 223       <refsect1>
 224         <title>Side Effects</title>
 225         <para>None.</para>
 226       </refsect1>
 227       <refsect1>
 228         <title>Affected by</title>
 229         <para>None.</para>
 230       </refsect1>
 231       <refsect1>
 232         <title>Exceptional Situations</title>
 233         <para>None.</para>
 234       </refsect1>
 235     </refentry>
 236
 237     <refentry id="get-slot-pointer">
 238       <refnamediv>
 239         <refname>get-slot-pointer</refname>
 240         <refpurpose>Retrieves a pointer from a slot of a structure.
 241         </refpurpose>
 242         <refclass>Macro</refclass>
 243       </refnamediv>
 244       <refsynopsisdiv>
 245         <title>Syntax</title>
 246         <synopsis>
 247           <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
 248         </synopsis>
 249       </refsynopsisdiv>
 250       <refsect1>
 251         <title>Arguments and Values</title>
 252         <variablelist>
 253           <varlistentry>
 254             <term><parameter>obj</parameter></term>
 255             <listitem>
 256               <para>A pointer to foreign structure.
 257               </para>
 258             </listitem>
 259           </varlistentry>
 260           <varlistentry>
 261             <term><parameter>type</parameter></term>
 262             <listitem>
 263               <para>A name of the foreign structure.
 264               </para>
 265             </listitem>
 266           </varlistentry>
 267           <varlistentry>
 268             <term><parameter>field</parameter></term>
 269             <listitem>
 270               <para>A name of the desired field in foreign structure.
 271               </para>
 272             </listitem>
 273           </varlistentry>
 274           <varlistentry>
 275             <term><returnvalue>pointer</returnvalue></term>
 276             <listitem>
 277               <para>The value of the field in the structure.
 278               </para>
 279             </listitem>
 280           </varlistentry>
 281         </variablelist>
 282       </refsect1>
 283       <refsect1>
 284         <title>Description</title>
 285         <para>
 286           This is similar to <function>get-slot-value</function>. It
 287           is used when the value of a slot is a pointer type.
 288         </para>
 289       </refsect1>
 290       <refsect1>
 291         <title>Examples</title>
 292         <screen>
 293 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
 294         </screen>
 295       </refsect1>
 296       <refsect1>
 297         <title>Side Effects</title>
 298         <para>None.</para>
 299       </refsect1>
 300       <refsect1>
 301         <title>Affected by</title>
 302         <para>None.</para>
 303       </refsect1>
 304       <refsect1>
 305         <title>Exceptional Situations</title>
 306         <para>None.</para>
 307       </refsect1>
 308     </refentry>
 309
 310
 311     <refentry id="def-array-pointer">
 312       <refnamediv>
 313         <refname>def-array-pointer</refname>
 314         <refpurpose>Defines a pointer to a array of type.
 315         </refpurpose>
 316         <refclass>Macro</refclass>
 317       </refnamediv>
 318       <refsynopsisdiv>
 319         <title>Syntax</title>
 320         <synopsis>
 321           <function>def-array-pointer</function> <replaceable>name type</replaceable>
 322         </synopsis>
 323       </refsynopsisdiv>
 324       <refsect1>
 325         <title>Arguments and Values</title>
 326         <variablelist>
 327           <varlistentry>
 328             <term><parameter>name</parameter></term>
 329             <listitem>
 330               <para>A name of the new foreign type.
 331               </para>
 332             </listitem>
 333           </varlistentry>
 334           <varlistentry>
 335             <term><parameter>type</parameter></term>
 336             <listitem>
 337               <para>The foreign type of the array elements.
 338               </para>
 339             </listitem>
 340           </varlistentry>
 341         </variablelist>
 342       </refsect1>
 343       <refsect1>
 344         <title>Description</title>
 345         <para>
 346           Defines a type tat is a pointer to an array of type.
 347         </para>
 348       </refsect1>
 349       <refsect1>
 350         <title>Examples</title>
 351         <screen>
 352 (def-array-pointer byte-array-pointer :unsigned-char)
 353         </screen>
 354       </refsect1>
 355       <refsect1>
 356         <title>Side Effects</title>
 357         <para>Defines a new foreign type.</para>
 358       </refsect1>
 359       <refsect1>
 360         <title>Affected by</title>
 361         <para>None.</para>
 362       </refsect1>
 363       <refsect1>
 364         <title>Exceptional Situations</title>
 365         <para>None.</para>
 366       </refsect1>
 367     </refentry>
 368
 369
 370     <refentry id="deref-array">
 371       <refnamediv>
 372         <refname>deref-array</refname>
 373         <refpurpose>Deference an array.
 374         </refpurpose>
 375         <refclass>Macro</refclass>
 376       </refnamediv>
 377       <refsynopsisdiv>
 378         <title>Syntax</title>
 379         <synopsis>
 380           <function>deref-array</function> <replaceable>array type position</replaceable> => <returnvalue>value</returnvalue>
 381         </synopsis>
 382       </refsynopsisdiv>
 383       <refsect1>
 384         <title>Arguments and Values</title>
 385         <variablelist>
 386           <varlistentry>
 387             <term><parameter>array</parameter></term>
 388             <listitem>
 389               <para>A foreign array.
 390               </para>
 391             </listitem>
 392           </varlistentry>
 393           <varlistentry>
 394             <term><parameter>type</parameter></term>
 395             <listitem>
 396               <para>The foreign type of the array.
 397               </para>
 398             </listitem>
 399           </varlistentry>
 400           <varlistentry>
 401             <term><parameter>position</parameter></term>
 402             <listitem>
 403               <para>An integer specifying the position to retrieve from
 404 the array.
 405               </para>
 406             </listitem>
 407           </varlistentry>
 408           <varlistentry>
 409             <term><returnvalue>value</returnvalue></term>
 410             <listitem>
 411               <para>The value stored in the position of the array.
 412               </para>
 413             </listitem>
 414           </varlistentry>
 415         </variablelist>
 416       </refsect1>
 417       <refsect1>
 418         <title>Description</title>
 419         <para>
 420           Dereferences (retrieves) the value of an array element.
 421         </para>
 422       </refsect1>
 423       <refsect1>
 424         <title>Examples</title>
 425         <screen>
 426 (def-array-pointer ca :char)
 427 (let ((fs (convert-to-foreign-string "ab")))
 428    (values (null-char-p (deref-array fs 'ca 0))
 429            (null-char-p (deref-array fs 'ca 2))))
 430 => &nil;
 431    &t;
 432         </screen>
 433       </refsect1>
 434       <refsect1>
 435         <title>Notes</title>
 436         <para>
 437   The TYPE argument is ignored for CL implementations other than
 438   AllegroCL. If you want to cast a pointer to another type use
 439   WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
 440         </para>
 441       </refsect1>
 442       <refsect1>
 443         <title>Side Effects</title>
 444         <para>None.</para>
 445       </refsect1>
 446       <refsect1>
 447         <title>Affected by</title>
 448         <para>None.</para>
 449       </refsect1>
 450       <refsect1>
 451         <title>Exceptional Situations</title>
 452         <para>None.</para>
 453       </refsect1>
 454     </refentry>
 455
 456     <refentry id="def-union">
 457       <refnamediv>
 458         <refname>def-union</refname>
 459         <refpurpose>Defines a foreign union type.
 460         </refpurpose>
 461         <refclass>Macro</refclass>
 462       </refnamediv>
 463       <refsynopsisdiv>
 464         <title>Syntax</title>
 465         <synopsis>
 466           <function>def-union</function> <replaceable>name &amp;rest fields</replaceable>
 467         </synopsis>
 468       </refsynopsisdiv>
 469       <refsect1>
 470         <title>Arguments and Values</title>
 471         <variablelist>
 472           <varlistentry>
 473             <term><parameter>name</parameter></term>
 474             <listitem>
 475               <para>A name of the new union type.
 476               </para>
 477             </listitem>
 478           </varlistentry>
 479           <varlistentry>
 480             <term><parameter>fields</parameter></term>
 481             <listitem>
 482               <para>A list of fields of the union.
 483               </para>
 484             </listitem>
 485           </varlistentry>
 486         </variablelist>
 487       </refsect1>
 488       <refsect1>
 489         <title>Description</title>
 490         <para>
 491           Defines a foreign union type.
 492         </para>
 493       </refsect1>
 494       <refsect1>
 495         <title>Examples</title>
 496         <screen>
 497 (def-union test-union
 498   (a-char :char)
 499   (an-int :int))
 500
 501 (let ((u (allocate-foreign-object 'test-union))
 502   (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
 503   (prog1
 504     (ensure-char-character (get-slot-value u 'test-union 'a-char))
 505     (free-foreign-object u)))
 506 => #\A
 507         </screen>
 508       </refsect1>
 509       <refsect1>
 510         <title>Side Effects</title>
 511         <para>Defines a new foreign type.</para>
 512       </refsect1>
 513       <refsect1>
 514         <title>Affected by</title>
 515         <para>None.</para>
 516       </refsect1>
 517       <refsect1>
 518         <title>Exceptional Situations</title>
 519         <para>None.</para>
 520       </refsect1>
 521     </refentry>
 522
 523 </reference>
 524