struct

structs.zig

  1. // Declare a struct.
  2. // Zig gives no guarantees about the order of fields and the size of
  3. // the struct but the fields are guaranteed to be ABI-aligned.
  4. const Point = struct {
  5.     x: f32,
  6.     y: f32,
  7. };
  9. // Maybe we want to pass it to OpenGL so we want to be particular about
  10. // how the bytes are arranged.
  11. const Point2 = packed struct {
  12.     x: f32,
  13.     y: f32,
  14. };
  17. // Declare an instance of a struct.
  18. const p = Point {
  19.     .x = 0.12,
  20.     .y = 0.34,
  21. };
  23. // Maybe we're not ready to fill out some of the fields.
  24. var p2 = Point {
  25.     .x = 0.12,
  26.     .y = undefined,
  27. };
  29. // Structs can have methods
  30. // Struct methods are not special, they are only namespaced
  31. // functions that you can call with dot syntax.
  32. const Vec3 = struct {
  33.     x: f32,
  34.     y: f32,
  35.     z: f32,
  37.     pub fn init(x: f32, y: f32, z: f32) Vec3 {
  38.         return Vec3 {
  39.             .x = x,
  40.             .y = y,
  41.             .z = z,
  42.         };
  43.     }
  45.     pub fn dot(self: Vec3, other: Vec3) f32 {
  46.         return self.x * other.x + self.y * other.y + self.z * other.z;
  47.     }
  48. };
  50. const assert = @import("std").debug.assert;
  51. test "dot product" {
  52.     const v1 = Vec3.init(1.0, 0.0, 0.0);
  53.     const v2 = Vec3.init(0.0, 1.0, 0.0);
  54.     assert(v1.dot(v2) == 0.0);
  56.     // Other than being available to call with dot syntax, struct methods are
  57.     // not special. You can reference them as any other declaration inside
  58.     // the struct:
  59.     assert(Vec3.dot(v1, v2) == 0.0);
  60. }
  62. // Structs can have global declarations.
  63. // Structs can have 0 fields.
  64. const Empty = struct {
  65.     pub const PI = 3.14;
  66. };
  67. test "struct namespaced variable" {
  68.     assert(Empty.PI == 3.14);
  69.     assert(@sizeOf(Empty) == 0);
  71.     // you can still instantiate an empty struct
  72.     const does_nothing = Empty {};
  73. }
  75. // struct field order is determined by the compiler for optimal performance.
  76. // however, you can still calculate a struct base pointer given a field pointer:
  77. fn setYBasedOnX(x: *f32, y: f32) void {
  78.     const point = @fieldParentPtr(Point, "x", x);
  79.     point.y = y;
  80. }
  81. test "field parent pointer" {
  82.     var point = Point {
  83.         .x = 0.1234,
  84.         .y = 0.5678,
  85.     };
  86.     setYBasedOnX(&point.x, 0.9);
  87.     assert(point.y == 0.9);
  88. }
  90. // You can return a struct from a function. This is how we do generics
  91. // in Zig:
  92. fn LinkedList(comptime T: type) type {
  93.     return struct {
  94.         pub const Node = struct {
  95.             prev: ?*Node,
  96.             next: ?*Node,
  97.             data: T,
  98.         };
  100.         first: ?*Node,
  101.         last:  ?*Node,
  102.         len:   usize,
  103.     };
  104. }
  106. test "linked list" {
  107.     // Functions called at compile-time are memoized. This means you can
  108.     // do this:
  109.     assert(LinkedList(i32) == LinkedList(i32));
  111.     var list = LinkedList(i32) {
  112.         .first = null,
  113.         .last = null,
  114.         .len = 0,
  115.     };
  116.     assert(list.len == 0);
  118.     // Since types are first class values you can instantiate the type
  119.     // by assigning it to a variable:
  120.     const ListOfInts = LinkedList(i32);
  121.     assert(ListOfInts == LinkedList(i32));
  123.     var node = ListOfInts.Node {
  124.         .prev = null,
  125.         .next = null,
  126.         .data = 1234,
  127.     };
  128.     var list2 = LinkedList(i32) {
  129.         .first = &node,
  130.         .last = &node,
  131.         .len = 1,
  132.     };
  133.     assert(list2.first.?.data == 1234);
  134. }
  1. $ zig test structs.zig
  2. 1/4 test "dot product"...OK
  3. 2/4 test "struct namespaced variable"...OK
  4. 3/4 test "field parent pointer"...OK
  5. 4/4 test "linked list"...OK
  6. All 4 tests passed.

Default Field Values

Each struct field may have an expression indicating the default field value. Such expressions are executed at comptime, and allow the field to be omitted in a struct literal expression:

