Debian Codegraph @

types/c/README

raw
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::]].