diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 58 |
1 files changed, 57 insertions, 1 deletions
@@ -100,6 +100,7 @@ Join the discussion, share demos, ask questions, or report bugs in the official - [Named Constraints](#named-constraints) - [15. Build Directives](#15-build-directives) - [16. Keywords](#16-keywords) + - [17. C Interoperability](#17-c-interoperability) - [Standard Library](#standard-library) - [Tooling](#tooling) - [Language Server (LSP)](#language-server-lsp) @@ -204,7 +205,11 @@ let y: const int = 10; // Read-only (Type qualified) | Type | C Equivalent | Description | |:---|:---|:---| -| `int`, `uint` | `int`, `unsigned int` | Platform standard integer | +| `int`, `uint` | `int32_t`, `uint32_t` | 32-bit signed/unsigned integer | +| `c_char`, `c_uchar` | `char`, `unsigned char` | C char / unsigned char (Interop) | +| `c_short`, `c_ushort` | `short`, `unsigned short` | C short / unsigned short (Interop) | +| `c_int`, `c_uint` | `int`, `unsigned int` | C int / unsigned int (Interop) | +| `c_long`, `c_ulong` | `long`, `unsigned long` | C long / unsigned long (Interop) | | `I8` .. `I128` or `i8` .. `i128` | `int8_t` .. `__int128_t` | Signed fixed-width integers | | `U8` .. `U128` or `u8` .. `u128` | `uint8_t` .. `__uint128_t` | Unsigned fixed-width integers | | `isize`, `usize` | `ptrdiff_t`, `size_t` | Pointer-sized integers | @@ -217,6 +222,12 @@ let y: const int = 10; // Read-only (Type qualified) | `iN` (for example, `i256`) | `_BitInt(N)` | Arbitrary bit-width signed integer (C23) | | `uN` (for example, `u42`) | `unsigned _BitInt(N)` | Arbitrary bit-width unsigned integer (C23) | +> **Best Practices for Portable Code** +> +> - Use **Portable Types** (`int`, `uint`, `i64`, `u8`, etc.) for all pure Zen C logic. `int` is guaranteed to be 32-bit signed on all architectures. +> - Use **C Interop Types** (`c_int`, `c_char`, `c_long`) **only** when interacting with C libraries (FFI). Their size varies by platform and C compiler (e.g. `c_long` size differs between Windows and Linux). +> - Use `isize` and `usize` for array indexing and memory pointer arithmetic. + ### 3. Aggregate Types #### Arrays @@ -1092,6 +1103,51 @@ The following identifiers are reserved because they are keywords in C11: #### Operators `and`, `or` +### 17. C Interoperability + +Zen C offers two ways to interact with C code: **Trusted Imports** (Convenient) and **Explicit FFI** (Safe/Precise). + +#### Method 1: Trusted Imports (Convenient) + +You can import a C header directly using the `import` keyword with the `.h` extension. This treats the header as a module and assumes all symbols accessed through it exist. + +```zc +//> link: -lm +import "math.h" as c_math; + +fn main() { + // Compiler trusts correctness; emits 'cos(...)' directly + let x = c_math::cos(3.14159); +} +``` + +> **Pros**: Zero boilerplate. Access everything in the header immediately. +> **Cons**: No type safety from Zen C (errors caught by C compiler later). + +#### Method 2: Explicit FFI (Safe) + +For strict type checking or when you don't want to include the text of a header, use `extern fn`. + +```zc +include <stdio.h> // Emits #include <stdio.h> in generated C + +// Define strict signature +extern fn printf(fmt: char*, ...) -> c_int; + +fn main() { + printf("Hello FFI: %d\n", 42); // Type checked by Zen C +} +``` + +> **Pros**: Zen C ensures types match. +> **Cons**: Requires manual declaration of functions. + +#### `import` vs `include` + +- **`import "file.h"`**: Registers the header as a named module. Enables implicit access to symbols (for example, `file::function()`). +- **`include <file.h>`**: Purely emits `#include <file.h>` in the generated C code. Does not introduce any symbols to the Zen C compiler; you must use `extern fn` to access them. + + --- ## Standard Library |