3.10 Enumerations and Masks

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 3 | C Types

3.1 | Type Constructors
3.2 | Numeric Types
3.3 | Other Atomic Types
3.4 | String Types
3.5 | Pointer Types
3.6 | Function Types
3.7 | C Struct Types
3.8 | C Array Types
3.9 | C Union Types
3.10 | Enumerations and Masks

On this page:

_ enum
_ bitmask

top contents ← prev up next →

#### 3.10`` Enumerations and Masks🔗ℹ

Although the constructors below are described as procedures, they are implemented as syntax, so that error messages can report a type name where the syntactic context implies one.

> procedure (_enum symbols [basetype #:unknown unknown]) → ctype?
> symbols : list?
> basetype : ctype? = _ufixint
> unknown : any/c = (lambda (x) (error ....))

Takes a list of symbols and generates an enumeration type. The enumeration maps between a symbol in the given symbols list and corresponding integers, counting from 0.

To call a foreign function that takes an enum as a parameter simply provide the symbol of the desired enum as an argument.

> ; example sdl call
> (sdl-create-window "title" ... 'SDL_WINDOW_OPENGL)

The list symbols can also set the values of symbols by putting '= and an exact integer after the symbol. For example, the list '(x y = 10 z) maps 'x to 0, 'y to 10, and 'z to 11.

The basetype argument specifies the base type to use.

The unknown argument specifies the result of converting an unknown integer from the foreign side: it can be a one-argument function to be applied on the integer, or a value to return instead. The default is to throw an exception.

Examples:

> ; example from snappy-c.h
> > (define _snappy_status
> (_enum '(ok = 0
> invalid_input
> buffer_too_small)))

Note that the default basetype is _ufixint. This differs from C enumerations that can use any value in _fixint. Any _enum using negative values should use _fixint for the base type.

Example:

> > (define _negative_enum
> (_enum '(unkown = -1
> error = 0
> ok = 1)
> _fixint))

> procedure (_bitmask symbols [basetype]) → ctype?
> symbols : (or symbol? list?)
> basetype : ctype? = _uint

Similar to _enum, but the resulting mapping translates a list of symbols to a number and back, using bitwise-ior on the values of individual symbols, where A single symbol is equivalent to a list containing just the symbol.

In other words, to call a foreign function that uses bitmask parameters simply call the procedure with the list of wanted flags.

> ; example call from curl_global_init in curl.h
> (curl-global-init '(CURL_GLOBAL_SSL CURL_GLOBAL_WIN32))

When a symbol does not have a given value (via '= after the symbol in symbols), its value is the next power of 2 greater than the previous symbol’s assignment (or 1 for the first symbol).

The default basetype is _uint, since high bits are often used for flags.

Examples:

> ; example from curl.h
> > (define _curl_global_flag
> (_bitmask `(CURL_GLOBAL_SSL = 1
> CURL_GLOBAL_WIN32 = 2
> CURL_GLOBAL_ALL = 3
> CURL_GLOBAL_NOTHING = 0
> CURL_GLOBAL_DEFAULT = 3
> CURL_GLOBAL_ACK_EINTR = 4)))
> ; example from XOrg
> > (define _Modifiers
> (_bitmask '(ShiftMask = 1
> LockMask = 2
> ControlMask = 4
> Mod1Mask = 8
> Mod2Mask = 16
> Mod3Mask = 32
> Mod4Mask = 64
> Mod5Mask = 128
> Button1Mask = 256
> Button2Mask = 512
> Button3Mask = 1024
> Button4Mask = 2048
> Button5Mask = 4096
> Any = 32768)))

top contents ← prev up next →