# Important Builtins in Zig 1.16

### Important Builtins in Zig 1.16

This chapter covered the builtins you will see most often as a beginner.

A builtin is a compiler-provided function. Its name starts with `@`.

```zig
@import("std")
@sizeOf(u32)
@alignOf(u32)
@intCast(x)
```

These are not standard library functions. They are part of the language.

#### Type and Module Builtins

Use these to import code or work with types.

| Builtin | Meaning |
|---|---|
| `@import` | Load a Zig module or source file |
| `@TypeOf` | Get the type of a value |
| `@typeInfo` | Inspect a type |
| `@Type` | Build a type from type information |
| `@typeName` | Get the name of a type |

Example:

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

const x = 123;
const T = @TypeOf(x);

pub fn main() void {
    std.debug.print("{s}\n", .{@typeName(T)});
}
```

#### Memory Layout Builtins

Use these when you need to understand how data is stored.

| Builtin | Meaning |
|---|---|
| `@sizeOf` | Number of bytes used by a type |
| `@alignOf` | Required memory alignment of a type |
| `@offsetOf` | Byte offset of a struct field |
| `@bitSizeOf` | Number of bits used by a type |

Example:

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

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

pub fn main() void {
    std.debug.print("size: {}\n", .{@sizeOf(Point)});
    std.debug.print("align: {}\n", .{@alignOf(Point)});
}
```

#### Conversion Builtins

Use these when converting values explicitly.

| Builtin | Meaning |
|---|---|
| `@intCast` | Convert between integer types, checking that the value fits |
| `@truncate` | Keep only the low bits of an integer |
| `@floatCast` | Convert between floating-point types |
| `@floatFromInt` | Convert an integer to a float |
| `@intFromFloat` | Convert a float to an integer |
| `@bitCast` | Reinterpret bits as another type of the same size |

The important distinction is this:

```text
@intCast preserves numeric meaning.
@truncate preserves low bits.
@bitCast preserves raw representation.
```

Example:

```zig
const x: u16 = 300;

const a: u8 = @truncate(x); // 44
```

Do not use `@truncate` when you mean “safe integer conversion.” Use `@intCast` with a range check.

#### Pointer and Memory Builtins

Use these when working close to raw memory.

| Builtin | Meaning |
|---|---|
| `@ptrCast` | Reinterpret a pointer as another pointer type |
| `@alignCast` | Assert stronger pointer alignment |
| `@constCast` | Remove const from a pointer |
| `@volatileCast` | Change volatile qualification |
| `@memcpy` | Copy memory from source to destination |
| `@memset` | Fill memory with a repeated value |

Example:

```zig
var buffer = [_]u8{0} ** 5;
const text = "hello";

@memcpy(&buffer, text);
```

Use pointer casts carefully. They do not move memory, fix alignment, or prove that the pointed-to memory has the new type.

#### Compile-Time Control Builtins

Use these to guide compilation.

| Builtin | Meaning |
|---|---|
| `@compileError` | Stop compilation with a message |
| `@compileLog` | Print compile-time debugging information |
| `@setEvalBranchQuota` | Raise the compile-time branch limit |
| `@panic` | Stop the running program with a message |

Example:

```zig
comptime {
    if (@sizeOf(usize) != 8) {
        @compileError("this program requires a 64-bit target");
    }
}
```

`@compileError` is for invalid code or unsupported targets.

`@panic` is for runtime states that should not happen.

#### File Builtins

Use these to include build-time files.

| Builtin | Meaning |
|---|---|
| `@embedFile` | Embed a file’s bytes into the executable |

Example:

```zig
const help_text = @embedFile("help.txt");
```

The file is read during compilation. The final executable contains the bytes.

#### Beginner Rule

Most Zig programs use only a small set of builtins often:

```zig
@import
@sizeOf
@alignOf
@TypeOf
@intCast
@truncate
@floatCast
@bitCast
@ptrCast
@memcpy
@panic
@compileError
@embedFile
```

Learn these first.

Do not try to memorize every builtin at once. Read each one by asking:

```text
What special thing is the compiler being asked to do?
```

That question usually explains the code.