| 1 |
c: support for C types and ABI interoperation |
| 2 |
|
| 3 |
types::c provides type aliases that are compatible with standard C builtin types |
| 4 |
and typedefs, as specified ISO/IEC 9899:2024 and POSIX.1-2024, as well as |
| 5 |
convenience functions for working with C types. This module is useful for C |
| 6 |
interop, for instance if an external function returns a [[long]] or an |
| 7 |
[[ssize]], or if you need to convert between a C string and a Hare string. The |
| 8 |
types provided here shouldn't be used by most Hare code. |
| 9 |
|
| 10 |
Some C types aren't provided by this module, since they are provided by the Hare |
| 11 |
language itself: |
| 12 |
|
| 13 |
- bool (or _Bool) -> bool |
| 14 |
- double, _Float64 -> f64 |
| 15 |
- float, _Float32 -> f32 |
| 16 |
- intN_t (<stdint.h>) -> iN (where N is a power of two from 8 to 64) |
| 17 |
- nullptr_t (<stddef.h>) -> null |
| 18 |
- (signed) int -> int |
| 19 |
- size_t (<stddef.h>) -> size |
| 20 |
- uintN_t (<stdint.h>) -> uN (where N is a power of two from 8 to 64) |
| 21 |
- unsigned int -> uint |
| 22 |
- uintptr_t (<stdint.h>) -> uintptr |
| 23 |
- va_list (<stdarg.h>) -> valist |
| 24 |
|
| 25 |
Some C types are mostly compatible with Hare types, with minor differences: |
| 26 |
|
| 27 |
- C's void is an incomplete opaque type, which is also used to indicate the |
| 28 |
absence of a value. Hare provides void as a zero-size type, and opaque as an |
| 29 |
undefined-size opaque type. |
| 30 |
- Hare doesn't have builtin imaginary or complex types, though complex types |
| 31 |
with equivalent represention to their C counterparts are declared in |
| 32 |
[[math::complex::]]. Hare doesn't allow casting between real and complex types |
| 33 |
like C does. |
| 34 |
|
| 35 |
[[io::off]] is compatible with off_t as defined in <sys/types.h> and specified |
| 36 |
by POSIX.1. |
| 37 |
|
| 38 |
The following C types are *not* supported by Hare: |
| 39 |
|
| 40 |
- 128-bit integer types (__int128) (will be supported in a future release) |
| 41 |
- Bit-precise integer types (_BitInt) |
| 42 |
- Decimal floating point types: _Decimal32, _Decimal64, _Decimal128 |
| 43 |
- long double |
| 44 |
- Extended floating point types: _Float128 (__float128), _Float16 (__fp16), etc. |
| 45 |
- Packed types: __m64, __m128, __m256, __m512 |
| 46 |
- Integer types with any width other than 8, 16, 32, or 64 |
| 47 |
- max_align_t |
| 48 |
- float_t and double_t (see below) |
| 49 |
|
| 50 |
Equivalents for float_t and double_t (as defined in <math.h>) aren't provided by |
| 51 |
this module, because they're dependent on the value of FLT_EVAL_METHOD, which is |
| 52 |
unknown. |
| 53 |
|
| 54 |
Note that Hare's fixed-width integer types are NOT guaranteed to be |
| 55 |
ABI-compatible with C's bit-precise integer types. |
| 56 |
|
| 57 |
When doing interop with C, be aware that Hare doesn't convert array parameters |
| 58 |
to pointers like C does; function prototypes will need to be adjusted |
| 59 |
accordingly. There's one exception: valist is passed by reference on targets |
| 60 |
which define it as an array type in C (such as x86_64). |
| 61 |
|
| 62 |
Additional low-level or implementation-specific types may be defined in |
| 63 |
[[rt::]]. |