test.zig

  1. const Foo = struct {
  2.     a: i32 = 1234,
  3.     b: i32,
  4. };
  6. test "default struct initialization fields" {
  7.     const x = Foo{
  8.         .b = 5,
  9.     };
  10.     if (x.a + x.b != 1239) {
  11.         @compileError("it's even comptime known!");
  12.     }
  13. }
  1. $ zig test test.zig
  2. 1/1 test "default struct initialization fields"...OK
  3. All 1 tests passed.

extern struct

An extern struct has in-memory layout guaranteed to match the C ABI for the target.

This kind of struct should only be used for compatibility with the C ABI. Every other use case should be solved with packed struct or normal struct.

See also:

packed struct

Unlike normal structs, packed structs have guaranteed in-memory layout:

  • Fields remain in the order declared.
  • There is no padding between fields.
  • Zig supports arbitrary width Integers and although normally, integers with fewer than 8 bits will still use 1 byte of memory, in packed structs, they use exactly their bit width.
  • bool fields use exactly 1 bit.
  • A packed enum field uses exactly the bit width of its integer tag type.
  • A packed union field uses exactly the bit width of the union field with the largest bit width.
  • Non-ABI-aligned fields are packed into the smallest possible ABI-aligned integers in accordance with the target endianness.

This means that a packed struct can participate in a @bitCast or a @ptrCast to reinterpret memory. This even works at comptime:

test.zig

  1. const std = @import("std");
  2. const builtin = std.builtin;
  3. const assert = std.debug.assert;
  5. const Full = packed struct {
  6.     number: u16,
  7. };
  8. const Divided = packed struct {
  9.     half1: u8,
  10.     quarter3: u4,
  11.     quarter4: u4,
  12. };
  14. test "@bitCast between packed structs" {
  15.     doTheTest();
  16.     comptime doTheTest();
  17. }
  19. fn doTheTest() void {
  20.     assert(@sizeOf(Full) == 2);
  21.     assert(@sizeOf(Divided) == 2);
  22.     var full = Full{ .number = 0x1234 };
  23.     var divided = @bitCast(Divided, full);
  24.     switch (builtin.endian) {
  25.         .Big => {
  26.             assert(divided.half1 == 0x12);
  27.             assert(divided.quarter3 == 0x3);
  28.             assert(divided.quarter4 == 0x4);
  29.         },
  30.         .Little => {
  31.             assert(divided.half1 == 0x34);
  32.             assert(divided.quarter3 == 0x2);
  33.             assert(divided.quarter4 == 0x1);
  34.         },
  35.     }
  36. }
  1. $ zig test test.zig
  2. 1/1 test "@bitCast between packed structs"...OK
  3. All 1 tests passed.

Zig allows the address to be taken of a non-byte-aligned field:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. const BitField = packed struct {
  5.     a: u3,
  6.     b: u3,
  7.     c: u2,
  8. };
  10. var foo = BitField{
  11.     .a = 1,
  12.     .b = 2,
  13.     .c = 3,
  14. };
  16. test "pointer to non-byte-aligned field" {
  17.     const ptr = &foo.b;
  18.     assert(ptr.* == 2);
  19. }
  1. $ zig test test.zig
  2. 1/1 test "pointer to non-byte-aligned field"...OK
  3. All 1 tests passed.

However, the pointer to a non-byte-aligned field has special properties and cannot be passed when a normal pointer is expected:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. const BitField = packed struct {
  5.     a: u3,
  6.     b: u3,
  7.     c: u2,
  8. };
  10. var bit_field = BitField{
  11.     .a = 1,
  12.     .b = 2,
  13.     .c = 3,
  14. };
  16. test "pointer to non-bit-aligned field" {
  17.     assert(bar(&bit_field.b) == 2);
  18. }
  20. fn bar(x: *const u3) u3 {
  21.     return x.*;
  22. }
  1. $ zig test test.zig
  2. ./docgen_tmp/test.zig:17:26: error: expected type '*const u3', found '*align(:3:1) u3'
  3.     assert(bar(&bit_field.b) == 2);
  4.                          ^

In this case, the function bar cannot be called becuse the pointer to the non-ABI-aligned field mentions the bit offset, but the function expects an ABI-aligned pointer.

Pointers to non-ABI-aligned fields share the same address as the other fields within their host integer:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. const BitField = packed struct {
  5.     a: u3,
  6.     b: u3,
  7.     c: u2,
  8. };
  10. var bit_field = BitField{
  11.     .a = 1,
  12.     .b = 2,
  13.     .c = 3,
  14. };
  16. test "pointer to non-bit-aligned field" {
  17.     assert(@ptrToInt(&bit_field.a) == @ptrToInt(&bit_field.b));
  18.     assert(@ptrToInt(&bit_field.a) == @ptrToInt(&bit_field.c));
  19. }
  1. $ zig test test.zig
  2. 1/1 test "pointer to non-bit-aligned field"...OK
  3. All 1 tests passed.

