1.5 Designator classes

1.5.3 Fundamental numeric type designator classes

This section describes the pre-defined designator classes for fundamental C numeric types. On page 10 we saw that none of these designator types are instantiable: a number on one side of the interface is converted to a number on the other side with the same value.

There are some additional details to note about integer representations. Because Dylan's integer representations do not match C's exactly, for each of the C integer types there are three designator classes that can be used to translate Dylan representations to that C integer. The categories are plain, unsafe, and raw integers.

Plain integer designators -- of which the class <C-unsigned-short> is an example -- translate C integer values to instances of <integer>. If the integer being translated is too big for the destination, the C-FFI signals an error. There are two ways this can happen.

On export, the C-FFI signals an error if the Dylan value has more significant bits than the C integer.

: This can happen if, for example, the designator is <C-unsigned-short>, and the Dylan value is negative, or if unsigned short on that platform is 16 bits wide, but the Dylan integer has more than 16 significant bits. The check will be omitted if the compiler can determine that no Dylan value outside the safe range can reach there. This can be done using a limited integer type.

On import into Dylan, the C-FFI signals an error if it cannot represent the C value using a Dylan <integer>.

: This can happen with any C integer type that is more than 30 bits wide. The size of a Dylan <integer> depends on the particular platform, but it is guaranteed to be at least 30 bits in length.

The C-FFI never signals an error for the unsafe designator classes -- of which the class <C-unsafe-unsigned-short> is an example -- but if the destination is too small for the value, the most significant bits of the value are chopped off to fit into the destination. Because there is no checking, using the unsafe designator classes brings a very small performance improvement, but nonetheless you should not use them unless you are certain you will not lose any bits.

Raw designator classes -- of which the class <C-raw-unsigned-int> is an example -- represent the integer on the Dylan side as a <machine-word>. An instance of <machine-word> is guaranteed to have enough bits to represent any C long value, or any C void * value. Note that a <machine-word> value may still have more significant bits than some C integer types, and so the C-FFI may still signal an overflow error if the <machine-word> value, interpreted as indicated by the designator, has more significant bits than may be held in the indicated C type.

Table 1.1 shows all raw, plain, and unsafe integer designator types exported from the C-FFI module.

Table 1.1 The integer designator classes and their mappings.
Designator name	C type	Dylan type(s)
`<C-int>`	`int`	`<integer>`
`<C-raw-int>`	`int`	`<machine-word>`
`<C-unsafe-int>`	`int`	`<integer>`
`<C-raw-signed-int>`	`signed int`	`<machine-word>`
`<C-unsafe-signed int>`	`signed int`	`<integer>`
`<C-signed-int>`	`signed int`	`<integer>`
`<C-raw-unsigned-int>`	`unsigned int`	`<machine-word>`
`<C-unsafe-unsigned-int>`	`unsigned int`	`<integer>`
`<C-unsigned-int>`	`unsigned int`	`<integer>`
`<C-unsigned-long>`	`unsigned long`	`<integer>`
`<C-signed-long>`	`signed long`	`<integer>`
`<C-unsafe-unsigned-long>`	`unsigned long`	`<integer>`
`<C-unsafe-signed-long>`	`signed long`	`<integer>`
`<C-raw-unsigned-long>`	`unsigned long`	`<machine-word>`
`<C-raw-signed-long>`	`signed long`	`<machine-word>`
`<C-unsigned-short>`	`unsigned short`	`<integer>`
`<C-signed-short>`	`signed short`	`<integer>`
`<C-unsafe-unsigned-short>`	`unsigned short`	`<integer>`
`<C-unsafe-signed-short>`	`signed short`	`<integer>`
`<C-raw-unsigned-short>`	`unsigned short`	`<machine-word>`
`<C-raw-signed-short>`	`signed short`	`<machine-word>`
`<C-unsigned-char>`	`unsigned char`	`<integer>`
`<C-signed-char>`	`signed char`	`<integer>`
`<C-unsafe-unsigned-char>`	`unsigned char`	`<integer>`
`<C-unsafe-signed-char>`	`signed char`	`<integer>`
`<C-raw-unsigned-char>`	`unsigned char`	`<machine-word>`
`<C-raw-signed-char>`	`signed char`	`<machine-word>`
`<C-char>`	`char`	`<integer>`
`<C-unsafe-char>`	`char`	`<integer>`
`<C-raw-char>`	`char`	`<machine-word>`

For each of the fundamental integer designator types, <C-xxx>, there is also a type designating pointers to that type called <C-xxx*>. In addition, the C-FFI defines methods for pointer-value and pointer-value-setter, with appropriate translation behavior for each of the types designating pointers to the fundamental integer designator types.