## Aggregate Types

## Overview

Aggregate types are comprised of one or more primitive types.

## `def-enum`

Defines a &C; enumeration.
Macro

### Syntax

         def-enum name fields &key separator-string

### Arguments and Values

`name`

  A symbol that names the enumeration.

`fields`

  A list of field defintions. Each definition can be a symbol or a list of two elements. Symbols get assigned a value of the current counter which starts at `0` and increments by `1` for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second position is the value to assign the the symbol. The current counter gets set to `1+` this value.

`separator-string`

  A string that governs the creation of constants. The default is `"#"`.

### Description

Declares a &C; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant values are created by the `concatenation` of the enumeration name, separator-string, and field symbol. Also creates a foreign type with the name `name` of type `:int`.

### Examples

    (def-enum abc (:a :b :c))
    ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
    ;; the foreign type "abc" to be :int

    (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
    ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
    ;; the foreign type efoo to be :int

### Side Effects

Creates a :int foreign type, defines constants.

### Affected by

None.

### Exceptional Situations

None.

## `def-struct`

Defines a &C; structure.
Macro

### Syntax

         def-struct name &rest fields

### Arguments and Values

`name`

  A symbol that names the structure.

`fields`

  A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.

### Description

Declares a structure. A special type is available as a slot in the field. It is a pointer that points to an instance of the parent structure. It's type is `:pointer-self`.

### Examples

    (def-struct foo (a :unsigned-int)
      (b (* :char))
      (c (:array :int 10))
      (next :pointer-self))

### Side Effects

Creates a foreign type.

### Affected by

None.

### Exceptional Situations

None.

## `get-slot-value`

Retrieves a value from a slot of a structure.
Macro

### Syntax

         get-slot-value obj type field => value

### Arguments and Values

`obj`

  A pointer to foreign structure.

`type`

  A name of the foreign structure.

`field`

  A name of the desired field in foreign structure.

value

  The value of the field in the structure.

### Description

Accesses a slot value from a structure. This is generalized and can be used with `setf`.

### Examples

    (get-slot-value foo-ptr 'foo-structure 'field-name)
    (setf (get-slot-value foo-ptr 'foo-structure 'field-name) 10)

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `get-slot-pointer`

Retrieves a pointer from a slot of a structure.
Macro

### Syntax

         get-slot-pointer obj type field => pointer

### Arguments and Values

`obj`

  A pointer to foreign structure.

`type`

  A name of the foreign structure.

`field`

  A name of the desired field in foreign structure.

pointer

  The value of the field in the structure.

### Description

This is similar to `get-slot-value`. It is used when the value of a slot is a pointer type.

### Examples

    (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `def-array-pointer`

Defines a pointer to a array of type.
Macro

### Syntax

         def-array-pointer name type

### Arguments and Values

`name`

  A name of the new foreign type.

`type`

  The foreign type of the array elements.

### Description

Defines a type tat is a pointer to an array of type.

### Examples

    (def-array-pointer byte-array-pointer :unsigned-char)

### Side Effects

Defines a new foreign type.

### Affected by

None.

### Exceptional Situations

None.

## `deref-array`

Deference an array.
Macro

### Syntax

         deref-array array type position => value

### Arguments and Values

`array`

  A foreign array.

`type`

  The foreign type of the array.

`position`

  An integer specifying the position to retrieve from the array.

value

  The value stored in the position of the array.

### Description

Dereferences (retrieves) the value of an array element.

### Examples

    (def-array-pointer ca :char)
      (let ((fs (convert-to-foreign-string "ab")))
        (values (null-char-p (deref-array fs 'ca 0))
        (null-char-p (deref-array fs 'ca 2))))
    => &nil;
       &t;

### Notes

The TYPE argument is ignored for CL implementations other than AllegroCL. If you want to cast a pointer to another type use WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `def-union`

Defines a foreign union type.
Macro

### Syntax

         def-union name &rest fields

### Arguments and Values

`name`

  A name of the new union type.

`fields`

  A list of fields of the union.

### Description

Defines a foreign union type.

### Examples

    (def-union test-union
      (a-char :char)
      (an-int :int))

    (let ((u (allocate-foreign-object 'test-union)))
      (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
      (prog1
         (ensure-char-character (get-slot-value u 'test-union 'a-char))
       (free-foreign-object u)))
    => #\A

### Side Effects

Defines a new foreign type.

### Affected by

None.

### Exceptional Situations

None.