This can be observed with @bitOffsetOf and byteOffsetOf:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. const BitField = packed struct {
  5.     a: u3,
  6.     b: u3,
  7.     c: u2,
  8. };
  10. test "pointer to non-bit-aligned field" {
  11.     comptime {
  12.         assert(@bitOffsetOf(BitField, "a") == 0);
  13.         assert(@bitOffsetOf(BitField, "b") == 3);
  14.         assert(@bitOffsetOf(BitField, "c") == 6);
  16.         assert(@byteOffsetOf(BitField, "a") == 0);
  17.         assert(@byteOffsetOf(BitField, "b") == 0);
  18.         assert(@byteOffsetOf(BitField, "c") == 0);
  19.     }
  20. }
  1. $ zig test test.zig
  2. 1/1 test "pointer to non-bit-aligned field"...OK
  3. All 1 tests passed.

Packed structs have 1-byte alignment. However if you have an overaligned pointer to a packed struct, Zig should correctly understand the alignment of fields. However there is a bug:

test.zig

  1. const S = packed struct {
  2.     a: u32,
  3.     b: u32,
  4. };
  5. test "overaligned pointer to packed struct" {
  6.     var foo: S align(4) = undefined;
  7.     const ptr: *align(4) S = &foo;
  8.     const ptr_to_b: *u32 = &ptr.b;
  9. }
  1. $ zig test test.zig
  2. ./docgen_tmp/test.zig:8:32: error: expected type '*u32', found '*align(1) u32'
  3.     const ptr_to_b: *u32 = &ptr.b;
  4.                                ^

When this bug is fixed, the above test in the documentation will unexpectedly pass, which will cause the test suite to fail, notifying the bug fixer to update these docs.

It's also planned to be able to set alignment of struct fields.

Using packed structs with volatile is problematic, and may be a compile error in the future. For details on this subscribe to this issue. TODO update these docs with a recommendation on how to use packed structs with MMIO (the use case for volatile packed structs) once this issue is resolved. Don't worry, there will be a good solution for this use case in zig.

Struct Naming

Since all structs are anonymous, Zig infers the type name based on a few rules.

  • If the struct is in the initialization expression of a variable, it gets named after that variable.
  • If the struct is in the return expression, it gets named after the function it is returning from, with the parameter values serialized.
  • Otherwise, the struct gets a name such as (anonymous struct at file.zig:7:38).

struct_name.zig

  1. const std = @import("std");
  3. pub fn main() void {
  4.     const Foo = struct {};
  5.     std.debug.warn("variable: {}\n", .{@typeName(Foo)});
  6.     std.debug.warn("anonymous: {}\n", .{@typeName(struct {})});
  7.     std.debug.warn("function: {}\n", .{@typeName(List(i32))});
  8. }
  10. fn List(comptime T: type) type {
  11.     return struct {
  12.         x: T,
  13.     };
  14. }
  1. $ zig build-exe struct_name.zig
  2. $ ./struct_name
  3. variable: Foo
  4. anonymous: struct:6:51
  5. function: List(i32)

Anonymous Struct Literals

Zig allows omitting the struct type of a literal. When the result is coerced, the struct literal will directly instantiate the result location, with no copy:

struct_result.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. const Point = struct {x: i32, y: i32};
  6. test "anonymous struct literal" {
  7.     var pt: Point = .{
  8.         .x = 13,
  9.         .y = 67,
  10.     };
  11.     assert(pt.x == 13);
  12.     assert(pt.y == 67);
  13. }
  1. $ zig test struct_result.zig
  2. 1/1 test "anonymous struct literal"...OK
  3. All 1 tests passed.

The struct type can be inferred. Here the result location does not include a type, and so Zig infers the type:

struct_anon.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. test "fully anonymous struct" {
  5.     dump(.{
  6.         .int = @as(u32, 1234),
  7.         .float = @as(f64, 12.34),
  8.         .b = true,
  9.         .s = "hi",
  10.     });
  11. }
  13. fn dump(args: var) void {
  14.     assert(args.int == 1234);
  15.     assert(args.float == 12.34);
  16.     assert(args.b);
  17.     assert(args.s[0] == 'h');
  18.     assert(args.s[1] == 'i');
  19. }
  1. $ zig test struct_anon.zig
  2. 1/1 test "fully anonymous struct"...OK
  3. All 1 tests passed.

See also: