# Appendix A. Zig Syntax Summary

## Appendix A. Zig Syntax Summary

This appendix summarizes the core syntax of Zig 0.16. It is a compact reference, not a tutorial.

## A.1 Comments

Single-line comments begin with `//`.

```zig
// this is a comment
```

Documentation comments begin with `///`.

```zig
/// add two integers
fn add(a: i32, b: i32) i32 {
    return a + b;
}
```

Container-level documentation comments begin with `//!`.

```zig
//! small utility library
```

## A.2 Declarations

Variables use `var`.

```zig
var count: i32 = 10;
```

Constants use `const`.

```zig
const limit = 100;
```

Type annotations are optional when the compiler can infer the type.

```zig
const name = "zig";
```

## A.3 Primitive Types

| Type | Meaning |
|---|---|
| `i32` | signed 32-bit integer |
| `u64` | unsigned 64-bit integer |
| `f32` | 32-bit float |
| `bool` | boolean |
| `usize` | pointer-sized unsigned integer |
| `isize` | pointer-sized signed integer |
| `void` | no value |
| `noreturn` | expression never returns |

## A.4 Integer Literals

```zig
const a = 123;
const b = 0xff;
const c = 0b1010;
const d = 0o755;
```

Underscores improve readability.

```zig
const million = 1_000_000;
```

## A.5 Strings

Strings are byte slices.

```zig
const text = "hello";
```

String type:

```zig
[]const u8
```

Multiline strings use escaping.

```zig
const text =
    \\hello
    \\zig
;
```

## A.6 Arrays and Slices

Fixed-size array:

```zig
const values = [4]i32{ 1, 2, 3, 4 };
```

Slice:

```zig
const part = values[1..3];
```

Array length:

```zig
values.len
```

## A.7 Pointers

Single-item pointer:

```zig
var value: i32 = 10;

const ptr: *i32 = &value;
```

Dereference:

```zig
ptr.*
```

Pointer assignment:

```zig
ptr.* = 20;
```

Many-item pointer:

```zig
[*]u8
```

Optional pointer:

```zig
?*i32
```

## A.8 Functions

Function declaration:

```zig
fn add(a: i32, b: i32) i32 {
    return a + b;
}
```

Public function:

```zig
pub fn main() void {}
```

Error-returning function:

```zig
fn parse(text: []const u8) !i32 {
    ...
}
```

Generic function:

```zig
fn identity(value: anytype) @TypeOf(value) {
    return value;
}
```

## A.9 Blocks and Scope

Blocks introduce scope.

```zig
{
    const x = 10;
}
```

Blocks are expressions.

```zig
const n = blk: {
    break :blk 42;
};
```

## A.10 Control Flow

`if` expression:

```zig
if (x > 0) {
    ...
} else {
    ...
}
```

`switch` expression:

```zig
switch (value) {
    0 => {},
    1 => {},
    else => {},
}
```

`while` loop:

```zig
while (n < 10) : (n += 1) {
    ...
}
```

`for` loop:

```zig
for (items) |item| {
    ...
}
```

## A.11 Optionals

Optional type:

```zig
?i32
```

Null value:

```zig
null
```

Unwrapping:

```zig
const value = maybe orelse 0;
```

Optional capture:

```zig
if (maybe) |value| {
    ...
}
```

## A.12 Errors

Error set:

```zig
const ParseError = error{
    Invalid,
    Overflow,
};
```

Error union:

```zig
ParseError!i32
```

Propagate error:

```zig
const n = try parse(text);
```

Handle error:

```zig
parse(text) catch 0;
```

## A.13 Defer

`defer` runs at scope exit.

```zig
defer file.close();
```

`errdefer` runs only on error.

```zig
errdefer allocator.free(buffer);
```

## A.14 Structs

Struct declaration:

```zig
const Point = struct {
    x: i32,
    y: i32,
};
```

Initialization:

```zig
const p = Point{
    .x = 10,
    .y = 20,
};
```

Method:

```zig
const Counter = struct {
    value: i32,

    pub fn inc(self: *Counter) void {
        self.value += 1;
    }
};
```

## A.15 Enums

```zig
const Color = enum {
    red,
    green,
    blue,
};
```

## A.16 Unions

Tagged union:

```zig
const Value = union(enum) {
    int: i32,
    float: f64,
};
```

Switch on union:

```zig
switch (value) {
    .int => |n| {},
    .float => |x| {},
}
```

## A.17 Allocators

Allocation:

```zig
const memory = try allocator.alloc(u8, 1024);
```

Free memory:

```zig
allocator.free(memory);
```

## A.18 Testing

Test block:

```zig
test "addition" {
    try std.testing.expect(1 + 1 == 2);
}
```

Run tests:

```sh
zig test main.zig
```

## A.19 Imports

Import standard library:

```zig
const std = @import("std");
```

Import source file:

```zig
const math = @import("math.zig");
```

## A.20 Builtin Functions

Builtin functions begin with `@`.

```zig
@TypeOf(x)
@sizeOf(i32)
@intCast(value)
@ptrCast(ptr)
@memcpy(dst, src)
```

## A.21 Formatting

Print formatted text:

```zig
std.debug.print("value = {d}\n", .{n});
```

Common format specifiers:

| Specifier | Meaning |
|---|---|
| `{d}` | decimal integer |
| `{x}` | hexadecimal |
| `{b}` | binary |
| `{s}` | string |
| `{any}` | generic formatting |

## A.22 Build Commands

| Command | Meaning |
|---|---|
| `zig run main.zig` | build and run |
| `zig build-exe main.zig` | build executable |
| `zig test main.zig` | run tests |
| `zig build` | run build script |
| `zig fmt file.zig` | format source |

## A.23 File Structure

Typical project layout:

```text
project/
    build.zig
    build.zig.zon
    src/
        main.zig
```