diff --git a/internal/worldgen/gen.go b/internal/worldgen/gen.go
index 77f63168..dfbf1d17 100644
--- a/internal/worldgen/gen.go
+++ b/internal/worldgen/gen.go
@@ -46,6 +46,7 @@ type Generator struct {
// 常用方块状态（启动时从注册表解析一次）
stone, grass, dirt, bedrock, sand, water, snowB, log, leaves block.State
coal, iron, gold, diamond, redstone block.State
+ planks, cobble, torch block.State // 村庄建筑用
}
// New 创建生成器；必须的方块缺注册时报错。
@@ -105,6 +106,15 @@ func New(reg *block.Registry, seed int64, biomeScale, heightScale, caveDensity f
if g.redstone, err = must(reg, "redstone_ore"); err != nil {
return nil, err
}
+ if g.planks, err = must(reg, "oak_planks"); err != nil {
+ return nil, err
+ }
+ if g.cobble, err = must(reg, "cobblestone"); err != nil {
+ return nil, err
+ }
+ if g.torch, err = must(reg, "torch"); err != nil {
+ return nil, err
+ }
return g, nil
}
@@ -237,6 +247,8 @@ func (g *Generator) Generate(cx, cz int32) *chunk.Chunk {
}
// 树后处理 pass（世界生态.md §3.1：边缘留白避免跨区块，树冠不出界）
g.placeTrees(c)
+ // 村庄结构 pass（村民系统.md §2：网格撒点 + 水井 + 房屋）
+ g.placeVillage(c, cx, cz)
return c
}
diff --git a/internal/worldgen/gen_test.go b/internal/worldgen/gen_test.go
index 89bb77a9..081db144 100644
--- a/internal/worldgen/gen_test.go
+++ b/internal/worldgen/gen_test.go
@@ -84,6 +84,48 @@ func TestTerrainStructure(t *testing.T) {
}
}
+// TestVillage 村庄生成：存在村庄中心的区块应有木板/圆石建筑（村民系统.md §2）。
+func TestVillage(t *testing.T) {
+ reg := loadReg(t)
+ planks, _ := reg.ID("oak_planks")
+ cobble, _ := reg.ID("cobblestone")
+ g, err := New(reg, 424242, 0.005, 0.01, 0.1)
+ if err != nil {
+ t.Fatalf("创建生成器失败: %v", err)
+ }
+ // 扫描网格点找村庄
+ found := 0
+ for gx := int32(-2); gx <= 2; gx++ {
+ for gz := int32(-2); gz <= 2; gz++ {
+ vx, vz := g.villageCenter(gx, gz)
+ b := g.biomeAt(vx, vz)
+ if b != biomePlains && b != biomeForest {
+ continue
+ }
+ cx, cz := floorDiv32(vx, 16), floorDiv32(vz, 16)
+ ch := g.Generate(cx, cz)
+ plankCnt, cobbleCnt := 0, 0
+ snap := ch.Snapshot()
+ for i := 0; i < 16*16*256; i++ {
+ switch snap[i].ID() {
+ case planks:
+ plankCnt++
+ case cobble:
+ cobbleCnt++
+ }
+ }
+ // 建筑跨区块：中心区块至少包含部分房屋/水井
+ if plankCnt < 20 || cobbleCnt == 0 {
+ t.Fatalf("村庄区块 (%d,%d) 建筑过少: 木板 %d 圆石 %d", cx, cz, plankCnt, cobbleCnt)
+ }
+ found++
+ }
+ }
+ if found == 0 {
+ t.Fatal("5×5 网格点内未发现村庄")
+ }
+}
+
// TestOres 验证矿物只出现在规定深度区间（挖矿与矿物.md §2：y=100 只允许石头/煤矿）。
func TestOres(t *testing.T) {
reg := loadReg(t)
diff --git a/internal/worldgen/village.go b/internal/worldgen/village.go
new file mode 100644
index 00000000..e43918b7
--- /dev/null
+++ b/internal/worldgen/village.go
@@ -0,0 +1,130 @@
+// 村庄生成：结构 pass（村民系统.md §2、世界生态.md §3）。
+//
+// 规则：村庄按 384 格网格撒点（噪声抖动选位，仅平原/森林群系），
+// 每个村庄水井 + 3 间房屋；建筑按绝对坐标定义，跨区块落位（世界生成.md §4）。
+package worldgen
+
+import (
+ "mc/internal/block"
+ "mc/internal/chunk"
+)
+
+// 村庄参数（村民系统.md §2）。
+const (
+ villageSpacing = 384 // 村庄网格间距（格）
+ villageJitter = 96 // 中心抖动半径
+ villageRadius = 32 // 村庄建筑最大半径（区块跨越判定）
+)
+
+// villageCenter 返回网格点 (gx, gz) 派生出的村庄中心绝对坐标。
+func (g *Generator) villageCenter(gx, gz int32) (int32, int32) {
+ jx := int32(g.ore.Eval2(float64(gx)*7.7+91, float64(gz)*3.1+17) * villageJitter)
+ jz := int32(g.ore.Eval2(float64(gx)*5.3+57, float64(gz)*8.9+29) * villageJitter)
+ return gx*villageSpacing + villageSpacing/2 + jx, gz*villageSpacing + villageSpacing/2 + jz
+}
+
+// placeVillage 生成跨越本区块的村庄建筑（世界生成.md §4 跨区块安全）。
+func (g *Generator) placeVillage(c *chunk.Chunk, cx, cz int32) {
+ minX, maxX := cx*16, cx*16+15
+ minZ, maxZ := cz*16, cz*16+15
+ // 附近的网格点（±1 个网格内即可覆盖）
+ for dgx := int32(-1); dgx <= 1; dgx++ {
+ for dgz := int32(-1); dgz <= 1; dgz++ {
+ gx := floorDiv32(cx*16, villageSpacing) + dgx
+ gz := floorDiv32(cz*16, villageSpacing) + dgz
+ vx, vz := g.villageCenter(gx, gz)
+ // 村庄建筑范围与本区块相交？
+ if vx < minX-villageRadius || vx > maxX+villageRadius || vz < minZ-villageRadius || vz > maxZ+villageRadius {
+ continue
+ }
+ // 群系白名单（沙漠/雪原不建村）
+ b := g.biomeAt(vx, vz)
+ if b != biomePlains && b != biomeForest {
+ continue
+ }
+ // 水井 + 房屋（绝对坐标，逐块过滤到当前区块）
+ h := int32(g.heightAt(vx, vz))
+ g.placeWellAbs(c, cx, cz, vx, h, vz)
+ offsets := [][2]int32{{-12, -8}, {8, -10}, {-4, 12}}
+ for i, o := range offsets {
+ hx, hz := vx+o[0], vz+o[1]
+ hh := int32(g.heightAt(hx, hz))
+ g.placeHouseAbs(c, cx, cz, hx, hh, hz, uint64(gx)*73856093^uint64(gz)*19349663^uint64(i))
+ }
+ }
+ }
+}
+
+// inChunk 判定绝对坐标是否属于区块 (cx, cz)。
+func inChunk(x, z, cx, cz int32) bool {
+ return floorDiv32(x, 16) == cx && floorDiv32(z, 16) == cz
+}
+
+// setAbs 绝对坐标写入（跨区块过滤，世界生成.md §4）。
+func (g *Generator) setAbs(c *chunk.Chunk, cx, cz, x, y, z int32, s block.State) {
+ if y < 0 || y >= chunk.Height {
+ return
+ }
+ if !inChunk(x, z, cx, cz) {
+ return
+ }
+ c.Fill(int(x-cx*16), int(y), int(z-cz*16), s)
+}
+
+// placeWellAbs 水井：圆石环 + 中心水（3×3，村民系统.md §2 布局）。
+func (g *Generator) placeWellAbs(c *chunk.Chunk, cx, cz, wx, h, wz int32) {
+ for dx := int32(-1); dx <= 1; dx++ {
+ for dz := int32(-1); dz <= 1; dz++ {
+ if dx == 0 && dz == 0 {
+ g.setAbs(c, cx, cz, wx+dx, h+1, wz+dz, g.water) // 井水
+ } else {
+ g.setAbs(c, cx, cz, wx+dx, h+1, wz+dz, g.cobble) // 井沿
+ }
+ }
+ }
+}
+
+// placeHouseAbs 村民房屋：木板地基 + 墙高 3（门洞）+ 平顶外沿 + 四角火把。
+// 布局与 entity.Blueprint 一致（村民系统.md §6.2）。
+func (g *Generator) placeHouseAbs(c *chunk.Chunk, cx, cz, hx, h, hz int32, seed uint64) {
+ w, d := int32(5+seed%2), int32(5) // 5–6 × 5
+ for x := int32(0); x < w; x++ {
+ for z := int32(0); z < d; z++ {
+ g.setAbs(c, cx, cz, hx+x, h+1, hz+z, g.planks)
+ }
+ }
+ // 墙（2 层，南侧门洞）
+ for y := int32(2); y <= 3; y++ {
+ for x := int32(0); x < w; x++ {
+ for z := int32(0); z < d; z++ {
+ edge := x == 0 || x == w-1 || z == 0 || z == d-1
+ if !edge {
+ continue
+ }
+ if y == 2 && z == d-1 && x == w/2 {
+ continue // 门洞
+ }
+ g.setAbs(c, cx, cz, hx+x, h+y, hz+z, g.planks)
+ }
+ }
+ }
+ // 屋顶外沿
+ for x := int32(-1); x <= w; x++ {
+ for z := int32(-1); z <= d; z++ {
+ g.setAbs(c, cx, cz, hx+x, h+4, hz+z, g.planks)
+ }
+ }
+ // 四角火把
+ for _, cc := range [4][2]int32{{0, 0}, {w - 1, 0}, {0, d - 1}, {w - 1, d - 1}} {
+ g.setAbs(c, cx, cz, hx+cc[0], h+3, hz+cc[1], g.torch)
+ }
+}
+
+// floorDiv32 负安全除法（villageCenter 网格定位）。
+func floorDiv32(a, b int32) int32 {
+ q := a / b
+ if a%b < 0 {
+ q--
+ }
+ return q
+}
diff --git a/tools/zig-x86_64-windows-0.14.1/LICENSE b/tools/zig-x86_64-windows-0.14.1/LICENSE
new file mode 100644
index 00000000..9ce01373
--- /dev/null
+++ b/tools/zig-x86_64-windows-0.14.1/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (Expat)
+
+Copyright (c) Zig contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/tools/zig-x86_64-windows-0.14.1/README.md b/tools/zig-x86_64-windows-0.14.1/README.md
new file mode 100644
index 00000000..818a7d67
--- /dev/null
+++ b/tools/zig-x86_64-windows-0.14.1/README.md
@@ -0,0 +1,147 @@
+
+
+A general-purpose programming language and toolchain for maintaining
+**robust**, **optimal**, and **reusable** software.
+
+https://ziglang.org/
+
+## Documentation
+
+If you are looking at this README file in a source tree, please refer to the
+**Release Notes**, **Language Reference**, or **Standard Library
+Documentation** corresponding to the version of Zig that you are using by
+following the appropriate link on the
+[download page](https://ziglang.org/download).
+
+Otherwise, you're looking at a release of Zig, so you can find the language
+reference at `doc/langref.html`, and the standard library documentation by
+running `zig std`, which will open a browser tab.
+
+## Installation
+
+ * [download a pre-built binary](https://ziglang.org/download/)
+ * [install from a package manager](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager)
+ * [bootstrap zig for any target](https://github.com/ziglang/zig-bootstrap)
+
+A Zig installation is composed of two things:
+
+1. The Zig executable
+2. The lib/ directory
+
+At runtime, the executable searches up the file system for the lib/ directory,
+relative to itself:
+
+* lib/
+* lib/zig/
+* ../lib/
+* ../lib/zig/
+* (and so on)
+
+In other words, you can **unpack a release of Zig anywhere**, and then begin
+using it immediately. There is no need to install it globally, although this
+mechanism supports that use case too (i.e. `/usr/bin/zig` and `/usr/lib/zig/`).
+
+## Building from Source
+
+Ensure you have the required dependencies:
+
+ * CMake >= 3.15
+ * System C/C++ Toolchain
+ * LLVM, Clang, LLD development libraries == 19.x
+
+Then it is the standard CMake build process:
+
+```
+mkdir build
+cd build
+cmake ..
+make install
+```
+
+For more options, tips, and troubleshooting, please see the
+[Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source)
+page on the wiki.
+
+## Building from Source without LLVM
+
+In this case, the only system dependency is a C compiler.
+
+```
+cc -o bootstrap bootstrap.c
+./bootstrap
+```
+
+This produces a `zig2` executable in the current working directory. This is a
+"stage2" build of the compiler,
+[without LLVM extensions](https://github.com/ziglang/zig/issues/16270), and is
+therefore lacking these features:
+- Release mode optimizations
+- [aarch64 machine code backend](https://github.com/ziglang/zig/issues/21172)
+- [@cImport](https://github.com/ziglang/zig/issues/20630)
+- [zig translate-c](https://github.com/ziglang/zig/issues/20875)
+- [Ability to compile assembly files](https://github.com/ziglang/zig/issues/21169)
+- [Some ELF linking features](https://github.com/ziglang/zig/issues/17749)
+- [Most COFF/PE linking features](https://github.com/ziglang/zig/issues/17751)
+- [Some WebAssembly linking features](https://github.com/ziglang/zig/issues/17750)
+- [Ability to create import libs from def files](https://github.com/ziglang/zig/issues/17807)
+- [Ability to create static archives from object files](https://github.com/ziglang/zig/issues/9828)
+- Ability to compile C, C++, Objective-C, and Objective-C++ files
+
+However, a compiler built this way does provide a C backend, which may be
+useful for creating system packages of Zig projects using the system C
+toolchain. **In this case, LLVM is not needed!**
+
+Furthermore, a compiler built this way provides an LLVM backend that produces
+bitcode files, which may be compiled into object files via a system Clang
+package. This can be used to produce system packages of Zig applications
+without the Zig package dependency on LLVM.
+
+## Contributing
+
+[Donate monthly](https://ziglang.org/zsf/).
+
+Zig is Free and Open Source Software. We welcome bug reports and patches from
+everyone. However, keep in mind that Zig governance is BDFN (Benevolent
+Dictator For Now) which means that Andrew Kelley has final say on the design
+and implementation of everything.
+
+One of the best ways you can contribute to Zig is to start using it for an
+open-source personal project.
+
+This leads to discovering bugs and helps flesh out use cases, which lead to
+further design iterations of Zig. Importantly, each issue found this way comes
+with real world motivations, making it straightforward to explain the reasoning
+behind proposals and feature requests.
+
+You will be taken much more seriously on the issue tracker if you have a
+personal project that uses Zig.
+
+The issue label
+[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
+exists to help you find issues that are **limited in scope and/or knowledge of
+Zig internals.**
+
+Please note that issues labeled
+[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
+but do not also have the
+[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
+label are still under consideration, and efforts to implement such a proposal
+have a high risk of being wasted. If you are interested in a proposal which is
+still under consideration, please express your interest in the issue tracker,
+providing extra insights and considerations that others have not yet expressed.
+The most highly regarded argument in such a discussion is a real world use case.
+
+For more tips, please see the
+[Contributing](https://github.com/ziglang/zig/wiki/Contributing) page on the
+wiki.
+
+## Community
+
+The Zig community is decentralized. Anyone is free to start and maintain their
+own space for Zig users to gather. There is no concept of "official" or
+"unofficial". Each gathering place has its own moderators and rules. Users are
+encouraged to be aware of the social structures of the spaces they inhabit, and
+work purposefully to facilitate spaces that align with their values.
+
+Please see the [Community](https://github.com/ziglang/zig/wiki/Community) wiki
+page for a public listing of social spaces.
diff --git a/tools/zig-x86_64-windows-0.14.1/doc/langref.html b/tools/zig-x86_64-windows-0.14.1/doc/langref.html
new file mode 100644
index 00000000..87654e14
--- /dev/null
+++ b/tools/zig-x86_64-windows-0.14.1/doc/langref.html
@@ -0,0 +1,15939 @@
+
+
+
+
+
+
+ Documentation - The Zig Programming Language
+
+
+
+
+
+
+ Zig is a general-purpose programming language and toolchain for maintaining
+ robust, optimal, and reusable software.
+
+
+
Robust
Behavior is correct even for edge cases such as out of memory.
+
Optimal
Write programs the best way they can behave and perform.
+
Reusable
The same code works in many environments which have different
+ constraints.
+
Maintainable
Precisely communicate intent to the compiler and
+ other programmers. The language imposes a low overhead to reading code and is
+ resilient to changing requirements and environments.
+
+
+ Often the most efficient way to learn something new is to see examples, so
+ this documentation shows how to use each of Zig's features. It is
+ all on one page so you can search with your browser's search tool.
+
+
+ The code samples in this document are compiled and tested as part of the main test suite of Zig.
+
+
+ This HTML document depends on no external files, so you can use it offline.
+
+ Zig's Standard Library contains commonly used algorithms, data structures, and definitions to help you build programs or libraries.
+ You will see many examples of Zig's Standard Library used in this documentation. To learn more about the Zig Standard Library,
+ visit the link above.
+
+
+ Alternatively, the Zig Standard Library documentation is provided with each Zig distribution. It can be rendered via a local webserver with:
+
+ Most of the time, it is more appropriate to write to stderr rather than stdout, and
+ whether or not the message is successfully written to the stream is irrelevant.
+ For this common case, there is a simpler API:
+
+ Zig supports 3 types of comments. Normal comments are ignored, but doc comments
+ and top-level doc comments are used by the compiler to generate the package documentation.
+
+
+ The generated documentation is still experimental, and can be produced with:
+
+ Shell
zig test -femit-docs main.zig
+
+ comments.zig
const print = @import("std").debug.print;
+
+pubfnmain() void {
+ // Comments in Zig start with "//" and end at the next LF byte (end of line).
+ // The line below is a comment and won't be executed.
+
+ //print("Hello?", .{});
+
+ print("Hello, world!\n", .{}); // another comment
+}
+ There are no multiline comments in Zig (e.g. like /* */
+ comments in C). This allows Zig to have the property that each line
+ of code can be tokenized out of context.
+
+ A doc comment is one that begins with exactly three slashes (i.e.
+ /// but not ////);
+ multiple doc comments in a row are merged together to form a multiline
+ doc comment. The doc comment documents whatever immediately follows it.
+
+ doc_comments.zig
/// A structure for storing a timestamp, with nanosecond precision (this is a
+/// multiline doc comment).
+const Timestamp = struct {
+ /// The number of seconds since the epoch (this is also a doc comment).
+ seconds: i64, // signed so we can represent pre-1970 (not a doc comment)
+ /// The number of nanoseconds past the second (doc comment again).
+ nanos: u32,
+
+ /// Returns a `Timestamp` struct representing the Unix epoch; that is, the
+ /// moment of 1970 Jan 1 00:00:00 UTC (this is a doc comment too).
+ pubfnunixEpoch() Timestamp {
+ return Timestamp{
+ .seconds = 0,
+ .nanos = 0,
+ };
+ }
+};
+
+
+ Doc comments are only allowed in certain places; it is a compile error to
+ have a doc comment in an unexpected place, such as in the middle of an expression,
+ or just before a non-doc comment.
+
$ zig build-obj invalid_doc-comment.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/invalid_doc-comment.zig:1:16: error: expected type expression, found 'a document comment'
+/// doc-comment
+ ^
+
+
+
+ unattached_doc-comment.zig
pubfnmain() void {}
+
+/// End of file
Shell
$ zig build-obj unattached_doc-comment.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/unattached_doc-comment.zig:3:1: error: unattached documentation comment
+/// End of file
+^~~~~~~~~~~~~~~
+
+
+
+
+ Doc comments can be interleaved with normal comments. Currently, when producing
+ the package documentation, normal comments are merged with doc comments.
+
+ A top-level doc comment is one that begins with two slashes and an exclamation
+ point: //!; it documents the current module.
+
+
+ It is a compile error if a top-level doc comment is not placed at the start
+ of a container, before any expressions.
+
+ tldoc_comments.zig
//! This module provides functions for retrieving the current date and
+//! time with varying degrees of precision and accuracy. It does not
+//! depend on libc, but will use functions from it if available.
+
+const S = struct {
+ //! Top level comments are allowed inside a container other than a module,
+ //! but it is not very useful. Currently, when producing the package
+ //! documentation, these comments are ignored.
+};
16-bit floating point (10-bit mantissa) IEEE-754-2008 binary16
+
+
+
f32
+
float
+
32-bit floating point (23-bit mantissa) IEEE-754-2008 binary32
+
+
+
f64
+
double
+
64-bit floating point (52-bit mantissa) IEEE-754-2008 binary64
+
+
+
f80
+
long double
+
80-bit floating point (64-bit mantissa) IEEE-754-2008 80-bit extended precision
+
+
+
f128
+
_Float128
+
128-bit floating point (112-bit mantissa) IEEE-754-2008 binary128
+
+
+
bool
+
bool
+
true or false
+
+
+
anyopaque
+
void
+
Used for type-erased pointers.
+
+
+
void
+
(none)
+
Always the value void{}
+
+
+
noreturn
+
(none)
+
the type of break, continue, return, unreachable, and while (true) {}
+
+
+
type
+
(none)
+
the type of types
+
+
+
anyerror
+
(none)
+
an error code
+
+
+
comptime_int
+
(none)
+
Only allowed for comptime-known values. The type of integer literals.
+
+
+
comptime_float
+
(none)
+
Only allowed for comptime-known values. The type of float literals.
+
+
+
+
+
+ In addition to the integer types above, arbitrary bit-width integers can be referenced by using
+ an identifier of i or u followed by digits. For example, the identifier
+ i7 refers to a signed 7-bit integer. The maximum allowed bit-width of an
+ integer type is 65535.
+
+ String literals are constant single-item Pointers to null-terminated byte arrays.
+ The type of string literals encodes both the length, and the fact that they are null-terminated,
+ and thus they can be coerced to both Slices and
+ Null-Terminated Pointers.
+ Dereferencing string literals converts them to Arrays.
+
+
+ Because Zig source code is UTF-8 encoded, any
+ non-ASCII bytes appearing within a string literal in source code carry
+ their UTF-8 meaning into the content of the string in the Zig program;
+ the bytes are not modified by the compiler. It is possible to embed
+ non-UTF-8 bytes into a string literal using \xNN notation.
+
+
Indexing into a string containing non-ASCII bytes returns individual
+ bytes, whether valid UTF-8 or not.
+
+ Unicode code point literals have type comptime_int, the same as
+ Integer Literals. All Escape Sequences are valid in both string literals
+ and Unicode code point literals.
+
+ string_literals.zig
const print = @import("std").debug.print;
+const mem = @import("std").mem; // will be used to compare bytes
+
+pubfnmain() void {
+ const bytes = "hello";
+ print("{}\n", .{@TypeOf(bytes)}); // *const [5:0]u8
+ print("{d}\n", .{bytes.len}); // 5
+ print("{c}\n", .{bytes[1]}); // 'e'
+ print("{d}\n", .{bytes[5]}); // 0
+ print("{}\n", .{'e' == '\x65'}); // true
+ print("{d}\n", .{'\u{1f4a9}'}); // 128169
+ print("{d}\n", .{'💯'}); // 128175
+ print("{u}\n", .{'⚡'});
+ print("{}\n", .{mem.eql(u8, "hello", "h\x65llo")}); // true
+ print("{}\n", .{mem.eql(u8, "💯", "\xf0\x9f\x92\xaf")}); // also true
+ const invalid_utf8 = "\xff\xfe"; // non-UTF-8 strings are possible with \xNN notation.
+ print("0x{x}\n", .{invalid_utf8[1]}); // indexing them returns individual bytes...
+ print("0x{x}\n", .{"💯"[1]}); // ...as does indexing part-way through non-ASCII characters
+}
+ Multiline string literals have no escapes and can span across multiple lines.
+ To start a multiline string literal, use the \\ token. Just like a comment,
+ the string literal goes until the end of the line. The end of the line is
+ not included in the string literal.
+ However, if the next line begins with \\ then a newline is appended and
+ the string literal continues.
+
Use the const keyword to assign a value to an identifier:
+ constant_identifier_cannot_change.zig
const x = 1234;
+
+fnfoo() void {
+ // It works at file scope as well as inside functions.
+ const y = 5678;
+
+ // Once assigned, an identifier cannot be changed.
+ y += 1;
+}
+
+pubfnmain() void {
+ foo();
+}
Shell
$ zig build-exe constant_identifier_cannot_change.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/constant_identifier_cannot_change.zig:8:7: error: cannot assign to constant
+ y += 1;
+ ~~^~~~
+referenced by:
+ main: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/constant_identifier_cannot_change.zig:12:8
+ posixCallMainAndExit: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22
+ 4 reference(s) hidden; use '-freference-trace=6' to see all references
+
+
+
+
const applies to all of the bytes that the identifier immediately addresses. Pointers have their own const-ness.
+
If you need a variable that you can modify, use the var keyword:
+ undefined can be coerced to any type.
+ Once this happens, it is no longer possible to detect that the value is undefined.
+ undefined means the value could be anything, even something that is nonsense
+ according to the type. Translated into English, undefined means "Not a meaningful
+ value. Using this value would be a bug. The value will be unused, or overwritten before being used."
+
+
+ In Debug mode, Zig writes 0xaa bytes to undefined memory. This is to catch
+ bugs early, and to help detect use of undefined memory in a debugger. However, this behavior is only an
+ implementation feature, not a language semantic, so it is not guaranteed to be observable to code.
+
+ A destructuring assignment can separate elements of indexable aggregate types
+ (Tuples, Arrays, Vectors):
+
+ destructuring_to_existing.zig
const print = @import("std").debug.print;
+
+pubfnmain() void {
+ var x: u32 = undefined;
+ var y: u32 = undefined;
+ var z: u32 = undefined;
+
+ const tuple = .{ 1, 2, 3 };
+
+ x, y, z = tuple;
+
+ print("tuple: x = {}, y = {}, z = {}\n", .{x, y, z});
+
+ const array = [_]u32{ 4, 5, 6 };
+
+ x, y, z = array;
+
+ print("array: x = {}, y = {}, z = {}\n", .{x, y, z});
+
+ const vector: @Vector(3, u32) = .{ 7, 8, 9 };
+
+ x, y, z = vector;
+
+ print("vector: x = {}, y = {}, z = {}\n", .{x, y, z});
+}
Shell
$ zig build-exe destructuring_to_existing.zig
+$ ./destructuring_to_existing
+tuple: x = 1, y = 2, z = 3
+array: x = 4, y = 5, z = 6
+vector: x = 7, y = 8, z = 9
+
+
+
+ A destructuring expression may only appear within a block (i.e. not at container scope).
+ The left hand side of the assignment must consist of a comma separated list,
+ each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration:
+
+ destructuring_mixed.zig
const print = @import("std").debug.print;
+
+pubfnmain() void {
+ var x: u32 = undefined;
+
+ const tuple = .{ 1, 2, 3 };
+
+ x, var y : u32, const z = tuple;
+
+ print("x = {}, y = {}, z = {}\n", .{x, y, z});
+
+ // y is mutable
+ y = 100;
+
+ // You can use _ to throw away unwanted values.
+ _, x, _ = tuple;
+
+ print("x = {}", .{x});
+}
Shell
$ zig build-exe destructuring_mixed.zig
+$ ./destructuring_mixed
+x = 1, y = 2, z = 3
+x = 2
+
+
+
+ A destructure may be prefixed with the comptime keyword, in which case the entire
+ destructure expression is evaluated at comptime. All vars declared would
+ be comptimevars and all expressions (both result locations and the assignee
+ expression) are evaluated at comptime.
+
+ Code written within one or more test declarations can be used to ensure behavior meets expectations:
+
+ testing_introduction.zig
const std = @import("std");
+
+test"expect addOne adds one to 41" {
+
+ // The Standard Library contains useful functions to help create tests.
+ // `expect` is a function that verifies its argument is true.
+ // It will return an error if its argument is false to indicate a failure.
+ // `try` is used to return an error to the test runner to notify it that the test failed.
+ try std.testing.expect(addOne(41) == 42);
+}
+
+test addOne {
+ // A test name can also be written using an identifier.
+ // This is a doctest, and serves as documentation for `addOne`.
+ try std.testing.expect(addOne(41) == 42);
+}
+
+/// The function `addOne` adds one to the number given as its argument.
+fnaddOne(number: i32) i32 {
+ return number + 1;
+}
Shell
$ zig test testing_introduction.zig
+1/2 testing_introduction.test.expect addOne adds one to 41...OK
+2/2 testing_introduction.decltest.addOne...OK
+All 2 tests passed.
+
+
+
+ The testing_introduction.zig code sample tests the function
+ addOne to ensure that it returns 42 given the input
+ 41. From this test's perspective, the addOne function is
+ said to be code under test.
+
+
+ zig test is a tool that creates and runs a test build. By default, it builds and runs an
+ executable program using the default test runner provided by the Zig Standard Library
+ as its main entry point. During the build, test declarations found while
+ resolving the given Zig source file are included for the default test runner
+ to run and report on.
+
+
+
+ The shell output shown above displays two lines after the zig test command. These lines are
+ printed to standard error by the default test runner:
+
+
+
1/2 testing_introduction.test.expect addOne adds one to 41...
+
Lines like this indicate which test, out of the total number of tests, is being run.
+ In this case, 1/2 indicates that the first test, out of a total of two tests,
+ is being run. Note that, when the test runner program's standard error is output
+ to the terminal, these lines are cleared when a test succeeds.
+
+
2/2 testing_introduction.decltest.addOne...
+
When the test name is an identifier, the default test runner uses the text
+ decltest instead of test.
+
+
All 2 tests passed.
+
This line indicates the total number of tests that have passed.
+ Test declarations contain the keywordtest, followed by an
+ optional name written as a string literal or an
+ identifier, followed by a block containing any valid Zig code that
+ is allowed in a function.
+
+
Non-named test blocks always run during test builds and are exempt from
+ Skip Tests.
+
+ Test declarations are similar to Functions: they have a return type and a block of code. The implicit
+ return type of test is the Error Union Typeanyerror!void,
+ and it cannot be changed. When a Zig source file is not built using the zig test tool, the test
+ declarations are omitted from the build.
+
+
+ Test declarations can be written in the same file, where code under test is written, or in a separate Zig source file.
+ Since test declarations are top-level declarations, they are order-independent and can
+ be written before or after the code under test.
+
+ Test declarations named using an identifier are doctests. The identifier must refer to another declaration in
+ scope. A doctest, like a doc comment, serves as documentation for the associated declaration, and
+ will appear in the generated documentation for the declaration.
+
+
+ An effective doctest should be self-contained and focused on the declaration being tested, answering questions a new
+ user might have about its interface or intended usage, while avoiding unnecessary or confusing details. A doctest is not
+ a substitute for a doc comment, but rather a supplement and companion providing a testable, code-driven example, verified
+ by zig test.
+
+ The default test runner checks for an error returned from a test.
+ When a test returns an error, the test is considered a failure and its error return trace
+ is output to standard error. The total number of failures will be reported after all tests have run.
+
+ testing_failure.zig
const std = @import("std");
+
+test"expect this to fail" {
+ try std.testing.expect(false);
+}
+
+test"expect this to succeed" {
+ try std.testing.expect(true);
+}
Shell
$ zig test testing_failure.zig
+1/2 testing_failure.test.expect this to fail...FAIL (TestUnexpectedResult)
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/testing.zig:580:14: 0x104865f in expect (test)
+ if (!ok) return error.TestUnexpectedResult;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/testing_failure.zig:4:5: 0x10486f5 in test.expect this to fail (test)
+ try std.testing.expect(false);
+ ^
+2/2 testing_failure.test.expect this to succeed...OK
+1 passed; 0 skipped; 1 failed.
+error: the following test command failed with exit code 1:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/4a2fad21710c87bc1399179ccb2726ce/test --seed=0xe0a3c2ed
+
+ One way to skip tests is to filter them out by using the zig test command line parameter
+ --test-filter [text]. This makes the test build only include tests whose name contains the
+ supplied filter text. Note that non-named tests are run even when using the --test-filter [text]
+ command line parameter.
+
+
+ To programmatically skip a test, make a test return the error
+ error.SkipZigTest and the default test runner will consider the test as being skipped.
+ The total number of skipped tests will be reported after all tests have run.
+
+ testing_skip.zig
test"this will be skipped" {
+ returnerror.SkipZigTest;
+}
Shell
$ zig test testing_skip.zig
+1/1 testing_skip.test.this will be skipped...SKIP
+0 passed; 1 skipped; 0 failed.
+
+ When code allocates Memory using the Zig Standard Library's testing allocator,
+ std.testing.allocator, the default test runner will report any leaks that are
+ found from using the testing allocator:
+
+ The Zig Standard Library's testing namespace contains useful functions to help
+ you create tests. In addition to the expect function, this document uses a couple of more functions
+ as exemplified here:
+
+ testing_namespace.zig
const std = @import("std");
+
+test"expectEqual demo" {
+ const expected: i32 = 42;
+ const actual = 42;
+
+ // The first argument to `expectEqual` is the known, expected, result.
+ // The second argument is the result of some expression.
+ // The actual's type is casted to the type of expected.
+ try std.testing.expectEqual(expected, actual);
+}
+
+test"expectError demo" {
+ const expected_error = error.DemoError;
+ const actual_error_union: anyerror!void = error.DemoError;
+
+ // `expectError` will fail when the actual error is different than
+ // the expected error.
+ try std.testing.expectError(expected_error, actual_error_union);
+}
The Zig Standard Library also contains functions to compare Slices, strings, and more. See the rest of the
+ std.testing namespace in the Zig Standard Library for more available functions.
+ It is generally preferable to use const rather than
+ var when declaring a variable. This causes less work for both
+ humans and computers to do when reading code, and creates more optimization opportunities.
+
+
+ The extern keyword or @extern builtin function can be used to link against a variable that is exported
+ from another object. The export keyword or @export builtin function
+ can be used to make a variable available to other objects at link time. In both cases,
+ the type of the variable must be C ABI compatible.
+
+ Variable identifiers are never allowed to shadow identifiers from an outer scope.
+
+
+ Identifiers must start with an alphabetic character or underscore and may be followed
+ by any number of alphanumeric characters or underscores.
+ They must not overlap with any keywords. See Keyword Reference.
+
+
+ If a name that does not fit these requirements is needed, such as for linking with external libraries, the @"" syntax may be used.
+
+ identifiers.zig
const @"identifier with spaces in it" = 0xff;
+const @"1SmallStep4Man" = 112358;
+
+const c = @import("std").c;
+pubextern"c"fn@"error"() void;
+pubextern"c"fn@"fstat$INODE64"(fd: c.fd_t, buf: *c.Stat) c_int;
+
+const Color = enum {
+ red,
+ @"really red",
+};
+const color: Color = .@"really red";
+ Container level variables have static lifetime and are order-independent and lazily analyzed.
+ The initialization value of container level variables is implicitly
+ comptime. If a container level variable is const then its value is
+ comptime-known, otherwise it is runtime-known.
+
A variable may be specified to be a thread-local variable using the
+ threadlocal keyword,
+ which makes each thread work with a separate instance of the variable:
+ When a local variable is const, it means that after initialization, the variable's
+ value will not change. If the initialization value of a const variable is
+ comptime-known, then the variable is also comptime-known.
+
+
+ A local variable may be qualified with the comptime keyword. This causes
+ the variable's value to be comptime-known, and all loads and stores of the
+ variable to happen during semantic analysis of the program, rather than at runtime.
+ All variables declared in a comptime expression are implicitly
+ comptime variables.
+
+ test_comptime_variables.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"comptime vars" {
+ var x: i32 = 1;
+ comptimevar y: i32 = 1;
+
+ x += 1;
+ y += 1;
+
+ try expect(x == 2);
+ try expect(y == 2);
+
+ if (y != 2) {
+ // This compile error never triggers because y is a comptime variable,
+ // and so `y != 2` is a comptime value, and this if is statically evaluated.
+ @compileError("wrong y value");
+ }
+}
+ Integer literals have no size limitation, and if any Illegal Behavior occurs,
+ the compiler catches it.
+
+
+ However, once an integer value is no longer known at compile-time, it must have a
+ known size, and is vulnerable to safety-checked Illegal Behavior.
+
+ runtime_vs_comptime.zig
fndivide(a: i32, b: i32) i32 {
+ return a / b;
+}
+
+
+ In this function, values a and b are known only at runtime,
+ and thus this division operation is vulnerable to both Integer Overflow and
+ Division by Zero.
+
+
+ Operators such as + and - cause Illegal Behavior on
+ integer overflow. Alternative operators are provided for wrapping and saturating arithmetic on all targets.
+ +% and -% perform wrapping arithmetic
+ while +| and -| perform saturating arithmetic.
+
+
+ Zig supports arbitrary bit-width integers, referenced by using
+ an identifier of i or u followed by digits. For example, the identifier
+ i7 refers to a signed 7-bit integer. The maximum allowed bit-width of an
+ integer type is 65535. For signed integer types, Zig uses a
+ two's complement representation.
+
+ Float literals have type comptime_float which is guaranteed to have
+ the same precision and operations of the largest other floating point type, which is
+ f128.
+
+
+ Float literals coerce to any floating point type,
+ and to any integer type when there is no fractional component.
+
+ float_literals.zig
const floating_point = 123.0E+77;
+const another_float = 123.0;
+const yet_another = 123.0e+77;
+
+const hex_floating_point = 0x103.70p-5;
+const another_hex_float = 0x103.70;
+const yet_another_hex_float = 0x103.70P-5;
+
+// underscores may be placed between two digits as a visual separator
+const lightspeed = 299_792_458.000_000;
+const nanosecond = 0.000_000_001;
+const more_hex = 0x1234_5678.9ABC_CDEFp-10;
+
+
+ There is no syntax for NaN, infinity, or negative infinity. For these special values,
+ one must use the standard library:
+
For this test we have to separate code into two object files -
+ otherwise the optimizer figures out all the values at compile-time,
+ which operates in strict mode.
If a is an error,
+ returns b ("default value"),
+ otherwise returns the unwrapped value of a.
+ Note that b may be a value of type noreturn.
+err is the error and is in scope of the expression b.
+
const expect = @import("std").testing.expect;
+const assert = @import("std").debug.assert;
+const mem = @import("std").mem;
+
+// array literal
+const message = [_]u8{ 'h', 'e', 'l', 'l', 'o' };
+
+// alternative initialization using result location
+const alt_message: [5]u8 = .{ 'h', 'e', 'l', 'l', 'o' };
+
+comptime {
+ assert(mem.eql(u8, &message, &alt_message));
+}
+
+// get the size of an array
+comptime {
+ assert(message.len == 5);
+}
+
+// A string literal is a single-item pointer to an array.
+const same_message = "hello";
+
+comptime {
+ assert(mem.eql(u8, &message, same_message));
+}
+
+test"iterate over an array" {
+ var sum: usize = 0;
+ for (message) |byte| {
+ sum += byte;
+ }
+ try expect(sum == 'h' + 'e' + 'l' * 2 + 'o');
+}
+
+// modifiable array
+var some_integers: [100]i32 = undefined;
+
+test"modify an array" {
+ for (&some_integers, 0..) |*item, i| {
+ item.* = @intCast(i);
+ }
+ try expect(some_integers[10] == 10);
+ try expect(some_integers[99] == 99);
+}
+
+// array concatenation works if the values are known
+// at compile time
+const part_one = [_]i32{ 1, 2, 3, 4 };
+const part_two = [_]i32{ 5, 6, 7, 8 };
+const all_of_it = part_one ++ part_two;
+comptime {
+ assert(mem.eql(i32, &all_of_it, &[_]i32{ 1, 2, 3, 4, 5, 6, 7, 8 }));
+}
+
+// remember that string literals are arrays
+const hello = "hello";
+const world = "world";
+const hello_world = hello ++ " " ++ world;
+comptime {
+ assert(mem.eql(u8, hello_world, "hello world"));
+}
+
+// ** does repeating patterns
+const pattern = "ab" ** 3;
+comptime {
+ assert(mem.eql(u8, pattern, "ababab"));
+}
+
+// initialize an array to zero
+const all_zero = [_]u16{0} ** 10;
+
+comptime {
+ assert(all_zero.len == 10);
+ assert(all_zero[5] == 0);
+}
+
+// use compile-time code to initialize an array
+var fancy_array = init: {
+ var initial_value: [10]Point = undefined;
+ for (&initial_value, 0..) |*pt, i| {
+ pt.* = Point{
+ .x = @intCast(i),
+ .y = @intCast(i * 2),
+ };
+ }
+ break :init initial_value;
+};
+const Point = struct {
+ x: i32,
+ y: i32,
+};
+
+test"compile-time array initialization" {
+ try expect(fancy_array[4].x == 4);
+ try expect(fancy_array[4].y == 8);
+}
+
+// call a function to initialize an array
+var more_points = [_]Point{makePoint(3)} ** 10;
+fnmakePoint(x: i32) Point {
+ return Point{
+ .x = x,
+ .y = x * 2,
+ };
+}
+test"array initialization with function calls" {
+ try expect(more_points[4].x == 3);
+ try expect(more_points[4].y == 6);
+ try expect(more_points.len == 10);
+}
Shell
$ zig test test_arrays.zig
+1/4 test_arrays.test.iterate over an array...OK
+2/4 test_arrays.test.modify an array...OK
+3/4 test_arrays.test.compile-time array initialization...OK
+4/4 test_arrays.test.array initialization with function calls...OK
+All 4 tests passed.
+
+ A vector is a group of booleans, Integers, Floats, or
+ Pointers which are operated on in parallel, using SIMD instructions if possible.
+ Vector types are created with the builtin function @Vector.
+
+
+ Vectors support the same builtin operators as their underlying base types.
+ These operations are performed element-wise, and return a vector of the same length
+ as the input vectors. This includes:
+
+ It is prohibited to use a math operator on a mixture of scalars (individual numbers)
+ and vectors. Zig provides the @splat builtin to easily convert from scalars
+ to vectors, and it supports @reduce and array indexing syntax to convert
+ from vectors to scalars. Vectors also support assignment to and from fixed-length
+ arrays with comptime-known length.
+
+
+ For rearranging elements within and between vectors, Zig provides the @shuffle and @select functions.
+
+
+ Operations on vectors shorter than the target machine's native SIMD size will typically compile to single SIMD
+ instructions, while vectors longer than the target machine's native SIMD size will compile to multiple SIMD
+ instructions. If a given operation doesn't have SIMD support on the target architecture, the compiler will default
+ to operating on each vector element one at a time. Zig supports any comptime-known vector length up to 2^32-1,
+ although small powers of two (2-64) are most typical. Note that excessively long vector lengths (e.g. 2^20) may
+ result in compiler crashes on current versions of Zig.
+
+ test_vector.zig
const std = @import("std");
+const expectEqual = std.testing.expectEqual;
+
+test"Basic vector usage" {
+ // Vectors have a compile-time known length and base type.
+ const a = @Vector(4, i32){ 1, 2, 3, 4 };
+ const b = @Vector(4, i32){ 5, 6, 7, 8 };
+
+ // Math operations take place element-wise.
+ const c = a + b;
+
+ // Individual vector elements can be accessed using array indexing syntax.
+ try expectEqual(6, c[0]);
+ try expectEqual(8, c[1]);
+ try expectEqual(10, c[2]);
+ try expectEqual(12, c[3]);
+}
+
+test"Conversion between vectors, arrays, and slices" {
+ // Vectors and fixed-length arrays can be automatically assigned back and forth
+ const arr1: [4]f32 = [_]f32{ 1.1, 3.2, 4.5, 5.6 };
+ const vec: @Vector(4, f32) = arr1;
+ const arr2: [4]f32 = vec;
+ try expectEqual(arr1, arr2);
+
+ // You can also assign from a slice with comptime-known length to a vector using .*
+ const vec2: @Vector(2, f32) = arr1[1..3].*;
+
+ const slice: []constf32 = &arr1;
+ var offset: u32 = 1; // var to make it runtime-known
+ _ = &offset; // suppress 'var is never mutated' error
+ // To extract a comptime-known length from a runtime-known offset,
+ // first extract a new slice from the starting offset, then an array of
+ // comptime-known length
+ const vec3: @Vector(2, f32) = slice[offset..][0..2].*;
+ try expectEqual(slice[offset], vec2[0]);
+ try expectEqual(slice[offset + 1], vec2[1]);
+ try expectEqual(vec2, vec3);
+}
Shell
$ zig test test_vector.zig
+1/2 test_vector.test.Basic vector usage...OK
+2/2 test_vector.test.Conversion between vectors, arrays, and slices...OK
+All 2 tests passed.
+
+
+
+ TODO talk about C ABI interop
+ TODO consider suggesting std.MultiArrayList
+
[]T - is a slice (a fat pointer, which contains a pointer of type [*]T and a length).
+
+
Supports index syntax: slice[i]
+
Supports slice syntax: slice[start..end]
+
Supports len property: slice.len
+
+
+
+
Use &x to obtain a single-item pointer:
+ test_single_item_pointer.zig
const expect = @import("std").testing.expect;
+
+test"address of syntax" {
+ // Get the address of a variable:
+ const x: i32 = 1234;
+ const x_ptr = &x;
+
+ // Dereference a pointer:
+ try expect(x_ptr.* == 1234);
+
+ // When you get the address of a const variable, you get a const single-item pointer.
+ try expect(@TypeOf(x_ptr) == *consti32);
+
+ // If you want to mutate the value, you'd need an address of a mutable variable:
+ var y: i32 = 5678;
+ const y_ptr = &y;
+ try expect(@TypeOf(y_ptr) == *i32);
+ y_ptr.* += 1;
+ try expect(y_ptr.* == 5679);
+}
+
+test"pointer array access" {
+ // Taking an address of an individual element gives a
+ // single-item pointer. This kind of pointer
+ // does not support pointer arithmetic.
+ var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
+ const ptr = &array[2];
+ try expect(@TypeOf(ptr) == *u8);
+
+ try expect(array[2] == 3);
+ ptr.* += 1;
+ try expect(array[2] == 4);
+}
+
+test"slice syntax" {
+ // Get a pointer to a variable:
+ var x: i32 = 1234;
+ const x_ptr = &x;
+
+ // Convert to array pointer using slice syntax:
+ const x_array_ptr = x_ptr[0..1];
+ try expect(@TypeOf(x_array_ptr) == *[1]i32);
+
+ // Coerce to many-item pointer:
+ const x_many_ptr: [*]i32 = x_array_ptr;
+ try expect(x_many_ptr[0] == 1234);
+}
Shell
$ zig test test_single_item_pointer.zig
+1/3 test_single_item_pointer.test.address of syntax...OK
+2/3 test_single_item_pointer.test.pointer array access...OK
+3/3 test_single_item_pointer.test.slice syntax...OK
+All 3 tests passed.
+
+
+
+ Zig supports pointer arithmetic. It's better to assign the pointer to [*]T and increment that variable. For example, directly incrementing the pointer from a slice will corrupt it.
+
+ test_pointer_arithmetic.zig
const expect = @import("std").testing.expect;
+
+test"pointer arithmetic with many-item pointer" {
+ const array = [_]i32{ 1, 2, 3, 4 };
+ var ptr: [*]consti32 = &array;
+
+ try expect(ptr[0] == 1);
+ ptr += 1;
+ try expect(ptr[0] == 2);
+
+ // slicing a many-item pointer without an end is equivalent to
+ // pointer arithmetic: `ptr[start..] == ptr + start`
+ try expect(ptr[1..] == ptr + 1);
+
+ // subtraction between any two pointers except slices based on element size is supported
+ try expect(&ptr[1] - &ptr[0] == 1);
+}
+
+test"pointer arithmetic with slices" {
+ var array = [_]i32{ 1, 2, 3, 4 };
+ var length: usize = 0; // var to make it runtime-known
+ _ = &length; // suppress 'var is never mutated' error
+ var slice = array[length..array.len];
+
+ try expect(slice[0] == 1);
+ try expect(slice.len == 4);
+
+ slice.ptr += 1;
+ // now the slice is in an bad state since len has not been updated
+
+ try expect(slice[0] == 2);
+ try expect(slice.len == 4);
+}
Shell
$ zig test test_pointer_arithmetic.zig
+1/2 test_pointer_arithmetic.test.pointer arithmetic with many-item pointer...OK
+2/2 test_pointer_arithmetic.test.pointer arithmetic with slices...OK
+All 2 tests passed.
+
+
+
+ In Zig, we generally prefer Slices rather than Sentinel-Terminated Pointers.
+ You can turn an array or pointer into a slice using slice syntax.
+
+
+ Slices have bounds checking and are therefore protected
+ against this kind of Illegal Behavior. This is one reason
+ we prefer slices to pointers.
+
+ test_slice_bounds.zig
const expect = @import("std").testing.expect;
+
+test"pointer slicing" {
+ var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
+ var start: usize = 2; // var to make it runtime-known
+ _ = &start; // suppress 'var is never mutated' error
+ const slice = array[start..4];
+ try expect(slice.len == 2);
+
+ try expect(array[3] == 4);
+ slice[1] += 1;
+ try expect(array[3] == 5);
+}
$ zig test test_integer_pointer_conversion.zig
+1/1 test_integer_pointer_conversion.test.@intFromPtr and @ptrFromInt...OK
+All 1 tests passed.
+
+
+
Zig is able to preserve memory addresses in comptime code, as long as
+ the pointer is never dereferenced:
+ test_comptime_pointer_conversion.zig
const expect = @import("std").testing.expect;
+
+test"comptime @ptrFromInt" {
+ comptime {
+ // Zig is able to do this at compile-time, as long as
+ // ptr is never dereferenced.
+ const ptr: *i32 = @ptrFromInt(0xdeadbee0);
+ const addr = @intFromPtr(ptr);
+ try expect(@TypeOf(addr) == usize);
+ try expect(addr == 0xdeadbee0);
+ }
+}
+ @ptrCast converts a pointer's element type to another. This
+ creates a new pointer that can cause undetectable Illegal Behavior
+ depending on the loads and stores that pass through it. Generally, other
+ kinds of type conversions are preferable to
+ @ptrCast if possible.
+
+ test_pointer_casting.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"pointer casting" {
+ const bytes align(@alignOf(u32)) = [_]u8{ 0x12, 0x12, 0x12, 0x12 };
+ const u32_ptr: *constu32 = @ptrCast(&bytes);
+ try expect(u32_ptr.* == 0x12121212);
+
+ // Even this example is contrived - there are better ways to do the above than
+ // pointer casting. For example, using a slice narrowing cast:
+ const u32_value = std.mem.bytesAsSlice(u32, bytes[0..])[0];
+ try expect(u32_value == 0x12121212);
+
+ // And even another way, the most straightforward way to do it:
+ try expect(@as(u32, @bitCast(bytes)) == 0x12121212);
+}
+
+test"pointer child type" {
+ // pointer types have a `child` field which tells you the type they point to.
+ try expect(@typeInfo(*u32).pointer.child == u32);
+}
Loads and stores are assumed to not have side effects. If a given load or store
+ should have side effects, such as Memory Mapped Input/Output (MMIO), use volatile.
+ In the following code, loads and stores with mmio_ptr are guaranteed to all happen
+ and in the same order as in source code:
+ Note that volatile is unrelated to concurrency and Atomics.
+ If you see code that is using volatile for something other than Memory Mapped
+ Input/Output, it is probably a bug.
+
+ Each type has an alignment - a number of bytes such that,
+ when a value of the type is loaded from or stored to memory,
+ the memory address must be evenly divisible by this number. You can use
+ @alignOf to find out this value for any type.
+
+
+ Alignment depends on the CPU architecture, but is always a power of two, and
+ less than 1 << 29.
+
+
+ In Zig, a pointer type has an alignment value. If the value is equal to the
+ alignment of the underlying type, it can be omitted from the type:
+
In the same way that a *i32 can be coerced to a
+ *consti32, a pointer with a larger alignment can be implicitly
+ cast to a pointer with a smaller alignment, but not vice versa.
+
+
+ You can specify alignment on variables and functions. If you do this, then
+ pointers to them get the specified alignment:
+
+ If you have a pointer or a slice that has a small alignment, but you know that it actually
+ has a bigger alignment, use @alignCast to change the
+ pointer into a more aligned pointer. This is a no-op at runtime, but inserts a
+ safety check:
+
+ This pointer attribute allows a pointer to have address zero. This is only ever needed on the
+ freestanding OS target, where the address zero is mappable. If you want to represent null pointers, use
+ Optional Pointers instead. Optional Pointers with allowzero
+ are not the same size as pointers. In this code example, if the pointer
+ did not have the allowzero attribute, this would be a
+ Pointer Cast Invalid Null panic:
+
+ test_allowzero.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"allowzero" {
+ var zero: usize = 0; // var to make to runtime-known
+ _ = &zero; // suppress 'var is never mutated' error
+ const ptr: *allowzeroi32 = @ptrFromInt(zero);
+ try expect(@intFromPtr(ptr) == 0);
+}
+ The syntax [*:x]T describes a pointer that
+ has a length determined by a sentinel value. This provides protection
+ against buffer overflow and overreads.
+
+ sentinel-terminated_pointer.zig
const std = @import("std");
+
+// This is also available as `std.c.printf`.
+pubextern"c"fnprintf(format: [*:0]constu8, ...) c_int;
+
+pubfnmain() anyerror!void {
+ _ = printf("Hello, world!\n"); // OK
+
+ const msg = "Hello, world!\n";
+ const non_null_terminated_msg: [msg.len]u8 = msg.*;
+ _ = printf(&non_null_terminated_msg);
+}
Shell
$ zig build-exe sentinel-terminated_pointer.zig -lc
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:11:16: error: expected type '[*:0]const u8', found '*const [14]u8'
+ _ = printf(&non_null_terminated_msg);
+ ^~~~~~~~~~~~~~~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:11:16: note: destination pointer requires '0' sentinel
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:4:34: note: parameter type declared here
+pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;
+ ^~~~~~~~~~~~~
+referenced by:
+ main: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:660:37
+ comptime: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:58:30
+ 2 reference(s) hidden; use '-freference-trace=4' to see all references
+
+
+ A slice is a pointer and a length. The difference between an array and
+ a slice is that the array's length is part of the type and known at
+ compile-time, whereas the slice's length is known at runtime.
+ Both can be accessed with the len field.
+
+ test_basic_slices.zig
const expect = @import("std").testing.expect;
+const expectEqualSlices = @import("std").testing.expectEqualSlices;
+
+test"basic slices" {
+ var array = [_]i32{ 1, 2, 3, 4 };
+ var known_at_runtime_zero: usize = 0;
+ _ = &known_at_runtime_zero;
+ const slice = array[known_at_runtime_zero..array.len];
+
+ // alternative initialization using result location
+ const alt_slice: []consti32 = &.{ 1, 2, 3, 4 };
+
+ try expectEqualSlices(i32, slice, alt_slice);
+
+ try expect(@TypeOf(slice) == []i32);
+ try expect(&slice[0] == &array[0]);
+ try expect(slice.len == array.len);
+
+ // If you slice with comptime-known start and end positions, the result is
+ // a pointer to an array, rather than a slice.
+ const array_ptr = array[0..array.len];
+ try expect(@TypeOf(array_ptr) == *[array.len]i32);
+
+ // You can perform a slice-by-length by slicing twice. This allows the compiler
+ // to perform some optimisations like recognising a comptime-known length when
+ // the start position is only known at runtime.
+ var runtime_start: usize = 1;
+ _ = &runtime_start;
+ const length = 2;
+ const array_ptr_len = array[runtime_start..][0..length];
+ try expect(@TypeOf(array_ptr_len) == *[length]i32);
+
+ // Using the address-of operator on a slice gives a single-item pointer.
+ try expect(@TypeOf(&slice[0]) == *i32);
+ // Using the `ptr` field gives a many-item pointer.
+ try expect(@TypeOf(slice.ptr) == [*]i32);
+ try expect(@intFromPtr(slice.ptr) == @intFromPtr(&slice[0]));
+
+ // Slices have array bounds checking. If you try to access something out
+ // of bounds, you'll get a safety check failure:
+ slice[10] += 1;
+
+ // Note that `slice.ptr` does not invoke safety checking, while `&slice[0]`
+ // asserts that the slice has len > 0.
+
+ // Empty slices can be created like this:
+ const empty1 = &[0]u8{};
+ // If the type is known you can use this short hand:
+ const empty2: []u8 = &.{};
+ try expect(empty1.len == 0);
+ try expect(empty2.len == 0);
+
+ // A zero-length initialization can always be used to create an empty slice, even if the slice is mutable.
+ // This is because the pointed-to data is zero bits long, so its immutability is irrelevant.
+}
Shell
$ zig test test_basic_slices.zig
+1/1 test_basic_slices.test.basic slices...thread 1082565 panic: index out of bounds: index 10, len 4
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_basic_slices.zig:41:10: 0x104b241 in test.basic slices (test)
+ slice[10] += 1;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10f21b9 in mainTerminal (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10ea55d in main (test)
+ return mainTerminal();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e99d2 in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e95ad in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/f9263bb559fc5a754baaa433017d4d71/test --seed=0x314392aa
+
+
+
This is one reason we prefer slices to pointers.
+ test_slices.zig
const std = @import("std");
+const expect = std.testing.expect;
+const mem = std.mem;
+const fmt = std.fmt;
+
+test"using slices for strings" {
+ // Zig has no concept of strings. String literals are const pointers
+ // to null-terminated arrays of u8, and by convention parameters
+ // that are "strings" are expected to be UTF-8 encoded slices of u8.
+ // Here we coerce *const [5:0]u8 and *const [6:0]u8 to []const u8
+ const hello: []constu8 = "hello";
+ const world: []constu8 = "世界";
+
+ var all_together: [100]u8 = undefined;
+ // You can use slice syntax with at least one runtime-known index on an
+ // array to convert an array into a slice.
+ var start: usize = 0;
+ _ = &start;
+ const all_together_slice = all_together[start..];
+ // String concatenation example.
+ const hello_world = try fmt.bufPrint(all_together_slice, "{s} {s}", .{ hello, world });
+
+ // Generally, you can use UTF-8 and not worry about whether something is a
+ // string. If you don't need to deal with individual characters, no need
+ // to decode.
+ try expect(mem.eql(u8, hello_world, "hello 世界"));
+}
+
+test"slice pointer" {
+ var array: [10]u8 = undefined;
+ const ptr = &array;
+ try expect(@TypeOf(ptr) == *[10]u8);
+
+ // A pointer to an array can be sliced just like an array:
+ var start: usize = 0;
+ var end: usize = 5;
+ _ = .{ &start, &end };
+ const slice = ptr[start..end];
+ // The slice is mutable because we sliced a mutable pointer.
+ try expect(@TypeOf(slice) == []u8);
+ slice[2] = 3;
+ try expect(array[2] == 3);
+
+ // Again, slicing with comptime-known indexes will produce another pointer
+ // to an array:
+ const ptr2 = slice[2..3];
+ try expect(ptr2.len == 1);
+ try expect(ptr2[0] == 3);
+ try expect(@TypeOf(ptr2) == *[1]u8);
+}
Shell
$ zig test test_slices.zig
+1/2 test_slices.test.using slices for strings...OK
+2/2 test_slices.test.slice pointer...OK
+All 2 tests passed.
+
+ The syntax [:x]T is a slice which has a runtime-known length
+ and also guarantees a sentinel value at the element indexed by the length. The type does not
+ guarantee that there are no sentinel elements before that. Sentinel-terminated slices allow element
+ access to the len index.
+
+ Sentinel-terminated slices can also be created using a variation of the slice syntax
+ data[start..end :x], where data is a many-item pointer,
+ array or slice and x is the sentinel value.
+
+ Sentinel-terminated slicing asserts that the element in the sentinel position of the backing data is
+ actually the sentinel value. If this is not the case, safety-checked Illegal Behavior results.
+
+ test_sentinel_mismatch.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"sentinel mismatch" {
+ var array = [_]u8{ 3, 2, 1, 0 };
+
+ // Creating a sentinel-terminated slice from the array with a length of 2
+ // will result in the value `1` occupying the sentinel element position.
+ // This does not match the indicated sentinel value of `0` and will lead
+ // to a runtime panic.
+ var runtime_length: usize = 2;
+ _ = &runtime_length;
+ const slice = array[0..runtime_length :0];
+
+ _ = slice;
+}
Shell
$ zig test test_sentinel_mismatch.zig
+1/1 test_sentinel_mismatch.test.sentinel mismatch...thread 1083169 panic: sentinel mismatch: expected 0, found 1
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_sentinel_mismatch.zig:13:24: 0x10487a1 in test.sentinel mismatch (test)
+ const slice = array[0..runtime_length :0];
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10eea69 in mainTerminal (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10e6e0d in main (test)
+ return mainTerminal();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e6282 in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e5e5d in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/5999cad80b529a1b559a5322826e4b05/test --seed=0x30c9f67
+
+ 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:
+
$ zig build-exe bad_default_value.zig
+$ ./bad_default_value
+thread 1084966 panic: reached unreachable code
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:550:14: 0x1048b9d in assert (bad_default_value)
+ if (!ok) unreachable; // assertion failure
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/bad_default_value.zig:8:15: 0x10de0d9 in categorize (bad_default_value)
+ assert(t.maximum >= t.minimum);
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/bad_default_value.zig:19:42: 0x10de01a in main (bad_default_value)
+ const category = threshold.categorize(0.90);
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:660:37: 0x10ddf2a in posixCallMainAndExit (bad_default_value)
+ const result = root.main() catch |err| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10ddadd in _start (bad_default_value)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+(process terminated by signal)
+
+
+
+ Above you can see the danger of ignoring this principle. The default
+ field values caused the data invariant to be violated, causing illegal
+ behavior.
+
+
+ To fix this, remove the default values from all the struct fields, and provide
+ a named default value:
+
If a struct value requires a runtime-known value in order to be initialized
+ without violating data invariants, then use an initialization method that accepts
+ those runtime values, and populates the remaining fields.
+ Unlike normal structs, packed structs have guaranteed in-memory layout:
+
+
+
Fields remain in the order declared, least to most significant.
+
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.
+
An 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.
+
Packed structs support equality operators.
+
+
+ This means that a packedstruct can participate
+ in a @bitCast or a @ptrCast to reinterpret memory.
+ This even works at comptime:
+
$ zig test test_missized_packed_struct.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_missized_packed_struct.zig:2:29: error: backing integer type 'u32' has bit size 32 but the struct fields have a total bit size of 24
+ const S = packed struct(u32) { a: u16, b: u8 };
+ ^~~
+referenced by:
+ test.missized packed struct: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_missized_packed_struct.zig:2:22
+
+
+
+
+ Zig allows the address to be taken of a non-byte-aligned field:
+
$ zig test test_misaligned_pointer.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: error: expected type '*const u3', found '*align(1:3:1) u3'
+ try expect(bar(&bit_field.b) == 2);
+ ^~~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: note: pointer host size '1' cannot cast into pointer host size '0'
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: note: pointer bit offset '3' cannot cast into pointer bit offset '0'
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:20:11: note: parameter type declared here
+fn bar(x: *const u3) u3 {
+ ^~~~~~~~~
+
+
+
+
+ In this case, the function bar cannot be called because 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:
+
+ 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.
+
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 (filename.funcname__struct_ID).
+
If the struct is declared inside another struct, it gets named after both the parent
+ struct and the name inferred by the previous rules, separated by a dot.
+ 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:
+
+ Anonymous structs can be created without specifying field names, and are referred to as "tuples". An empty tuple looks like .{} and can be seen in one of the Hello World examples.
+
+
+ The fields are implicitly named using numbers starting from 0. Because their names are integers,
+ they cannot be accessed with . syntax without also wrapping them in
+ @"". Names inside @"" are always recognised as
+ identifiers.
+
+
+ Like arrays, tuples have a .len field, can be indexed (provided the index is comptime-known)
+ and work with the ++ and ** operators. They can also be iterated over with inline for.
+
const expect = @import("std").testing.expect;
+const mem = @import("std").mem;
+
+// Declare an enum.
+const Type = enum {
+ ok,
+ not_ok,
+};
+
+// Declare a specific enum field.
+const c = Type.ok;
+
+// If you want access to the ordinal value of an enum, you
+// can specify the tag type.
+const Value = enum(u2) {
+ zero,
+ one,
+ two,
+};
+// Now you can cast between u2 and Value.
+// The ordinal value starts from 0, counting up by 1 from the previous member.
+test"enum ordinal value" {
+ try expect(@intFromEnum(Value.zero) == 0);
+ try expect(@intFromEnum(Value.one) == 1);
+ try expect(@intFromEnum(Value.two) == 2);
+}
+
+// You can override the ordinal value for an enum.
+const Value2 = enum(u32) {
+ hundred = 100,
+ thousand = 1000,
+ million = 1000000,
+};
+test"set enum ordinal value" {
+ try expect(@intFromEnum(Value2.hundred) == 100);
+ try expect(@intFromEnum(Value2.thousand) == 1000);
+ try expect(@intFromEnum(Value2.million) == 1000000);
+}
+
+// You can also override only some values.
+const Value3 = enum(u4) {
+ a,
+ b = 8,
+ c,
+ d = 4,
+ e,
+};
+test"enum implicit ordinal values and overridden values" {
+ try expect(@intFromEnum(Value3.a) == 0);
+ try expect(@intFromEnum(Value3.b) == 8);
+ try expect(@intFromEnum(Value3.c) == 9);
+ try expect(@intFromEnum(Value3.d) == 4);
+ try expect(@intFromEnum(Value3.e) == 5);
+}
+
+// Enums can have methods, the same as structs and unions.
+// Enum methods are not special, they are only namespaced
+// functions that you can call with dot syntax.
+const Suit = enum {
+ clubs,
+ spades,
+ diamonds,
+ hearts,
+
+ pubfnisClubs(self: Suit) bool {
+ return self == Suit.clubs;
+ }
+};
+test"enum method" {
+ const p = Suit.spades;
+ try expect(!p.isClubs());
+}
+
+// An enum can be switched upon.
+const Foo = enum {
+ string,
+ number,
+ none,
+};
+test"enum switch" {
+ const p = Foo.number;
+ const what_is_it = switch (p) {
+ Foo.string => "this is a string",
+ Foo.number => "this is a number",
+ Foo.none => "this is a none",
+ };
+ try expect(mem.eql(u8, what_is_it, "this is a number"));
+}
+
+// @typeInfo can be used to access the integer tag type of an enum.
+const Small = enum {
+ one,
+ two,
+ three,
+ four,
+};
+test"std.meta.Tag" {
+ try expect(@typeInfo(Small).@"enum".tag_type == u2);
+}
+
+// @typeInfo tells us the field count and the fields names:
+test"@typeInfo" {
+ try expect(@typeInfo(Small).@"enum".fields.len == 4);
+ try expect(mem.eql(u8, @typeInfo(Small).@"enum".fields[1].name, "two"));
+}
+
+// @tagName gives a [:0]const u8 representation of an enum value:
+test"@tagName" {
+ try expect(mem.eql(u8, @tagName(Small.three), "three"));
+}
+ By default, enums are not guaranteed to be compatible with the C ABI:
+
+ enum_export_error.zig
const Foo = enum { a, b, c };
+exportfnentry(foo: Foo) void {
+ _ = foo;
+}
Shell
$ zig build-obj enum_export_error.zig -target x86_64-linux
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: error: parameter of type 'enum_export_error.Foo' not allowed in function with calling convention 'x86_64_sysv'
+export fn entry(foo: Foo) void {
+ ^~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: note: enum tag type 'u2' is not extern compatible
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: note: only integers with 0, 8, 16, 32, 64 and 128 bits are extern compatible
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:1:13: note: enum declared here
+const Foo = enum { a, b, c };
+ ^~~~~~~~~~~~~~~~
+referenced by:
+ root: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:3:22
+ comptime: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:27:9
+ 2 reference(s) hidden; use '-freference-trace=4' to see all references
+
+
+
+
+ For a C-ABI-compatible enum, provide an explicit tag type to
+ the enum:
+
+ enum_export.zig
const Foo = enum(c_int) { a, b, c };
+exportfnentry(foo: Foo) void {
+ _ = foo;
+}
+ A non-exhaustive enum can be created by adding a trailing _ field.
+ The enum must specify a tag type and cannot consume every enumeration value.
+
+
+ @enumFromInt on a non-exhaustive enum involves the safety semantics
+ of @intCast to the integer tag type, but beyond that always results in
+ a well-defined enum value.
+
+
+ A switch on a non-exhaustive enum can include a _ prong as an alternative to an else prong.
+ With a _ prong the compiler errors if all the known tag names are not handled by the switch.
+
+ A bare union defines a set of possible types that a value
+ can be as a list of fields. Only one field can be active at a time.
+ The in-memory representation of bare unions is not guaranteed.
+ Bare unions cannot be used to reinterpret memory. For that, use @ptrCast,
+ or use an extern union or a packed union which have
+ guaranteed in-memory layout.
+ Accessing the non-active field is
+ safety-checked Illegal Behavior:
+
$ zig test test_wrong_union_access.zig
+1/1 test_wrong_union_access.test.simple union...thread 1081145 panic: access of union field 'float' while field 'int' is active
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_wrong_union_access.zig:8:12: 0x10487af in test.simple union (test)
+ payload.float = 12.34;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10eeb99 in mainTerminal (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10e6f3d in main (test)
+ return mainTerminal();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e63b2 in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e5f8d in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/8f6c2970fa4ed12c76dd41bda2086b47/test --seed=0x32e9061f
+
+
+
You can activate another field by assigning the entire union:
Unions can be declared with an enum tag type.
+ This turns the union into a tagged union, which makes it eligible
+ to use with switch expressions.
+ Tagged unions coerce to their tag type: Type Coercion: Unions and Enums.
+
+ opaque {} declares a new type with an unknown (but non-zero) size and alignment.
+ It can contain declarations the same as structs, unions,
+ and enums.
+
+
+ This is typically used for type safety when interacting with C code that does not expose struct details.
+ Example:
+
+ Blocks are used to limit the scope of variable declarations:
+
+ test_blocks.zig
test"access variable after block scope" {
+ {
+ var x: i32 = 1;
+ _ = &x;
+ }
+ x += 1;
+}
Shell
$ zig test test_blocks.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_blocks.zig:6:5: error: use of undeclared identifier 'x'
+ x += 1;
+ ^
+
+
+
+
Blocks are expressions. When labeled, break can be used
+ to return a value from the block:
+
Identifiers are never allowed to "hide" other identifiers by using the same name:
+ test_shadowing.zig
const pi = 3.14;
+
+test"inside test block" {
+ // Let's even go inside another block
+ {
+ var pi: i32 = 1234;
+ }
+}
Shell
$ zig test test_shadowing.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_shadowing.zig:6:13: error: local variable shadows declaration of 'pi'
+ var pi: i32 = 1234;
+ ^~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_shadowing.zig:1:1: note: declared here
+const pi = 3.14;
+^~~~~~~~~~~~~~~
+
+
+
+
+ Because of this, when you read Zig code you can always rely on an identifier to consistently mean
+ the same thing within the scope it is defined. Note that you can, however, use the same name if
+ the scopes are separate:
+
const std = @import("std");
+const builtin = @import("builtin");
+const expect = std.testing.expect;
+
+test"switch simple" {
+ const a: u64 = 10;
+ const zz: u64 = 103;
+
+ // All branches of a switch expression must be able to be coerced to a
+ // common type.
+ //
+ // Branches cannot fallthrough. If fallthrough behavior is desired, combine
+ // the cases and use an if.
+ const b = switch (a) {
+ // Multiple cases can be combined via a ','
+ 1, 2, 3 => 0,
+
+ // Ranges can be specified using the ... syntax. These are inclusive
+ // of both ends.
+ 5...100 => 1,
+
+ // Branches can be arbitrarily complex.
+ 101 => blk: {
+ const c: u64 = 5;
+ break :blk c * 2 + 1;
+ },
+
+ // Switching on arbitrary expressions is allowed as long as the
+ // expression is known at compile-time.
+ zz => zz,
+ blk: {
+ const d: u32 = 5;
+ const e: u32 = 100;
+ break :blk d + e;
+ } => 107,
+
+ // The else branch catches everything not already captured.
+ // Else branches are mandatory unless the entire range of values
+ // is handled.
+ else => 9,
+ };
+
+ try expect(b == 1);
+}
+
+// Switch expressions can be used outside a function:
+const os_msg = switch (builtin.target.os.tag) {
+ .linux => "we found a linux user",
+ else => "not a linux user",
+};
+
+// Inside a function, switch statements implicitly are compile-time
+// evaluated if the target expression is compile-time known.
+test"switch inside function" {
+ switch (builtin.target.os.tag) {
+ .fuchsia => {
+ // On an OS other than fuchsia, block is not even analyzed,
+ // so this compile error is not triggered.
+ // On fuchsia this compile error would be triggered.
+ @compileError("fuchsia not supported");
+ },
+ else => {},
+ }
+}
+ switch can be used to capture the field values
+ of a Tagged union. Modifications to the field values can be
+ done by placing a * before the capture variable name,
+ turning it into a pointer.
+
+ test_switch_tagged_union.zig
const expect = @import("std").testing.expect;
+
+test"switch on tagged union" {
+ const Point = struct {
+ x: u8,
+ y: u8,
+ };
+ const Item = union(enum) {
+ a: u32,
+ c: Point,
+ d,
+ e: u32,
+ };
+
+ var a = Item{ .c = Point{ .x = 1, .y = 2 } };
+
+ // Switching on more complex enums is allowed.
+ const b = switch (a) {
+ // A capture group is allowed on a match, and will return the enum
+ // value matched. If the payload types of both cases are the same
+ // they can be put into the same switch prong.
+ Item.a, Item.e => |item| item,
+
+ // A reference to the matched value can be obtained using `*` syntax.
+ Item.c => |*item| blk: {
+ item.*.x += 1;
+ break :blk 6;
+ },
+
+ // No else is required if the types cases was exhaustively handled
+ Item.d => 8,
+ };
+
+ try expect(b == 6);
+ try expect(a.c.x == 2);
+}
Shell
$ zig test test_switch_tagged_union.zig
+1/1 test_switch_tagged_union.test.switch on tagged union...OK
+All 1 tests passed.
+
+ When a switch statement is labeled, it can be referenced from a
+ break or continue.
+ break will return a value from the switch.
+
+
+ A continue targeting a switch must have an
+ operand. When executed, it will jump to the matching prong, as if the
+ switch were executed again with the continue's operand replacing the initial switch value.
+
+
+ test_switch_continue.zig
const std = @import("std");
+
+test"switch continue" {
+ sw: switch (@as(i32, 5)) {
+ 5 => continue :sw 4,
+
+ // `continue` can occur multiple times within a single switch prong.
+ 2...4 => |v| {
+ if (v > 3) {
+ continue :sw 2;
+ } elseif (v == 3) {
+
+ // `break` can target labeled loops.
+ break :sw;
+ }
+
+ continue :sw 1;
+ },
+
+ 1 => return,
+
+ else => unreachable,
+ }
+}
+ This can improve clarity of (for example) state machines, where the syntax continue :sw .next_state is unambiguous, explicit, and immediately understandable.
+
+
+ However, the motivating example is a switch on each element of an array, where using a single switch can improve clarity and performance:
+
+ test_switch_dispatch_loop.zig
const std = @import("std");
+const expectEqual = std.testing.expectEqual;
+
+const Instruction = enum {
+ add,
+ mul,
+ end,
+};
+
+fnevaluate(initial_stack: []consti32, code: []const Instruction) !i32 {
+ var stack = try std.BoundedArray(i32, 8).fromSlice(initial_stack);
+ var ip: usize = 0;
+
+ return vm: switch (code[ip]) {
+ // Because all code after `continue` is unreachable, this branch does
+ // not provide a result.
+ .add => {
+ try stack.append(stack.pop().? + stack.pop().?);
+
+ ip += 1;
+ continue :vm code[ip];
+ },
+ .mul => {
+ try stack.append(stack.pop().? * stack.pop().?);
+
+ ip += 1;
+ continue :vm code[ip];
+ },
+ .end => stack.pop().?,
+ };
+}
+
+test"evaluate" {
+ const result = try evaluate(&.{ 7, 2, -3 }, &.{ .mul, .add, .end });
+ try expectEqual(1, result);
+}
+ If the operand to continue is
+ comptime-known, then it can be lowered to an unconditional branch
+ to the relevant case. Such a branch is perfectly predicted, and hence
+ typically very fast to execute.
+
+
+
+ If the operand is runtime-known, each continue can
+ embed a conditional branch inline (ideally through a jump table), which
+ allows a CPU to predict its target independently of any other prong. A
+ loop-based lowering would force every branch through the same dispatch
+ point, hindering branch prediction.
+
+ inlineelse prongs can be used as a type safe
+ alternative to inlinefor loops:
+
+ test_inline_else.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+const SliceTypeA = externstruct {
+ len: usize,
+ ptr: [*]u32,
+};
+const SliceTypeB = externstruct {
+ ptr: [*]SliceTypeA,
+ len: usize,
+};
+const AnySlice = union(enum) {
+ a: SliceTypeA,
+ b: SliceTypeB,
+ c: []constu8,
+ d: []AnySlice,
+};
+
+fnwithFor(any: AnySlice) usize {
+ const Tag = @typeInfo(AnySlice).@"union".tag_type.?;
+ inlinefor (@typeInfo(Tag).@"enum".fields) |field| {
+ // With `inline for` the function gets generated as
+ // a series of `if` statements relying on the optimizer
+ // to convert it to a switch.
+ if (field.value == @intFromEnum(any)) {
+ return@field(any, field.name).len;
+ }
+ }
+ // When using `inline for` the compiler doesn't know that every
+ // possible case has been handled requiring an explicit `unreachable`.
+ unreachable;
+}
+
+fnwithSwitch(any: AnySlice) usize {
+ returnswitch (any) {
+ // With `inline else` the function is explicitly generated
+ // as the desired switch and the compiler can check that
+ // every possible case is handled.
+ inlineelse => |slice| slice.len,
+ };
+}
+
+test"inline for and inline else similarity" {
+ const any = AnySlice{ .c = "hello" };
+ try expect(withFor(any) == 5);
+ try expect(withSwitch(any) == 5);
+}
Shell
$ zig test test_inline_else.zig
+1/1 test_inline_else.test.inline for and inline else similarity...OK
+All 1 tests passed.
+
+
+
+ When using an inline prong switching on an union an additional
+ capture can be used to obtain the union's enum tag value.
+
+ test_inline_switch_union_tag.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+const U = union(enum) {
+ a: u32,
+ b: f32,
+};
+
+fngetNum(u: U) u32 {
+ switch (u) {
+ // Here `num` is a runtime-known value that is either
+ // `u.a` or `u.b` and `tag` is `u`'s comptime-known tag value.
+ inlineelse => |num, tag| {
+ if (tag == .b) {
+ return@intFromFloat(num);
+ }
+ return num;
+ },
+ }
+}
+
+test"test" {
+ const u = U{ .b = 42 };
+ try expect(getNum(u) == 42);
+}
+ While loops are expressions. The result of the expression is the
+ result of the else clause of a while loop, which is executed when
+ the condition of the while loop is tested as false.
+
+
+ break, like return, accepts a value
+ parameter. This is the result of the while expression.
+ When you break from a while loop, the else branch is not
+ evaluated.
+
+ test_while_else.zig
const expect = @import("std").testing.expect;
+
+test"while else" {
+ try expect(rangeHasNumber(0, 10, 5));
+ try expect(!rangeHasNumber(0, 10, 15));
+}
+
+fnrangeHasNumber(begin: usize, end: usize, number: usize) bool {
+ var i = begin;
+ returnwhile (i < end) : (i += 1) {
+ if (i == number) {
+ breaktrue;
+ }
+ } elsefalse;
+}
+ Just like if expressions, while loops can take an error union as
+ the condition and capture the payload or the error code. When the
+ condition results in an error code the else branch is evaluated and
+ the loop is finished.
+
+
+ When the else |x| syntax is present on a while expression,
+ the while condition must have an Error Union Type.
+
+ While loops can be inlined. This causes the loop to be unrolled, which
+ allows the code to do some things which only work at compile time,
+ such as use types as first class values.
+
const expect = @import("std").testing.expect;
+
+test"for basics" {
+ const items = [_]i32{ 4, 5, 3, 4, 0 };
+ var sum: i32 = 0;
+
+ // For loops iterate over slices and arrays.
+ for (items) |value| {
+ // Break and continue are supported.
+ if (value == 0) {
+ continue;
+ }
+ sum += value;
+ }
+ try expect(sum == 16);
+
+ // To iterate over a portion of a slice, reslice.
+ for (items[0..1]) |value| {
+ sum += value;
+ }
+ try expect(sum == 20);
+
+ // To access the index of iteration, specify a second condition as well
+ // as a second capture value.
+ var sum2: i32 = 0;
+ for (items, 0..) |_, i| {
+ try expect(@TypeOf(i) == usize);
+ sum2 += @as(i32, @intCast(i));
+ }
+ try expect(sum2 == 10);
+
+ // To iterate over consecutive integers, use the range syntax.
+ // Unbounded range is always a compile error.
+ var sum3: usize = 0;
+ for (0..5) |i| {
+ sum3 += i;
+ }
+ try expect(sum3 == 10);
+}
+
+test"multi object for" {
+ const items = [_]usize{ 1, 2, 3 };
+ const items2 = [_]usize{ 4, 5, 6 };
+ var count: usize = 0;
+
+ // Iterate over multiple objects.
+ // All lengths must be equal at the start of the loop, otherwise detectable
+ // illegal behavior occurs.
+ for (items, items2) |i, j| {
+ count += i + j;
+ }
+
+ try expect(count == 21);
+}
+
+test"for reference" {
+ var items = [_]i32{ 3, 4, 2 };
+
+ // Iterate over the slice by reference by
+ // specifying that the capture value is a pointer.
+ for (&items) |*value| {
+ value.* += 1;
+ }
+
+ try expect(items[0] == 4);
+ try expect(items[1] == 5);
+ try expect(items[2] == 3);
+}
+
+test"for else" {
+ // For allows an else attached to it, the same as a while loop.
+ const items = [_]?i32{ 3, 4, null, 5 };
+
+ // For loops can also be used as expressions.
+ // Similar to while loops, when you break from a for loop, the else branch is not evaluated.
+ var sum: i32 = 0;
+ const result = for (items) |value| {
+ if (value != null) {
+ sum += value.?;
+ }
+ } else blk: {
+ try expect(sum == 12);
+ break :blk sum;
+ };
+ try expect(result == 12);
+}
+ For loops can be inlined. This causes the loop to be unrolled, which
+ allows the code to do some things which only work at compile time,
+ such as use types as first class values.
+ The capture value and iterator value of inlined for loops are
+ compile-time known.
+
// unreachable is used to assert that control flow will never reach a
+// particular location:
+test"basic math" {
+ const x = 1;
+ const y = 2;
+ if (x + y != 3) {
+ unreachable;
+ }
+}
In fact, this is how std.debug.assert is implemented:
+ test_assertion_failure.zig
// This is how std.debug.assert is implemented
+fnassert(ok: bool) void {
+ if (!ok) unreachable; // assertion failure
+}
+
+// This test will fail because we hit unreachable.
+test"this will fail" {
+ assert(false);
+}
Shell
$ zig test test_assertion_failure.zig
+1/1 test_assertion_failure.test.this will fail...thread 1079538 panic: reached unreachable code
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_assertion_failure.zig:3:14: 0x104866d in assert (test)
+ if (!ok) unreachable; // assertion failure
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_assertion_failure.zig:8:11: 0x104863a in test.this will fail (test)
+ assert(false);
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10ee969 in mainTerminal (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10e6d0d in main (test)
+ return mainTerminal();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e6182 in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e5d5d in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/d70b4afba1753abfc36c3e045b83ca5b/test --seed=0xb28f0ea5
+
const assert = @import("std").debug.assert;
+
+test"type of unreachable" {
+ comptime {
+ // The type of unreachable is noreturn.
+
+ // However this assertion will still fail to compile because
+ // unreachable expressions are compile errors.
+
+ assert(@TypeOf(unreachable) == noreturn);
+ }
+}
Shell
$ zig test test_comptime_unreachable.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unreachable.zig:10:16: error: unreachable code
+ assert(@TypeOf(unreachable) == noreturn);
+ ^~~~~~~~~~~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unreachable.zig:10:24: note: control flow is diverted here
+ assert(@TypeOf(unreachable) == noreturn);
+ ^~~~~~~~~~~
+
+
const std = @import("std");
+const builtin = @import("builtin");
+const native_arch = builtin.cpu.arch;
+const expect = std.testing.expect;
+
+// Functions are declared like this
+fnadd(a: i8, b: i8) i8 {
+ if (a == 0) {
+ return b;
+ }
+
+ return a + b;
+}
+
+// The export specifier makes a function externally visible in the generated
+// object file, and makes it use the C ABI.
+exportfnsub(a: i8, b: i8) i8 {
+ return a - b;
+}
+
+// The extern specifier is used to declare a function that will be resolved
+// at link time, when linking statically, or at runtime, when linking
+// dynamically. The quoted identifier after the extern keyword specifies
+// the library that has the function. (e.g. "c" -> libc.so)
+// The callconv specifier changes the calling convention of the function.
+const WINAPI: std.builtin.CallingConvention = if (native_arch == .x86) .Stdcall else .C;
+extern"kernel32"fnExitProcess(exit_code: u32) callconv(WINAPI) noreturn;
+extern"c"fnatan2(a: f64, b: f64) f64;
+
+// The @branchHint builtin can be used to tell the optimizer that a function is rarely called ("cold").
+fnabort() noreturn {
+ @branchHint(.cold);
+ while (true) {}
+}
+
+// The naked calling convention makes a function not have any function prologue or epilogue.
+// This can be useful when integrating with assembly.
+fn_start() callconv(.Naked) noreturn {
+ abort();
+}
+
+// The inline calling convention forces a function to be inlined at all call sites.
+// If the function cannot be inlined, it is a compile-time error.
+inlinefnshiftLeftOne(a: u32) u32 {
+ return a << 1;
+}
+
+// The pub specifier allows the function to be visible when importing.
+// Another file can use @import and call sub2
+pubfnsub2(a: i8, b: i8) i8 {
+ return a - b;
+}
+
+// Function pointers are prefixed with `*const `.
+const Call2Op = *constfn (a: i8, b: i8) i8;
+fndoOp(fnCall: Call2Op, op1: i8, op2: i8) i8 {
+ return fnCall(op1, op2);
+}
+
+test"function" {
+ try expect(doOp(add, 5, 6) == 11);
+ try expect(doOp(sub2, 5, 6) == -1);
+}
There is a difference between a function body and a function pointer.
+ Function bodies are comptime-only types while function Pointers may be
+ runtime-known.
+ Primitive types such as Integers and Floats passed as parameters
+ are copied, and then the copy is available in the function body. This is called "passing by value".
+ Copying a primitive type is essentially free and typically involves nothing more than
+ setting a register.
+
+
+ Structs, unions, and arrays can sometimes be more efficiently passed as a reference, since a copy
+ could be arbitrarily expensive depending on the size. When these types are passed
+ as parameters, Zig may choose to copy and pass by value, or pass by reference, whichever way
+ Zig decides will be faster. This is made possible, in part, by the fact that parameters are immutable.
+
+ test_pass_by_reference_or_value.zig
const Point = struct {
+ x: i32,
+ y: i32,
+};
+
+fnfoo(point: Point) i32 {
+ // Here, `point` could be a reference, or a copy. The function body
+ // can ignore the difference and treat it as a value. Be very careful
+ // taking the address of the parameter - it should be treated as if
+ // the address will become invalid when the function returns.
+ return point.x + point.y;
+}
+
+const expect = @import("std").testing.expect;
+
+test"pass struct to function" {
+ try expect(foo(Point{ .x = 1, .y = 2 }) == 3);
+}
Shell
$ zig test test_pass_by_reference_or_value.zig
+1/1 test_pass_by_reference_or_value.test.pass struct to function...OK
+All 1 tests passed.
+
+
+
+ For extern functions, Zig follows the C ABI for passing structs and unions by value.
+
+ Function parameters can be declared with anytype in place of the type.
+ In this case the parameter types will be inferred when the function is called.
+ Use @TypeOf and @typeInfo to get information about the inferred type.
+
+ Adding the inline keyword to a function definition makes that
+ function become semantically inlined at the callsite. This is
+ not a hint to be possibly observed by optimization passes, but has
+ implications on the types and values involved in the function call.
+
+
+ Unlike normal function calls, arguments at an inline function callsite which are
+ compile-time known are treated as Compile Time Parameters. This can potentially
+ propagate all the way to the return value:
+
+ inline_call.zig
test"inline function call" {
+ if (foo(1200, 34) != 1234) {
+ @compileError("bad");
+ }
+}
+
+inlinefnfoo(a: i32, b: i32) i32 {
+ return a + b;
+}
Shell
$ zig test inline_call.zig
+1/1 inline_call.test.inline function call...OK
+All 1 tests passed.
+
+
+
If inline is removed, the test fails with the compile error
+ instead of passing.
+
It is generally better to let the compiler decide when to inline a
+ function, except for these scenarios:
+
+
To change how many stack frames are in the call stack, for debugging purposes.
+
To force comptime-ness of the arguments to propagate to the return value of the function, as in the above example.
+
Real world performance measurements demand it.
+
+
Note that inline actually restricts
+ what the compiler is allowed to do. This can harm binary size,
+ compilation speed, and even runtime performance.
+ An error set is like an enum.
+ However, each error name across the entire compilation gets assigned an unsigned integer
+ greater than 0. You are allowed to declare the same error name more than once, and if you do, it
+ gets assigned the same integer value.
+
+
+ The error set type defaults to a u16, though if the maximum number of distinct
+ error values is provided via the --error-limit [num] command line parameter an integer type
+ with the minimum number of bits required to represent all of the error values will be used.
+
+
+ You can coerce an error from a subset to a superset:
+
$ zig test test_coerce_error_superset_to_subset.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: error: expected type 'error{OutOfMemory}', found 'error{AccessDenied,OutOfMemory,FileNotFound}'
+ return err;
+ ^~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.AccessDenied' not a member of destination error set
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.FileNotFound' not a member of destination error set
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:15:28: note: function return type declared here
+fn foo(err: FileOpenError) AllocationError {
+ ^~~~~~~~~~~~~~~
+referenced by:
+ test.coerce superset to subset: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:12:8
+
+
+
+
+ There is a shortcut for declaring an error set with only 1 value, and then getting that value:
+
anyerror refers to the global error set.
+ This is the error set that contains all errors in the entire compilation unit, i.e. it is the union of all other error sets.
+
+
+ You can coerce any error set to the global one, and you can explicitly
+ cast an error of the global error set to a non-global one. This inserts a language-level
+ assert to make sure the error value is in fact in the destination error set.
+
+
+ The global error set should generally be avoided because it prevents the
+ compiler from knowing what errors are possible at compile-time. Knowing
+ the error set at compile-time is better for generated documentation and
+ helpful error messages, such as forgetting a possible error value in a switch.
+
+ An error set type and normal type can be combined with the !
+ binary operator to form an error union type. You are likely to use an
+ error union type more often than an error set type by itself.
+
+
+ Here is a function to parse a string into a 64-bit integer:
+
+ error_union_parsing_u64.zig
const std = @import("std");
+const maxInt = std.math.maxInt;
+
+pubfnparseU64(buf: []constu8, radix: u8) !u64 {
+ var x: u64 = 0;
+
+ for (buf) |c| {
+ const digit = charToDigit(c);
+
+ if (digit >= radix) {
+ returnerror.InvalidChar;
+ }
+
+ // x *= radix
+ var ov = @mulWithOverflow(x, radix);
+ if (ov[1] != 0) returnerror.OverFlow;
+
+ // x += digit
+ ov = @addWithOverflow(ov[0], digit);
+ if (ov[1] != 0) returnerror.OverFlow;
+ x = ov[0];
+ }
+
+ return x;
+}
+
+fncharToDigit(c: u8) u8 {
+ returnswitch (c) {
+ '0'...'9' => c - '0',
+ 'A'...'Z' => c - 'A' + 10,
+ 'a'...'z' => c - 'a' + 10,
+ else => maxInt(u8),
+ };
+}
+
+test"parse u64" {
+ const result = try parseU64("1234", 10);
+ try std.testing.expect(result == 1234);
+}
+ Notice the return type is !u64. This means that the function
+ either returns an unsigned 64 bit integer, or an error. We left off the error set
+ to the left of the !, so the error set is inferred.
+
+
+ Within the function definition, you can see some return statements that return
+ an error, and at the bottom a return statement that returns a u64.
+ Both types coerce to anyerror!u64.
+
+
+ What it looks like to use this function varies depending on what you're
+ trying to do. One of the following:
+
+
+
You want to provide a default value if it returned an error.
+
If it returned an error then you want to return the same error.
+
You know with complete certainty it will not return an error, so want to unconditionally unwrap it.
+
You want to take a different action for each possible error.
+ In this code, number will be equal to the successfully parsed string, or
+ a default value of 13. The type of the right hand side of the binary catch operator must
+ match the unwrapped error union type, or be of type noreturn.
+
+
+ If you want to provide a default value with
+ catch after performing some logic, you
+ can combine catch with named Blocks:
+
+ handle_error_with_catch_block.zig.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
+
+fndoAThing(str: []u8) void {
+ const number = parseU64(str, 10) catch blk: {
+ // do things
+ break :blk 13;
+ };
+ _ = number; // number is now initialized
+}
+ try evaluates an error union expression. If it is an error, it returns
+ from the current function with the same error. Otherwise, the expression results in
+ the unwrapped value.
+
+
+
+ Maybe you know with complete certainty that an expression will never be an error.
+ In this case you can do this:
+
+ const number = parseU64("1234", 10) catchunreachable;
+
+ Here we know for sure that "1234" will parse successfully. So we put the
+ unreachable value on the right hand side.
+ unreachable invokes safety-checked Illegal Behavior, so
+ in Debug and ReleaseSafe, triggers a safety panic by default. So, while
+ we're debugging the application, if there was a surprise error here, the application
+ would crash appropriately.
+
+
+ You may want to take a different action for every situation. For that, we combine
+ the if and switch expression:
+
+ handle_all_error_scenarios.zig
fndoAThing(str: []u8) void {
+ if (parseU64(str, 10)) |number| {
+ doSomethingWithNumber(number);
+ } else |err| switch (err) {
+ error.Overflow => {
+ // handle overflow...
+ },
+ // we promise that InvalidChar won't happen (or crash in debug mode if it does)
+ error.InvalidChar => unreachable,
+ }
+}
+
+ Finally, you may want to handle only some errors. For that, you can capture the unhandled
+ errors in the else case, which now contains a narrower error set:
+
+ The other component to error handling is defer statements.
+ In addition to an unconditional defer, Zig has errdefer,
+ which evaluates the deferred expression on block exit path if and only if
+ the function returned with an error from the block.
+
+
+ Example:
+
+ errdefer_example.zig
fncreateFoo(param: i32) !Foo {
+ const foo = try tryToAllocateFoo();
+ // now we have allocated foo. we need to free it if the function fails.
+ // but we want to return it if the function succeeds.
+ errdefer deallocateFoo(foo);
+
+ const tmp_buf = allocateTmpBuffer() orelsereturnerror.OutOfMemory;
+ // tmp_buf is truly a temporary resource, and we for sure want to clean it up
+ // before this block leaves scope
+ defer deallocateTmpBuffer(tmp_buf);
+
+ if (param > 1337) returnerror.InvalidParam;
+
+ // here the errdefer will not run since we're returning success from the function.
+ // but the defer will run!
+ return foo;
+}
+
+ The neat thing about this is that you get robust error handling without
+ the verbosity and cognitive overhead of trying to make sure every exit path
+ is covered. The deallocation code is always directly following the allocation code.
+
+
+ The errdefer statement can optionally capture the error:
+
+ A couple of other tidbits about error handling:
+
+
+
These primitives give enough expressiveness that it's completely practical
+ to have failing to check for an error be a compile error. If you really want
+ to ignore the error, you can add catchunreachable and
+ get the added benefit of crashing in Debug and ReleaseSafe modes if your assumption was wrong.
+
+
+ Since Zig understands error types, it can pre-weight branches in favor of
+ errors not occurring. Just a small optimization benefit that is not available
+ in other languages.
+
An error union is created with the ! binary operator.
+ You can use compile-time reflection to access the child type of an error union:
+ test_error_union.zig
const expect = @import("std").testing.expect;
+
+test"error union" {
+ var foo: anyerror!i32 = undefined;
+
+ // Coerce from child type of an error union:
+ foo = 1234;
+
+ // Coerce from an error set:
+ foo = error.SomeError;
+
+ // Use compile-time reflection to access the payload type of an error union:
+ trycomptime expect(@typeInfo(@TypeOf(foo)).error_union.payload == i32);
+
+ // Use compile-time reflection to access the error set type of an error union:
+ trycomptime expect(@typeInfo(@TypeOf(foo)).error_union.error_set == anyerror);
+}
+ Use the || operator to merge two error sets together. The resulting
+ error set contains the errors of both error sets. Doc comments from the left-hand
+ side override doc comments from the right-hand side. In this example, the doc
+ comments for C.PathNotFound is A doc comment.
+
+
+ This is especially useful for functions which return different error sets depending
+ on comptime branches. For example, the Zig standard library uses
+ LinuxFileOpenError || WindowsFileOpenError for the error set of opening
+ files.
+
+ Because many functions in Zig return a possible error, Zig supports inferring the error set.
+ To infer the error set for a function, prepend the ! operator to the function’s return type, like !T:
+
+ test_inferred_error_sets.zig
// With an inferred error set
+pubfnadd_inferred(comptime T: type, a: T, b: T) !T {
+ const ov = @addWithOverflow(a, b);
+ if (ov[1] != 0) returnerror.Overflow;
+ return ov[0];
+}
+
+// With an explicit error set
+pubfnadd_explicit(comptime T: type, a: T, b: T) Error!T {
+ const ov = @addWithOverflow(a, b);
+ if (ov[1] != 0) returnerror.Overflow;
+ return ov[0];
+}
+
+const Error = error{
+ Overflow,
+};
+
+const std = @import("std");
+
+test"inferred error set" {
+ if (add_inferred(u8, 255, 1)) |_| unreachableelse |err| switch (err) {
+ error.Overflow => {}, // ok
+ }
+}
+ When a function has an inferred error set, that function becomes generic and thus it becomes
+ trickier to do certain things with it, such as obtain a function pointer, or have an error
+ set that is consistent across different build targets. Additionally, inferred error sets
+ are incompatible with recursion.
+
+
+ In these situations, it is recommended to use an explicit error set. You can generally start
+ with an empty error set and let compile errors guide you toward completing the set.
+
+
+ These limitations may be overcome in a future version of Zig.
+
+ Error Return Traces show all the points in the code that an error was returned to the calling function. This makes it practical to use try everywhere and then still be able to know what happened if an error ends up bubbling all the way out of your application.
+
$ zig build-exe error_return_trace.zig
+$ ./error_return_trace
+error: PermissionDenied
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:34:5: 0x10de038 in bang1 (error_return_trace)
+ return error.FileNotFound;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:22:5: 0x10de063 in baz (error_return_trace)
+ try bang1();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:38:5: 0x10de088 in bang2 (error_return_trace)
+ return error.PermissionDenied;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:30:5: 0x10de0f3 in hello (error_return_trace)
+ try bang2();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:17:31: 0x10de198 in bar (error_return_trace)
+ error.FileNotFound => try hello(),
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:7:9: 0x10de200 in foo (error_return_trace)
+ try bar();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:2:5: 0x10de258 in main (error_return_trace)
+ try foo(12);
+ ^
+
+
+
+ Look closely at this example. This is no stack trace.
+
+
+ You can see that the final error bubbled up was PermissionDenied,
+ but the original error that started this whole thing was FileNotFound. In the bar function, the code handles the original error code,
+ and then returns another one, from the switch statement. Error Return Traces make this clear, whereas a stack trace would look like this:
+
$ zig build-exe stack_trace.zig
+$ ./stack_trace
+thread 1081770 panic: PermissionDenied
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:38:5: 0x10decfc in bang2 (stack_trace)
+ @panic("PermissionDenied");
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:30:10: 0x10df5c8 in hello (stack_trace)
+ bang2();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:17:14: 0x10decd0 in bar (stack_trace)
+ hello();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:7:12: 0x10deaf4 in foo (stack_trace)
+ bar();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:2:8: 0x10de28d in main (stack_trace)
+ foo(12);
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10ddc82 in posixCallMainAndExit (stack_trace)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10dd85d in _start (stack_trace)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+(process terminated by signal)
+
+
+
+ Here, the stack trace does not explain how the control
+ flow in bar got to the hello() call.
+ One would have to open a debugger or further instrument the application
+ in order to find out. The error return trace, on the other hand,
+ shows exactly how the error bubbled up.
+
+
+ This debugging feature makes it easier to iterate quickly on code that
+ robustly handles all error conditions. This means that Zig developers
+ will naturally find themselves writing correct, robust code in order
+ to increase their development pace.
+
+ There are a few ways to activate this error return tracing feature:
+
+
+
Return an error from main
+
An error makes its way to catchunreachable and you have not overridden the default panic handler
+
Use errorReturnTrace to access the current return trace. You can use std.debug.dumpStackTrace to print it. This function returns comptime-known null when building without error return tracing support.
+ To analyze performance cost, there are two cases:
+
+
+
when no errors are returned
+
when returning errors
+
+
+ For the case when no errors are returned, the cost is a single memory write operation, only in the first non-failable function in the call graph that calls a failable function, i.e. when a function returning void calls a function returning error.
+ This is to initialize this struct in the stack memory:
+
+ Here, N is the maximum function call depth as determined by call graph analysis. Recursion is ignored and counts for 2.
+
+
+ A pointer to StackTrace is passed as a secret parameter to every function that can return an error, but it's always the first parameter, so it can likely sit in a register and stay there.
+
+
+ That's it for the path when no errors occur. It's practically free in terms of performance.
+
+
+ When generating the code for a function that returns an error, just before the return statement (only for the return statements that return errors), Zig generates a call to this function:
+
+ zig_return_error_fn.zig
// marked as "no-inline" in LLVM IR
+fn__zig_return_error(stack_trace: *StackTrace) void {
+ stack_trace.instruction_addresses[stack_trace.index] = @returnAddress();
+ stack_trace.index = (stack_trace.index + 1) % N;
+}
+
+ The cost is 2 math operations plus some memory reads and writes. The memory accessed is constrained and should remain cached for the duration of the error return bubbling.
+
+
+ As for code size cost, 1 function call before a return statement is no big deal. Even so,
+ I have a plan to make the call to
+ __zig_return_error a tail call, which brings the code size cost down to actually zero. What is a return statement in code without error return tracing can become a jump instruction in code with error return tracing.
+
+ Now the variable optional_int could be an i32, or null.
+
+
+ Instead of integers, let's talk about pointers. Null references are the source of many runtime
+ exceptions, and even stand accused of being
+ the worst mistake of computer science.
+
+
Zig does not have them.
+
+ Instead, you can use an optional pointer. This secretly compiles down to a normal pointer,
+ since we know we can use 0 as the null value for the optional type. But the compiler
+ can check your work and make sure you don't assign null to something that can't be null.
+
+
+ Typically the downside of not having null is that it makes the code more verbose to
+ write. But, let's compare some equivalent C code and Zig code.
+
+
+ Task: call malloc, if the result is null, return null.
+
+
C code
+ call_malloc_in_c.c
// malloc prototype included for reference
+void *malloc(size_t size);
+
+struct Foo *do_a_thing(void) {
+ char *ptr = malloc(1234);
+ if (!ptr) return NULL;
+ // ...
+}
+ Here, Zig is at least as convenient, if not more, than C. And, the type of "ptr"
+ is [*]u8not?[*]u8. The orelse keyword
+ unwrapped the optional type and therefore ptr is guaranteed to be non-null everywhere
+ it is used in the function.
+
+
+ The other form of checking against NULL you might see looks like this:
+
+ checking_null_in_c.c
void do_a_thing(struct Foo *foo) {
+ // do some stuff
+
+ if (foo) {
+ do_something_with_foo(foo);
+ }
+
+ // do some stuff
+}
+
+ In Zig you can accomplish the same thing:
+
+ checking_null_in_zig.zig
const Foo = struct {};
+fndoSomethingWithFoo(foo: *Foo) void {
+ _ = foo;
+}
+
+fndoAThing(optional_foo: ?*Foo) void {
+ // do some stuff
+
+ if (optional_foo) |foo| {
+ doSomethingWithFoo(foo);
+ }
+
+ // do some stuff
+}
+
+
+ Once again, the notable thing here is that inside the if block,
+ foo is no longer an optional pointer, it is a pointer, which
+ cannot be null.
+
+
+ One benefit to this is that functions which take pointers as arguments can
+ be annotated with the "nonnull" attribute - __attribute__((nonnull)) in
+ GCC.
+ The optimizer can sometimes make better decisions knowing that pointer arguments
+ cannot be null.
+
An optional is created by putting ? in front of a type. You can use compile-time
+ reflection to access the child type of an optional:
+ test_optional_type.zig
const expect = @import("std").testing.expect;
+
+test"optional type" {
+ // Declare an optional and coerce from null:
+ var foo: ?i32 = null;
+
+ // Coerce from child type of an optional
+ foo = 1234;
+
+ // Use compile-time reflection to access the child type of the optional:
+ trycomptime expect(@typeInfo(@TypeOf(foo)).optional.child == i32);
+}
An optional pointer is guaranteed to be the same size as a pointer. The null of
+ the optional is guaranteed to be address 0.
+ test_optional_pointer.zig
const expect = @import("std").testing.expect;
+
+test"optional pointers" {
+ // Pointers cannot be null. If you want a null pointer, use the optional
+ // prefix `?` to make the pointer type optional.
+ var ptr: ?*i32 = null;
+
+ var x: i32 = 1;
+ ptr = &x;
+
+ try expect(ptr.?.* == 1);
+
+ // Optional pointers are the same size as normal pointers, because pointer
+ // value 0 is used as the null value.
+ try expect(@sizeOf(?*i32) == @sizeOf(*i32));
+}
+ A type cast converts a value of one type to another.
+ Zig has Type Coercion for conversions that are known to be completely safe and unambiguous,
+ and Explicit Casts for conversions that one would not want to happen on accident.
+ There is also a third kind of type conversion called Peer Type Resolution for
+ the case when a result type must be decided given multiple operand types.
+
+ Type coercions are only allowed when it is completely unambiguous how to get from one type to another,
+ and the transformation is guaranteed to be safe. There is one exception, which is C Pointers.
+
+ Values which have the same representation at runtime can be cast to increase the strictness
+ of the qualifiers, no matter how nested the qualifiers are:
+
+ Integers coerce to integer types which can represent every value of the old type, and likewise
+ Floats coerce to float types which can represent every value of the old type.
+
When a number is comptime-known to be representable in the destination type,
+ it may be coerced:
+
+ test_coerce_large_to_small.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"coercing large integer type to smaller one when value is comptime-known to fit" {
+ const x: u64 = 255;
+ const y: u8 = x;
+ try expect(y == 255);
+}
Shell
$ zig test test_coerce_large_to_small.zig
+1/1 test_coerce_large_to_small.test.coercing large integer type to smaller one when value is comptime-known to fit...OK
+All 1 tests passed.
+
Tagged unions can be coerced to enums, and enums can be coerced to tagged unions
+ when they are comptime-known to be a field of the union that has only one possible value, such as
+ void:
+
+ test_coerce_unions_enums.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+const E = enum {
+ one,
+ two,
+ three,
+};
+
+const U = union(E) {
+ one: i32,
+ two: f32,
+ three,
+};
+
+const U2 = union(enum) {
+ a: void,
+ b: f32,
+
+ fntag(self: U2) usize {
+ switch (self) {
+ .a => return1,
+ .b => return2,
+ }
+ }
+};
+
+test"coercion between unions and enums" {
+ const u = U{ .two = 12.34 };
+ const e: E = u; // coerce union to enum
+ try expect(e == E.two);
+
+ const three = E.three;
+ const u_2: U = three; // coerce enum to union
+ try expect(u_2 == E.three);
+
+ const u_3: U = .three; // coerce enum literal to union
+ try expect(u_3 == E.three);
+
+ const u_4: U2 = .a; // coerce enum literal to union with inferred enum tag type.
+ try expect(u_4.tag() == 1);
+
+ // The following example is invalid.
+ // error: coercion from enum '@TypeOf(.enum_literal)' to union 'test_coerce_unions_enum.U2' must initialize 'f32' field 'b'
+ //var u_5: U2 = .b;
+ //try expect(u_5.tag() == 2);
+}
Shell
$ zig test test_coerce_unions_enums.zig
+1/1 test_coerce_unions_enums.test.coercion between unions and enums...OK
+All 1 tests passed.
+
+ Explicit casts are performed via Builtin Functions.
+ Some explicit casts are safe; some are not.
+ Some explicit casts perform language-level assertions; some do not.
+ Some explicit casts are no-ops at runtime; some are not.
+
+
+
@bitCast - change type but maintain bit representation
+ This kind of type resolution chooses a type that all peer types can coerce into. Here are
+ some examples:
+
+ test_peer_type_resolution.zig
const std = @import("std");
+const expect = std.testing.expect;
+const mem = std.mem;
+
+test"peer resolve int widening" {
+ const a: i8 = 12;
+ const b: i16 = 34;
+ const c = a + b;
+ try expect(c == 46);
+ try expect(@TypeOf(c) == i16);
+}
+
+test"peer resolve arrays of different size to const slice" {
+ try expect(mem.eql(u8, boolToStr(true), "true"));
+ try expect(mem.eql(u8, boolToStr(false), "false"));
+ trycomptime expect(mem.eql(u8, boolToStr(true), "true"));
+ trycomptime expect(mem.eql(u8, boolToStr(false), "false"));
+}
+fnboolToStr(b: bool) []constu8 {
+ returnif (b) "true"else"false";
+}
+
+test"peer resolve array and const slice" {
+ try testPeerResolveArrayConstSlice(true);
+ trycomptime testPeerResolveArrayConstSlice(true);
+}
+fntestPeerResolveArrayConstSlice(b: bool) !void {
+ const value1 = if (b) "aoeu"else@as([]constu8, "zz");
+ const value2 = if (b) @as([]constu8, "zz") else"aoeu";
+ try expect(mem.eql(u8, value1, "aoeu"));
+ try expect(mem.eql(u8, value2, "zz"));
+}
+
+test"peer type resolution: ?T and T" {
+ try expect(peerTypeTAndOptionalT(true, false).? == 0);
+ try expect(peerTypeTAndOptionalT(false, false).? == 3);
+ comptime {
+ try expect(peerTypeTAndOptionalT(true, false).? == 0);
+ try expect(peerTypeTAndOptionalT(false, false).? == 3);
+ }
+}
+fnpeerTypeTAndOptionalT(c: bool, b: bool) ?usize {
+ if (c) {
+ returnif (b) nullelse@as(usize, 0);
+ }
+
+ return@as(usize, 3);
+}
+
+test"peer type resolution: *[0]u8 and []const u8" {
+ try expect(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
+ try expect(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
+ comptime {
+ try expect(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
+ try expect(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
+ }
+}
+fnpeerTypeEmptyArrayAndSlice(a: bool, slice: []constu8) []constu8 {
+ if (a) {
+ return &[_]u8{};
+ }
+
+ return slice[0..1];
+}
+test"peer type resolution: *[0]u8, []const u8, and anyerror![]u8" {
+ {
+ var data = "hi".*;
+ const slice = data[0..];
+ try expect((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
+ try expect((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
+ }
+ comptime {
+ var data = "hi".*;
+ const slice = data[0..];
+ try expect((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
+ try expect((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
+ }
+}
+fnpeerTypeEmptyArrayAndSliceAndError(a: bool, slice: []u8) anyerror![]u8 {
+ if (a) {
+ return &[_]u8{};
+ }
+
+ return slice[0..1];
+}
+
+test"peer type resolution: *const T and ?*T" {
+ const a: *constusize = @ptrFromInt(0x123456780);
+ const b: ?*usize = @ptrFromInt(0x123456780);
+ try expect(a == b);
+ try expect(b == a);
+}
+
+test"peer type resolution: error union switch" {
+ // The non-error and error cases are only peers if the error case is just a switch expression;
+ // the pattern `if (x) {...} else |err| blk: { switch (err) {...} }` does not consider the
+ // non-error and error case to be peers.
+ var a: error{ A, B, C }!u32 = 0;
+ _ = &a;
+ const b = if (a) |x|
+ x + 3
+ else |err| switch (err) {
+ error.A => 0,
+ error.B => 1,
+ error.C => null,
+ };
+ try expect(@TypeOf(b) == ?u32);
+
+ // The non-error and error cases are only peers if the error case is just a switch expression;
+ // the pattern `x catch |err| blk: { switch (err) {...} }` does not consider the unwrapped `x`
+ // and error case to be peers.
+ const c = a catch |err| switch (err) {
+ error.A => 0,
+ error.B => 1,
+ error.C => null,
+ };
+ try expect(@TypeOf(c) == ?u32);
+}
Shell
$ zig test test_peer_type_resolution.zig
+1/8 test_peer_type_resolution.test.peer resolve int widening...OK
+2/8 test_peer_type_resolution.test.peer resolve arrays of different size to const slice...OK
+3/8 test_peer_type_resolution.test.peer resolve array and const slice...OK
+4/8 test_peer_type_resolution.test.peer type resolution: ?T and T...OK
+5/8 test_peer_type_resolution.test.peer type resolution: *[0]u8 and []const u8...OK
+6/8 test_peer_type_resolution.test.peer type resolution: *[0]u8, []const u8, and anyerror![]u8...OK
+7/8 test_peer_type_resolution.test.peer type resolution: *const T and ?*T...OK
+8/8 test_peer_type_resolution.test.peer type resolution: error union switch...OK
+All 8 tests passed.
+
A union with only 1 field which is a zero bit type.
+
+
+ These types can only ever have one possible value, and thus
+ require 0 bits to represent. Code that makes use of these types is
+ not included in the final generated code:
+
+ zero_bit_types.zig
exportfnentry() void {
+ var x: void = {};
+ var y: void = {};
+ x = y;
+ y = x;
+}
+
+
When this turns into machine code, there is no code generated in the
+ body of entry, even in Debug mode. For example, on x86_64:
+ void can be useful for instantiating generic types. For example, given a
+ Map(Key, Value), one can pass void for the Value
+ type to make it into a Set:
+
$ zig test test_void_in_hashmap.zig
+1/1 test_void_in_hashmap.test.turn HashMap into a set with void...OK
+All 1 tests passed.
+
+
+
Note that this is different from using a dummy value for the hash map value.
+ By using void as the type of the value, the hash map entry type has no value field, and
+ thus the hash map takes up less space. Further, all the code that deals with storing and loading the
+ value is deleted, as seen above.
+
+
+ void is distinct from anyopaque.
+ void has a known size of 0 bytes, and anyopaque has an unknown, but non-zero, size.
+
+
+ Expressions of type void are the only ones whose value can be ignored. For example, ignoring
+ a non-void expression is a compile error:
+
$ zig test test_expression_ignored.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: error: value of type 'i32' ignored
+ foo();
+ ~~~^~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: note: all non-void values must be used
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: note: to discard the value, assign it to '_'
+
+
+
+
However, if the expression has type void, there will be no error. Expression results can be explicitly ignored by assigning them to _.
+ During compilation, every Zig expression and sub-expression is assigned optional result location
+ information. This information dictates what type the expression should have (its result type), and
+ where the resulting value should be placed in memory (its result location). The information is
+ optional in the sense that not every expression has this information: assignment to
+ _, for instance, does not provide any information about the type of an
+ expression, nor does it provide a concrete memory location to place it in.
+
+
+ As a motivating example, consider the statement const x: u32 = 42;. The type
+ annotation here provides a result type of u32 to the initialization expression
+ 42, instructing the compiler to coerce this integer (initially of type
+ comptime_int) to this type. We will see more examples shortly.
+
+
+ This is not an implementation detail: the logic outlined above is codified into the Zig language
+ specification, and is the primary mechanism of type inference in the language. This system is
+ collectively referred to as "Result Location Semantics".
+
+ Result types are propagated recursively through expressions where possible. For instance, if the
+ expression &e has result type *u32, then
+ e is given a result type of u32, allowing the
+ language to perform this coercion before taking a reference.
+
+
+ The result type mechanism is utilized by casting builtins such as @intCast.
+ Rather than taking as an argument the type to cast to, these builtins use their result type to
+ determine this information. The result type is often known from context; where it is not, the
+ @as builtin can be used to explicitly provide a result type.
+
+
+ We can break down the result types for each component of a simple expression as follows:
+
+ result_type_propagation.zig
const expectEqual = @import("std").testing.expectEqual;
+test"result type propagates through struct initializer" {
+ const S = struct { x: u32 };
+ const val: u64 = 123;
+ const s: S = .{ .x = @intCast(val) };
+ // .{ .x = @intCast(val) } has result type `S` due to the type annotation
+ // @intCast(val) has result type `u32` due to the type of the field `S.x`
+ // val has no result type, as it is permitted to be any integer type
+ try expectEqual(@as(u32, 123), s.x);
+}
Shell
$ zig test result_type_propagation.zig
+1/1 result_type_propagation.test.result type propagates through struct initializer...OK
+All 1 tests passed.
+
+
+
+ This result type information is useful for the aforementioned cast builtins, as well as to avoid
+ the construction of pre-coercion values, and to avoid the need for explicit type coercions in some
+ cases. The following table details how some common expressions propagate result types, where
+ x and y are arbitrary sub-expressions.
+
+ In addition to result type information, every expression may be optionally assigned a result
+ location: a pointer to which the value must be directly written. This system can be used to prevent
+ intermediate copies when initializing data structures, which can be important for types which must
+ have a fixed memory address ("pinned" types).
+
+
+ When compiling the simple assignment expression x = e, many languages would
+ create the temporary value e on the stack, and then assign it to
+ x, potentially performing a type coercion in the process. Zig approaches this
+ differently. The expression e is given a result type matching the type of
+ x, and a result location of &x. For many syntactic
+ forms of e, this has no practical impact. However, it can have important
+ semantic effects when working with more complex syntax forms.
+
+
+ For instance, if the expression .{ .a = x, .b = y } has a result location of
+ ptr, then x is given a result location of
+ &ptr.a, and y a result location of &ptr.b.
+ Without this system, this expression would construct a temporary struct value entirely on the stack, and
+ only then copy it to the destination address. In essence, Zig desugars the assignment
+ foo = .{ .a = x, .b = y } to the two statements foo.a = x; foo.b = y;.
+
+
+ This can sometimes be important when assigning an aggregate value where the initialization
+ expression depends on the previous value of the aggregate. The easiest way to demonstrate this is by
+ attempting to swap fields of a struct or array - the following logic looks sound, but in fact is not:
+
+ result_location_interfering_with_swap.zig
const expect = @import("std").testing.expect;
+test"attempt to swap array elements with array initializer" {
+ var arr: [2]u32 = .{ 1, 2 };
+ arr = .{ arr[1], arr[0] };
+ // The previous line is equivalent to the following two lines:
+ // arr[0] = arr[1];
+ // arr[1] = arr[0];
+ // So this fails!
+ try expect(arr[0] == 2); // succeeds
+ try expect(arr[1] == 1); // fails
+}
Shell
$ zig test result_location_interfering_with_swap.zig
+1/1 result_location_interfering_with_swap.test.attempt to swap array elements with array initializer...FAIL (TestUnexpectedResult)
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/testing.zig:580:14: 0x104861f in expect (test)
+ if (!ok) return error.TestUnexpectedResult;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/result_location_interfering_with_swap.zig:10:5: 0x1048705 in test.attempt to swap array elements with array initializer (test)
+ try expect(arr[1] == 1); // fails
+ ^
+0 passed; 0 skipped; 1 failed.
+error: the following test command failed with exit code 1:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/5cf73dcca47fe5ad7ad8e07722996213/test --seed=0x914c57cf
+
+
+
+ The following table details how some common expressions propagate result locations, where
+ x and y are arbitrary sub-expressions. Note that
+ some expressions cannot provide meaningful result locations to sub-expressions, even if they
+ themselves have a result location.
+
+
+
+
+
+
Expression
+
Result Location
+
Sub-expression Result Locations
+
+
+
+
+
const val: T = x
+
-
+
x has result location &val
+
+
+
var val: T = x
+
-
+
x has result location &val
+
+
+
val = x
+
-
+
x has result location &val
+
+
+
@as(T, x)
+
ptr
+
x has no result location
+
+
+
&x
+
ptr
+
x has no result location
+
+
+
f(x)
+
ptr
+
x has no result location
+
+
+
.{x}
+
ptr
+
x has result location &ptr[0]
+
+
+
.{ .a = x }
+
ptr
+
x has result location &ptr.a
+
+
+
T{x}
+
ptr
+
x has no result location (typed initializers do not propagate result locations)
+
+
+
T{ .a = x }
+
ptr
+
x has no result location (typed initializers do not propagate result locations)
+ usingnamespace is a declaration that mixes all the public
+ declarations of the operand, which must be a struct, union, enum,
+ or opaque, into the namespace:
+
+ usingnamespace has an important use case when organizing the public
+ API of a file or package. For example, one might have c.zig with all of the
+ C imports:
+
+ The above example demonstrates using pub to qualify the
+ usingnamespace additionally makes the imported declarations
+ pub. This can be used to forward declarations, giving precise control
+ over what declarations a given file exposes.
+
+ Zig places importance on the concept of whether an expression is known at compile-time.
+ There are a few different places this concept is used, and these building blocks are used
+ to keep the language small, readable, and powerful.
+
+ Compile-time parameters is how Zig implements generics. It is compile-time duck typing.
+
+ compile-time_duck_typing.zig
fnmax(comptime T: type, a: T, b: T) T {
+ returnif (a > b) a else b;
+}
+fngimmeTheBiggerFloat(a: f32, b: f32) f32 {
+ return max(f32, a, b);
+}
+fngimmeTheBiggerInteger(a: u64, b: u64) u64 {
+ return max(u64, a, b);
+}
+
+
+ In Zig, types are first-class citizens. They can be assigned to variables, passed as parameters to functions,
+ and returned from functions. However, they can only be used in expressions which are known at compile-time,
+ which is why the parameter T in the above snippet must be marked with comptime.
+
+
+ A comptime parameter means that:
+
+
+
At the callsite, the value must be known at compile-time, or it is a compile error.
+
In the function definition, the value is known at compile-time.
+
+
+ For example, if we were to introduce another function to the above snippet:
+
+ test_unresolved_comptime_value.zig
fnmax(comptime T: type, a: T, b: T) T {
+ returnif (a > b) a else b;
+}
+test"try to pass a runtime type" {
+ foo(false);
+}
+fnfoo(condition: bool) void {
+ const result = max(if (condition) f32elseu64, 1234, 5678);
+ _ = result;
+}
Shell
$ zig test test_unresolved_comptime_value.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:8:28: error: unable to resolve comptime value
+ const result = max(if (condition) f32 else u64, 1234, 5678);
+ ^~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:8:24: note: argument to comptime parameter must be comptime-known
+ const result = max(if (condition) f32 else u64, 1234, 5678);
+ ^~~~~~~~~~~~~~~~~~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:1:8: note: parameter declared comptime here
+fn max(comptime T: type, a: T, b: T) T {
+ ^~~~~~~~
+referenced by:
+ test.try to pass a runtime type: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:5:8
+
+
+
+
+ This is an error because the programmer attempted to pass a value only known at run-time
+ to a function which expects a value known at compile-time.
+
+
+ Another way to get an error is if we pass a type that violates the type checker when the
+ function is analyzed. This is what it means to have compile-time duck typing.
+
+
+ For example:
+
+ test_comptime_mismatched_type.zig
fnmax(comptime T: type, a: T, b: T) T {
+ returnif (a > b) a else b;
+}
+test"try to compare bools" {
+ _ = max(bool, true, false);
+}
Shell
$ zig test test_comptime_mismatched_type.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_mismatched_type.zig:2:18: error: operator > not allowed for type 'bool'
+ return if (a > b) a else b;
+ ~~^~~
+referenced by:
+ test.try to compare bools: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_mismatched_type.zig:5:12
+
+
+
+
+ On the flip side, inside the function definition with the comptime parameter, the
+ value is known at compile-time. This means that we actually could make this work for the bool type
+ if we wanted to:
+
+ test_comptime_max_with_bool.zig
fnmax(comptime T: type, a: T, b: T) T {
+ if (T == bool) {
+ return a or b;
+ } elseif (a > b) {
+ return a;
+ } else {
+ return b;
+ }
+}
+test"try to compare bools" {
+ try@import("std").testing.expect(max(bool, false, true) == true);
+}
Shell
$ zig test test_comptime_max_with_bool.zig
+1/1 test_comptime_max_with_bool.test.try to compare bools...OK
+All 1 tests passed.
+
+
+
+ This works because Zig implicitly inlines if expressions when the condition
+ is known at compile-time, and the compiler guarantees that it will skip analysis of
+ the branch not taken.
+
+
+ This means that the actual function generated for max in this situation looks like
+ this:
+
+ compiler_generated_function.zig
fnmax(a: bool, b: bool) bool {
+ {
+ return a or b;
+ }
+}
+
+
+ All the code that dealt with compile-time known values is eliminated and we are left with only
+ the necessary run-time code to accomplish the task.
+
+
+ This works the same way for switch expressions - they are implicitly inlined
+ when the target expression is compile-time known.
+
+ In Zig, the programmer can label variables as comptime. This guarantees to the compiler
+ that every load and store of the variable is performed at compile-time. Any violation of this results in a
+ compile error.
+
+
+ This combined with the fact that we can inline loops allows us to write
+ a function which is partially evaluated at compile-time and partially at run-time.
+
+ This example is a bit contrived, because the compile-time evaluation component is unnecessary;
+ this code would work fine if it was all done at run-time. But it does end up generating
+ different code. In this example, the function performFn is generated three different times,
+ for the different values of prefix_char provided:
+
+ performFn_1
// From the line:
+// expect(performFn('t', 1) == 6);
+fnperformFn(start_value: i32) i32 {
+ var result: i32 = start_value;
+ result = two(result);
+ result = three(result);
+ return result;
+}
+ performFn_2
// From the line:
+// expect(performFn('o', 0) == 1);
+fnperformFn(start_value: i32) i32 {
+ var result: i32 = start_value;
+ result = one(result);
+ return result;
+}
+ performFn_3
// From the line:
+// expect(performFn('w', 99) == 99);
+fnperformFn(start_value: i32) i32 {
+ var result: i32 = start_value;
+ _ = &result;
+ return result;
+}
+
+ Note that this happens even in a debug build.
+ This is not a way to write more optimized code, but it is a way to make sure that what should happen
+ at compile-time, does happen at compile-time. This catches more errors and allows expressiveness
+ that in other languages requires using macros, generated code, or a preprocessor to accomplish.
+
+ In Zig, it matters whether a given expression is known at compile-time or run-time. A programmer can
+ use a comptime expression to guarantee that the expression will be evaluated at compile-time.
+ If this cannot be accomplished, the compiler will emit an error. For example:
+
$ zig test test_comptime_call_extern_function.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_call_extern_function.zig:5:13: error: comptime call of extern function
+ exit();
+ ~~~~^~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_call_extern_function.zig:4:5: note: 'comptime' keyword forces comptime evaluation
+ comptime {
+ ^~~~~~~~
+
+
+
+
+ It doesn't make sense that a program could call exit() (or any other external function)
+ at compile-time, so this is a compile error. However, a comptime expression does much
+ more than sometimes cause a compile error.
+
+
+ Within a comptime expression:
+
+
+
All variables are comptime variables.
+
All if, while, for, and switch
+ expressions are evaluated at compile-time, or emit a compile error if this is not possible.
+
All return and try expressions are invalid (unless the function itself is called at compile-time).
+
All code with runtime side effects or depending on runtime values emits a compile error.
+
All function calls cause the compiler to interpret the function at compile-time, emitting a
+ compile error if the function tries to do something that has global runtime side effects.
+
+
+ This means that a programmer can create a function which is called both at compile-time and run-time, with
+ no modification to the function required.
+
$ zig test test_fibonacci_comptime_overflow.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:5:28: error: overflow of integer type 'u32' with value '-1'
+ return fibonacci(index - 1) + fibonacci(index - 2);
+ ~~~~~~^~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:5:21: note: called from here (7 times)
+ return fibonacci(index - 1) + fibonacci(index - 2);
+ ~~~~~~~~~^~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:9:34: note: called from here
+ try comptime expect(fibonacci(7) == 13);
+ ~~~~~~~~~^~~
+
+
+
+
+ The compiler produces an error which is a stack trace from trying to evaluate the
+ function at compile-time.
+
+
+ Luckily, we used an unsigned integer, and so when we tried to subtract 1 from 0, it triggered
+ Illegal Behavior, which is always a compile error if the compiler knows it happened.
+ But what would have happened if we used a signed integer?
+
+ The compiler is supposed to notice that evaluating this function at
+ compile-time took more than 1000 branches, and thus emits an error and
+ gives up. If the programmer wants to increase the budget for compile-time
+ computation, they can use a built-in function called
+ @setEvalBranchQuota to change the default number 1000 to
+ something else.
+
+
+ However, there is a design
+ flaw in the compiler causing it to stack overflow instead of having the proper
+ behavior here. I'm terribly sorry about that. I hope to get this resolved
+ before the next release.
+
+
+ What if we fix the base case, but put the wrong value in the
+ expect line?
+
$ zig test test_fibonacci_comptime_unreachable.zig
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:550:14: error: reached unreachable code
+ if (!ok) unreachable; // assertion failure
+ ^~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_unreachable.zig:9:24: note: called from here
+ try comptime assert(fibonacci(7) == 99999);
+ ~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+
+
+ At container level (outside of any function), all expressions are implicitly
+ comptime expressions. This means that we can use functions to
+ initialize complex static data. For example:
+
+ Note that we did not have to do anything special with the syntax of these functions. For example,
+ we could call the sum function as is with a slice of numbers whose length and values were
+ only known at run-time.
+
+ Zig uses comptime capabilities to implement generic data structures without introducing any
+ special-case syntax.
+
+
+ Here is an example of a generic List data structure.
+
+ generic_data_structure.zig
fnList(comptime T: type) type {
+ returnstruct {
+ items: []T,
+ len: usize,
+ };
+}
+
+// The generic List data structure can be instantiated by passing in a type:
+var buffer: [10]i32 = undefined;
+var list = List(i32){
+ .items = &buffer,
+ .len = 0,
+};
+
+
+ That's it. It's a function that returns an anonymous struct.
+ For the purposes of error messages and debugging, Zig infers the name
+ "List(i32)" from the function name and parameters invoked when creating
+ the anonymous struct.
+
+
+ To explicitly give a type a name, we assign it to a constant.
+
+ In this example, the Node struct refers to itself.
+ This works because all top level declarations are order-independent.
+ As long as the compiler can determine the size of the struct, it is free to refer to itself.
+ In this case, Node refers to itself as a pointer, which has a
+ well-defined size at compile time, so it works fine.
+
+ This is a proof of concept implementation; the actual function in the standard library has more
+ formatting capabilities.
+
+
+ Note that this is not hard-coded into the Zig compiler; this is userland code in the standard library.
+
+
+ When this function is analyzed from our example code above, Zig partially evaluates the function
+ and emits a function that actually looks like this:
+
+ Emitted print Function
pubfnprint(self: *Writer, arg0: []constu8, arg1: i32) !void {
+ try self.write("here is a string: '");
+ try self.printValue(arg0);
+ try self.write("' here is a number: ");
+ try self.printValue(arg1);
+ try self.write("\n");
+ try self.flush();
+}
+
+ printValue is a function that takes a parameter of any type, and does different things depending
+ on the type:
+
+ And now, what happens if we give too many arguments to print?
+
+ test_print_too_many_args.zig
const print = @import("std").debug.print;
+
+const a_number: i32 = 1234;
+const a_string = "foobar";
+
+test"print too many arguments" {
+ print("here is a string: '{s}' here is a number: {}\n", .{
+ a_string,
+ a_number,
+ a_number,
+ });
+}
Shell
$ zig test test_print_too_many_args.zig
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/fmt.zig:211:18: error: unused argument in 'here is a string: '{s}' here is a number: {}
+ '
+ 1 => @compileError("unused argument in '" ++ fmt ++ "'"),
+ ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+referenced by:
+ print__anon_679: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/io/Writer.zig:24:26
+ print__anon_420: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/io.zig:312:47
+ 1 reference(s) hidden; use '-freference-trace=3' to see all references
+
+
+
+
+ Zig gives programmers the tools needed to protect themselves against their own mistakes.
+
+
+ Zig doesn't care whether the format argument is a string literal,
+ only that it is a compile-time known value that can be coerced to a []constu8:
+
+ print_comptime-known_format.zig
const print = @import("std").debug.print;
+
+const a_number: i32 = 1234;
+const a_string = "foobar";
+const fmt = "here is a string: '{s}' here is a number: {}\n";
+
+pubfnmain() void {
+ print(fmt, .{ a_string, a_number });
+}
Shell
$ zig build-exe print_comptime-known_format.zig
+$ ./print_comptime-known_format
+here is a string: 'foobar' here is a number: 1234
+
+
+
+ This works fine.
+
+
+ Zig does not special case string formatting in the compiler and instead exposes enough power to accomplish this
+ task in userland. It does so without introducing another language on top of Zig, such as
+ a macro language or a preprocessor language. It's Zig all the way down.
+
+ For some use cases, it may be necessary to directly control the machine code generated
+ by Zig programs, rather than relying on Zig's code generation. For these cases, one
+ can use inline assembly. Here is an example of implementing Hello, World on x86_64 Linux
+ using inline assembly:
+
pubfnsyscall1(number: usize, arg1: usize) usize {
+ // Inline assembly is an expression which returns a value.
+ // the `asm` keyword begins the expression.
+ returnasm
+ // `volatile` is an optional modifier that tells Zig this
+ // inline assembly expression has side-effects. Without
+ // `volatile`, Zig is allowed to delete the inline assembly
+ // code if the result is unused.
+ volatile (
+ // Next is a comptime string which is the assembly code.
+ // Inside this string one may use `%[ret]`, `%[number]`,
+ // or `%[arg1]` where a register is expected, to specify
+ // the register that Zig uses for the argument or return value,
+ // if the register constraint strings are used. However in
+ // the below code, this is not used. A literal `%` can be
+ // obtained by escaping it with a double percent: `%%`.
+ // Often multiline string syntax comes in handy here.
+ \\syscall
+ // Next is the output. It is possible in the future Zig will
+ // support multiple outputs, depending on how
+ // https://github.com/ziglang/zig/issues/215 is resolved.
+ // It is allowed for there to be no outputs, in which case
+ // this colon would be directly followed by the colon for the inputs.
+ :
+ // This specifies the name to be used in `%[ret]` syntax in
+ // the above assembly string. This example does not use it,
+ // but the syntax is mandatory.
+ [ret]
+ // Next is the output constraint string. This feature is still
+ // considered unstable in Zig, and so LLVM/GCC documentation
+ // must be used to understand the semantics.
+ // http://releases.llvm.org/10.0.0/docs/LangRef.html#inline-asm-constraint-string
+ // https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
+ // In this example, the constraint string means "the result value of
+ // this inline assembly instruction is whatever is in $rax".
+ "={rax}"
+ // Next is either a value binding, or `->` and then a type. The
+ // type is the result type of the inline assembly expression.
+ // If it is a value binding, then `%[ret]` syntax would be used
+ // to refer to the register bound to the value.
+ (-> usize),
+ // Next is the list of inputs.
+ // The constraint for these inputs means, "when the assembly code is
+ // executed, $rax shall have the value of `number` and $rdi shall have
+ // the value of `arg1`". Any number of input parameters is allowed,
+ // including none.
+ : [number] "{rax}" (number),
+ [arg1] "{rdi}" (arg1),
+ // Next is the list of clobbers. These declare a set of registers whose
+ // values will not be preserved by the execution of this assembly code.
+ // These do not include output or input registers. The special clobber
+ // value of "memory" means that the assembly writes to arbitrary undeclared
+ // memory locations - not only the memory pointed to by a declared indirect
+ // output. In this example we list $rcx and $r11 because it is known the
+ // kernel syscall does not preserve these registers.
+ : "rcx", "r11"
+ );
+}
+
+
+ For x86 and x86_64 targets, the syntax is AT&T syntax, rather than the more
+ popular Intel syntax. This is due to technical constraints; assembly parsing is
+ provided by LLVM and its support for Intel syntax is buggy and not well tested.
+
+
+ Some day Zig may have its own assembler. This would allow it to integrate more seamlessly
+ into the language, as well as be compatible with the popular NASM syntax. This documentation
+ section will be updated before 1.0.0 is released, with a conclusive statement about the status
+ of AT&T vs Intel/NASM syntax.
+
+ Output constraints are still considered to be unstable in Zig, and
+ so
+ LLVM documentation
+ and
+ GCC documentation
+ must be used to understand the semantics.
+
+
+ Note that some breaking changes to output constraints are planned with
+ issue #215.
+
+ Input constraints are still considered to be unstable in Zig, and
+ so
+ LLVM documentation
+ and
+ GCC documentation
+ must be used to understand the semantics.
+
+
+ Note that some breaking changes to input constraints are planned with
+ issue #215.
+
+ Clobbers are the set of registers whose values will not be preserved by the execution of
+ the assembly code. These do not include output or input registers. The special clobber
+ value of "memory" means that the assembly causes writes to
+ arbitrary undeclared memory locations - not only the memory pointed to by a declared
+ indirect output.
+
+
+ Failure to declare the full set of clobbers for a given inline assembly
+ expression is unchecked Illegal Behavior.
+
+ When an assembly expression occurs in a container level comptime block, this is
+ global assembly.
+
+
+ This kind of assembly has different rules than inline assembly. First, volatile
+ is not valid because all global assembly is unconditionally included.
+ Second, there are no inputs, outputs, or clobbers. All global assembly is concatenated
+ verbatim into one long string and assembled together. There are no template substitution rules regarding
+ % as there are in inline assembly expressions.
+
+ Builtin functions are provided by the compiler and are prefixed with @.
+ The comptime keyword on a parameter means that the parameter must be known
+ at compile time.
+
+ Converts a pointer from one address space to another. The new address space is inferred
+ based on the result type. Depending on the current target and address spaces, this cast
+ may be a no-op, a complex operation, or illegal. If the cast is legal, then the resulting
+ pointer points to the same memory location as the pointer operand. It is always valid to
+ cast a pointer between the same address spaces.
+
+ This function returns the number of bytes that this type should be aligned to
+ for the current target to match the C ABI. When the child type of a pointer has
+ this alignment, the alignment can be omitted from the type.
+
+ Performs Type Coercion. This cast is allowed when the conversion is unambiguous and safe,
+ and is the preferred way to convert between types, whenever possible.
+
+ Converts a value of one type to another type. The return type is the
+ inferred result type.
+
+
+ Asserts that @sizeOf(@TypeOf(value)) == @sizeOf(DestType).
+
+
+ Asserts that @typeInfo(DestType) != .pointer. Use @ptrCast or @ptrFromInt if you need this.
+
+
+ Can be used for these things for example:
+
+
+
Convert f32 to u32 bits
+
Convert i32 to u32 preserving twos complement
+
+
+ Works at compile-time if value is known at compile time. It's a compile error to bitcast a value of undefined layout; this means that, besides the restriction from types which possess dedicated casting builtins (enums, pointers, error sets), bare structs, error unions, slices, optionals, and any other type without a well-defined memory layout, also cannot be used in this operation.
+
+ Returns the bit offset of a field relative to its containing struct.
+
+
+ For non packed structs, this will always be divisible by 8.
+ For packed structs, non-byte-aligned fields will share a byte offset, but they will have different
+ bit offsets.
+
+ This function returns the number of bits it takes to store T in memory if the type
+ were a field in a packed struct/union.
+ The result is a target-specific compile time constant.
+
+
+ This function measures the size at runtime. For types that are disallowed at runtime, such as
+ comptime_int and type, the result is 0.
+
+ This function inserts a platform-specific debug trap instruction which causes
+ debuggers to break there.
+ Unlike for @trap(), execution may continue after this point if the program is resumed.
+
+
+ This function is only valid within function scope.
+
+ Swaps the byte order of the integer. This converts a big endian integer to a little endian integer,
+ and converts a little endian integer to a big endian integer.
+
+
+ Note that for the purposes of memory layout with respect to endianness, the integer type should be
+ related to the number of bytes reported by @sizeOf bytes. This is demonstrated with
+ u24. @sizeOf(u24) == 4, which means that a
+ u24 stored in memory takes 4 bytes, and those 4 bytes are what are swapped on
+ a little vs big endian system. On the other hand, if T is specified to
+ be u24, then only 3 bytes are reversed.
+
$ zig test test_call_builtin.zig
+1/1 test_call_builtin.test.noinline function call...OK
+All 1 tests passed.
+
+
+
+ @call allows more flexibility than normal function call syntax does. The
+ CallModifier enum is reproduced here:
+
+ builtin.CallModifier struct.zig
pubconst CallModifier = enum {
+ /// Equivalent to function call syntax.
+ auto,
+
+ /// Equivalent to async keyword used with function call syntax.
+ async_kw,
+
+ /// Prevents tail call optimization. This guarantees that the return
+ /// address will point to the callsite, as opposed to the callsite's
+ /// callsite. If the call is otherwise required to be tail-called
+ /// or inlined, a compile error is emitted instead.
+ never_tail,
+
+ /// Guarantees that the call will not be inlined. If the call is
+ /// otherwise required to be inlined, a compile error is emitted instead.
+ never_inline,
+
+ /// Asserts that the function call will not suspend. This allows a
+ /// non-async function to call an async function.
+ no_async,
+
+ /// Guarantees that the call will be generated with tail call optimization.
+ /// If this is not possible, a compile error is emitted instead.
+ always_tail,
+
+ /// Guarantees that the call will be inlined at the callsite.
+ /// If this is not possible, a compile error is emitted instead.
+ always_inline,
+
+ /// Evaluates the call at compile-time. If the call cannot be completed at
+ /// compile-time, a compile error is emitted instead.
+ compile_time,
+};
+ This function parses C code and imports the functions, types, variables,
+ and compatible macro definitions into a new empty struct type, and then
+ returns that type.
+
+
+ expression is interpreted at compile time. The builtin functions
+ @cInclude, @cDefine, and @cUndef work
+ within this expression, appending to a temporary buffer which is then parsed as C code.
+
+
+ Usually you should only have one @cImport in your entire application, because it saves the compiler
+ from invoking clang multiple times, and prevents inline functions from being duplicated.
+
+
+ Reasons for having multiple @cImport expressions would be:
+
+
+
To avoid a symbol collision, for example if foo.h and bar.h both #define CONNECTION_COUNT
+
To analyze the C code with different preprocessor defines
+ Counts the number of most-significant (leading in a big-endian sense) zeroes in an integer - "count leading zeroes".
+
+
+ The return type is an unsigned integer or vector of unsigned integers with the minimum number
+ of bits that can represent the bit count of the integer type.
+
+
+ If operand is zero, @clz returns the bit width
+ of integer type T.
+
+ This function performs a strong atomic compare-and-exchange operation, returning null
+ if the current value is the given expected value. It's the equivalent of this code,
+ except atomic:
+
+ If you are using cmpxchg in a retry loop, @cmpxchgWeak is the better choice, because it can be implemented
+ more efficiently in machine instructions.
+
+
+ T must be a pointer, a bool, a float,
+ an integer or an enum.
+
+
@typeInfo(@TypeOf(ptr)).pointer.alignment must be >= @sizeOf(T).
+
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
+ This function performs a weak atomic compare-and-exchange operation, returning null
+ if the current value is the given expected value. It's the equivalent of this code,
+ except atomic:
+
+ If you are using cmpxchg in a retry loop, the sporadic failure will be no problem, and cmpxchgWeak
+ is the better choice, because it can be implemented more efficiently in machine instructions.
+ However if you need a stronger guarantee, use @cmpxchgStrong.
+
+
+ T must be a pointer, a bool, a float,
+ an integer or an enum.
+
+
@typeInfo(@TypeOf(ptr)).pointer.alignment must be >= @sizeOf(T).
+
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
+ This function, when semantically analyzed, causes a compile error with the
+ message msg.
+
+
+ There are several ways that code avoids being semantically checked, such as
+ using if or switch with compile time constants,
+ and comptime functions.
+
+ This function prints the arguments passed to it at compile-time.
+
+
+ To prevent accidentally leaving compile log statements in a codebase,
+ a compilation error is added to the build, pointing to the compile
+ log statement. This error prevents code from being generated, but
+ does not otherwise interfere with analysis.
+
+
+ This function can be used to do "printf debugging" on
+ compile-time executing code.
+
+ Counts the number of least-significant (trailing in a big-endian sense) zeroes in an integer - "count trailing zeroes".
+
+
+ The return type is an unsigned integer or vector of unsigned integers with the minimum number
+ of bits that can represent the bit count of the integer type.
+
+
+ If operand is zero, @ctz returns
+ the bit width of integer type T.
+
+ Floored division. Rounds toward negative infinity. For unsigned integers it is
+ the same as numerator / denominator. Caller guarantees denominator != 0 and
+ !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
+
+
+
@divFloor(-5, 3) == -2
+
(@divFloor(a, b) * b) + @mod(a, b) == a
+
+
For a function that returns a possible error code, use @import("std").math.divFloor.
+ Truncated division. Rounds toward zero. For unsigned integers it is
+ the same as numerator / denominator. Caller guarantees denominator != 0 and
+ !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
+
+
+
@divTrunc(-5, 3) == -1
+
(@divTrunc(a, b) * b) + @rem(a, b) == a
+
+
For a function that returns a possible error code, use @import("std").math.divTrunc.
+ This function returns a compile time constant pointer to null-terminated,
+ fixed-size array with length equal to the byte count of the file given by
+ path. The contents of the array are the contents of the file.
+ This is equivalent to a string literal
+ with the file contents.
+
+
+ path is absolute or relative to the current file, just like @import.
+
+ Converts an integer into an enum value. The return type is the inferred result type.
+
+
+ Attempting to convert an integer with no corresponding value in the enum invokes
+ safety-checked Illegal Behavior.
+ Note that a non-exhaustive enum has corresponding values for all
+ integers in the enum's integer tag type: the _ value represents all
+ the remaining unnamed integers in the enum's tag type.
+
+ This function returns the string representation of an error. The string representation
+ of error.OutOfMem is "OutOfMem".
+
+
+ If there are no calls to @errorName in an entire application,
+ or all calls have a compile-time known value for err, then no
+ error name table will be generated.
+
+ If the binary is built with error return tracing, and this function is invoked in a
+ function that calls a function with an error or error union return type, returns a
+ stack trace object. Otherwise returns null.
+
+ Converts an error set or error union value from one error set to another error set. The return type is the
+ inferred result type. Attempting to convert an error which is not in the destination error
+ set results in safety-checked Illegal Behavior.
+
Creates a symbol in the output object file which refers to the target of ptr.
+
ptr must point to a global variable or a comptime-known constant.
+
+ This builtin can be called from a comptime block to conditionally export symbols.
+ When ptr points to a function with the C calling convention and
+ options.linkage is .Strong, this is equivalent to
+ the export keyword used on a function:
+
+ Given a pointer to a struct field, returns a pointer to the struct containing that field.
+ The return type (and struct in question) is the inferred result type.
+
+
+ If field_ptr does not point to the field_name field of an instance of
+ the result type, and the result type has ill-defined layout, invokes unchecked Illegal Behavior.
+
+ Convert from one float type to another. This cast is safe, but may cause the
+ numeric value to lose precision. The return type is the inferred result type.
+
+ Converts an integer to the closest floating point representation. The return type is the inferred result type.
+ To convert the other way, use @intFromFloat. This operation is legal
+ for all values of all integer types.
+
+ This function returns the base pointer of the current stack frame.
+
+
+ The implications of this are target-specific and not consistent across all
+ platforms. The frame address may not be available in release mode due to
+ aggressive optimizations.
+
+
+ This function is only valid within function scope.
+
+ Returns whether or not a container has a declaration
+ matching name.
+
+ test_hasDecl_builtin.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+const Foo = struct {
+ nope: i32,
+
+ pubvar blah = "xxx";
+ const hi = 1;
+};
+
+test"@hasDecl" {
+ try expect(@hasDecl(Foo, "blah"));
+
+ // Even though `hi` is private, @hasDecl returns true because this test is
+ // in the same file scope as Foo. It would return false if Foo was declared
+ // in a different file.
+ try expect(@hasDecl(Foo, "hi"));
+
+ // @hasDecl is for declarations; not fields.
+ try expect(!@hasDecl(Foo, "nope"));
+ try expect(!@hasDecl(Foo, "nope1234"));
+}
+ This function finds a zig file corresponding to path and adds it to the build,
+ if it is not already added.
+
+
+ Zig source files are implicitly structs, with a name equal to the file's basename with the extension
+ truncated. @import returns the struct type corresponding to the file.
+
+
+ Declarations which have the pub keyword may be referenced from a different
+ source file than the one they are declared in.
+
+
+ path can be a relative path or it can be the name of a package.
+ If it is a relative path, it is relative to the file that contains the @import
+ function call.
+
+
+ The following packages are always available:
+
+
+
@import("std") - Zig Standard Library
+
@import("builtin") - Target-specific information
+ The command zig build-exe --show-builtin outputs the source to stdout for reference.
+
+
@import("root") - Root source file
+ This is usually src/main.zig but depends on what file is built.
+
+ Returns whether the builtin was run in a comptime context. The result is a compile-time constant.
+
+
+ This can be used to provide alternative, comptime-friendly implementations of functions. It should not be used, for instance, to exclude certain functions from being evaluated at comptime.
+
+ Converts an integer to another integer while keeping the same numerical value.
+ The return type is the inferred result type.
+ Attempting to convert a number which is out of range of the destination type results in
+ safety-checked Illegal Behavior.
+
+ Takes two or more arguments and returns the biggest value included (the maximum). This builtin accepts integers, floats, and vectors of either. In the latter case, the operation is performed element wise.
+
+
+ NaNs are handled as follows: return the biggest non-NaN value included. If all operands are NaN, return NaN.
+
This function copies bytes from one region of memory to another.
+
dest must be a mutable slice, a mutable pointer to an array, or
+ a mutable many-item pointer. It may have any
+ alignment, and it may have any element type.
+
source must be a slice, a pointer to
+ an array, or a many-item pointer. It may
+ have any alignment, and it may have any element type.
+
The source element type must have the same in-memory
+ representation as the dest element type.
+
Similar to for loops, at least one of source and
+ dest must provide a length, and if two lengths are provided,
+ they must be equal.
+ Takes two or more arguments and returns the smallest value included (the minimum). This builtin accepts integers, floats, and vectors of either. In the latter case, the operation is performed element wise.
+
+
+ NaNs are handled as follows: return the smallest non-NaN value included. If all operands are NaN, return NaN.
+
+ This function returns the size of the Wasm memory identified by index as
+ an unsigned value in units of Wasm pages. Note that each Wasm page is 64KB in size.
+
+
+ This function is a low level intrinsic with no safety mechanisms usually useful for allocator
+ designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use
+ something like @import("std").heap.WasmPageAllocator.
+
+ This function increases the size of the Wasm memory identified by index by
+ delta in units of unsigned number of Wasm pages. Note that each Wasm page
+ is 64KB in size. On success, returns previous memory size; on failure, if the allocation fails,
+ returns -1.
+
+
+ This function is a low level intrinsic with no safety mechanisms usually useful for allocator
+ designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use
+ something like @import("std").heap.WasmPageAllocator.
+
+ Modulus division. For unsigned integers this is the same as
+ numerator % denominator. Caller guarantees denominator > 0, otherwise the
+ operation will result in a Remainder Division by Zero when runtime safety checks are enabled.
+
+
+
@mod(-5, 3) == 1
+
(@divFloor(a, b) * b) + @mod(a, b) == a
+
+
For a function that returns an error code, see @import("std").math.mod.
+ Invokes the panic handler function. By default the panic handler function
+ calls the public panic function exposed in the root source file, or
+ if there is not one specified, the std.builtin.default_panic
+ function from std/builtin.zig.
+
+
Generally it is better to use @import("std").debug.panic.
+ However, @panic can be useful for 2 scenarios:
+
+
+
From library code, calling the programmer's panic function if they exposed one in the root source file.
+
When mixing C and Zig code, calling the canonical panic implementation across multiple .o files.
+ Counts the number of bits set in an integer - "population count".
+
+
+ The return type is an unsigned integer or vector of unsigned integers with the minimum number
+ of bits that can represent the bit count of the integer type.
+
+ This builtin tells the compiler to emit a prefetch instruction if supported by the
+ target CPU. If the target CPU does not support the requested prefetch instruction,
+ this builtin is a no-op. This function has no effect on the behavior of the program,
+ only on the performance characteristics.
+
+
+ The ptr argument may be any pointer type and determines the memory
+ address to prefetch. This function does not dereference the pointer, it is perfectly legal
+ to pass a pointer to invalid memory to this function and no Illegal Behavior will result.
+
+
PrefetchOptions can be found with @import("std").builtin.PrefetchOptions.
+ Converts an integer to a pointer. The return type is the inferred result type.
+ To convert the other way, use @intFromPtr. Casting an address of 0 to a destination type
+ which in not optional and does not have the allowzero attribute will result in a
+ Pointer Cast Invalid Null panic when runtime safety checks are enabled.
+
+
+ If the destination pointer type does not allow address zero and address
+ is zero, this invokes safety-checked Illegal Behavior.
+
+ Remainder division. For unsigned integers this is the same as
+ numerator % denominator. Caller guarantees denominator > 0, otherwise the
+ operation will result in a Remainder Division by Zero when runtime safety checks are enabled.
+
+
+
@rem(-5, 3) == -2
+
(@divTrunc(a, b) * b) + @rem(a, b) == a
+
+
For a function that returns an error code, see @import("std").math.rem.
+ This function returns the address of the next machine code instruction that will be executed
+ when the current function returns.
+
+
+ The implications of this are target-specific and not consistent across
+ all platforms.
+
+
+ This function is only valid within function scope. If the function gets inlined into
+ a calling function, the returned address will apply to the calling function.
+
+ Selects values element-wise from a or b based on pred. If pred[i] is true, the corresponding element in the result will be a[i] and otherwise b[i].
+
+ Increase the maximum number of backwards branches that compile-time code
+ execution can use before giving up and making a compile error.
+
+
+ If the new_quota is smaller than the default quota (1000) or
+ a previously explicitly set quota, it is ignored.
+
+
+ Example:
+
+ test_without_setEvalBranchQuota_builtin.zig
test"foo" {
+ comptime {
+ var i = 0;
+ while (i < 1001) : (i += 1) {}
+ }
+}
Shell
$ zig test test_without_setEvalBranchQuota_builtin.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: error: evaluation exceeded 1000 backwards branches
+ while (i < 1001) : (i += 1) {}
+ ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: note: use @setEvalBranchQuota() to raise the branch limit from 1000
+
+
+
+
Now we use @setEvalBranchQuota:
+ test_setEvalBranchQuota_builtin.zig
test"foo" {
+ comptime {
+ @setEvalBranchQuota(1001);
+ var i = 0;
+ while (i < 1001) : (i += 1) {}
+ }
+}
+ Optimized - Floating point operations may do all of the following:
+
+
Assume the arguments and result are not NaN. Optimizations are required to retain legal behavior over NaNs, but the value of the result is undefined.
+
Assume the arguments and result are not +/-Inf. Optimizations are required to retain legal behavior over +/-Inf, but the value of the result is undefined.
+
Treat the sign of a zero argument or result as insignificant.
+
Use the reciprocal of an argument rather than perform division.
+
Perform floating-point contraction (e.g. fusing a multiply followed by an addition into a fused multiply-add).
+
Perform algebraically equivalent transformations that may change results in floating point (e.g. reassociate).
+
+ This is equivalent to -ffast-math in GCC.
+
+
+
+ The floating point mode is inherited by child scopes, and can be overridden in any scope.
+ You can set the floating point mode in a struct or module scope by using a comptime block.
+
+
FloatMode can be found with @import("std").builtin.FloatMode.
+ Sets whether runtime safety checks are enabled for the scope that contains the function call.
+
+ test_setRuntimeSafety_builtin.zig
test"@setRuntimeSafety" {
+ // The builtin applies to the scope that it is called in. So here, integer overflow
+ // will not be caught in ReleaseFast and ReleaseSmall modes:
+ // var x: u8 = 255;
+ // x += 1; // Unchecked Illegal Behavior in ReleaseFast/ReleaseSmall modes.
+ {
+ // However this block has safety enabled, so safety checks happen here,
+ // even in ReleaseFast and ReleaseSmall modes.
+ @setRuntimeSafety(true);
+ var x: u8 = 255;
+ x += 1;
+
+ {
+ // The value can be overridden at any scope. So here integer overflow
+ // would not be caught in any build mode.
+ @setRuntimeSafety(false);
+ // var x: u8 = 255;
+ // x += 1; // Unchecked Illegal Behavior in all build modes.
+ }
+ }
+}
Shell
$ zig test test_setRuntimeSafety_builtin.zig -OReleaseFast
+1/1 test_setRuntimeSafety_builtin.test.@setRuntimeSafety...thread 1083480 panic: integer overflow
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_setRuntimeSafety_builtin.zig:11:11: 0x100a6a8 in test.@setRuntimeSafety (test)
+ x += 1;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x1031ad8 in main (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x103028d in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x102ff7d in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/785fdecfc68325a878131d6159c06409/test --seed=0x882a3448
+
+
+
Note: it is planned to replace
+ @setRuntimeSafety with @optimizeFor
+ Performs the left shift operation (<<).
+ For unsigned integers, the result is undefined if any 1 bits
+ are shifted out. For signed integers, the result is undefined if
+ any bits that disagree with the resultant sign bit are shifted out.
+
+
+ The type of shift_amt is an unsigned integer with log2(@typeInfo(T).int.bits) bits.
+ This is because shift_amt >= @typeInfo(T).int.bits triggers safety-checked Illegal Behavior.
+
+
+ comptime_int is modeled as an integer with an infinite number of bits,
+ meaning that in such case, @shlExact always produces a result and
+ cannot produce a compile error.
+
+ Performs a << b and returns a tuple with the result and a possible overflow bit.
+
+
+ The type of shift_amt is an unsigned integer with log2(@typeInfo(@TypeOf(a)).int.bits) bits.
+ This is because shift_amt >= @typeInfo(@TypeOf(a)).int.bits triggers safety-checked Illegal Behavior.
+
+ Performs the right shift operation (>>). Caller guarantees
+ that the shift will not shift any 1 bits out.
+
+
+ The type of shift_amt is an unsigned integer with log2(@typeInfo(T).int.bits) bits.
+ This is because shift_amt >= @typeInfo(T).int.bits triggers safety-checked Illegal Behavior.
+
+ Constructs a new vector by selecting elements from a and
+ b based on mask.
+
+
+ Each element in mask selects an element from either a or
+ b. Positive numbers select from a starting at 0.
+ Negative values select from b, starting at -1 and going down.
+ It is recommended to use the ~ operator for indexes from b
+ so that both indexes can start from 0 (i.e. ~@as(i32, 0) is
+ -1).
+
+
+ For each element of mask, if it or the selected value from
+ a or b is undefined,
+ then the resulting element is undefined.
+
+
+ a_len and b_len may differ in length. Out-of-bounds element
+ indexes in mask result in compile errors.
+
+
+ If a or b is undefined, it
+ is equivalent to a vector of all undefined with the same length as the other vector.
+ If both vectors are undefined, @shuffle returns
+ a vector with all elements undefined.
+
+
+ E must be an integer, float,
+ pointer, or bool. The mask may be any vector length, and its
+ length determines the result length.
+
+ test_shuffle_builtin.zig
const std = @import("std");
+const expect = std.testing.expect;
+
+test"vector @shuffle" {
+ const a = @Vector(7, u8){ 'o', 'l', 'h', 'e', 'r', 'z', 'w' };
+ const b = @Vector(4, u8){ 'w', 'd', '!', 'x' };
+
+ // To shuffle within a single vector, pass undefined as the second argument.
+ // Notice that we can re-order, duplicate, or omit elements of the input vector
+ const mask1 = @Vector(5, i32){ 2, 3, 1, 1, 0 };
+ const res1: @Vector(5, u8) = @shuffle(u8, a, undefined, mask1);
+ try expect(std.mem.eql(u8, &@as([5]u8, res1), "hello"));
+
+ // Combining two vectors
+ const mask2 = @Vector(6, i32){ -1, 0, 4, 1, -2, -3 };
+ const res2: @Vector(6, u8) = @shuffle(u8, a, b, mask2);
+ try expect(std.mem.eql(u8, &@as([6]u8, res2), "world!"));
+}
+ This function returns the number of bytes it takes to store T in memory.
+ The result is a target-specific compile time constant.
+
+
+ This size may contain padding bytes. If there were two consecutive T in memory, the padding would be the offset
+ in bytes between element at index 0 and the element at index 1. For integer,
+ consider whether you want to use @sizeOf(T) or
+ @typeInfo(T).int.bits.
+
+
+ This function measures the size at runtime. For types that are disallowed at runtime, such as
+ comptime_int and type, the result is 0.
+
@reduce(comptime op: std.builtin.ReduceOp, value: anytype) E
+
+ Transforms a vector into a scalar value (of type E)
+ by performing a sequential horizontal reduction of its elements using the
+ specified operator op.
+
+
+ Not every operator is available for every vector element type:
+
.And, .Or,
+ .Xor are additionally available for
+ bool vectors,
+
.Min, .Max,
+ .Add, .Mul are
+ additionally available for floating point vectors,
+
+
+ Note that .Add and .Mul
+ reductions on integral types are wrapping; when applied on floating point
+ types the operation associativity is preserved, unless the float mode is
+ set to Optimized.
+
+ Returns the absolute value of an integer or a floating point number. Uses a dedicated hardware instruction
+ when available.
+
+ The return type is always an unsigned integer of the same bit width as the operand if the operand is an integer.
+ Unsigned integer operands are supported. The builtin cannot overflow for signed integer operands.
+
+ Rounds the given floating point number to the nearest integer. If two integers are equally close, rounds away from zero.
+ Uses a dedicated hardware instruction when available.
+
+ Returns the innermost struct, enum, or union that this function call is inside.
+ This can be useful for an anonymous struct that needs to refer to itself:
+
+ This function inserts a platform-specific trap/jam instruction which can be used to exit the program abnormally.
+ This may be implemented by explicitly emitting an invalid instruction which may cause an illegal instruction exception of some sort.
+ Unlike for @breakpoint(), execution does not continue after this point.
+
+
+ Outside function scope, this builtin causes a compile error.
+
+ This function truncates bits from an integer type, resulting in a smaller
+ or same-sized integer type. The return type is the inferred result type.
+
+
+ This function always truncates the significant bits of the integer, regardless
+ of endianness on the target platform.
+
+
+ Calling @truncate on a number out of range of the destination type is well defined and working code:
+
+ Type information of structs, unions, enums, and
+ error sets has fields which are guaranteed to be in the same
+ order as appearance in the source file.
+
+
+ Type information of structs, unions, enums, and
+ opaques has declarations, which are also guaranteed to be in the same
+ order as appearance in the source file.
+
+ This function returns the string representation of a type, as
+ an array. It is equivalent to a string literal of the type name.
+ The returned type name is fully qualified with the parent namespace included
+ as part of the type name with a series of dots.
+
+ @TypeOf is a special builtin function that takes any (non-zero) number of expressions
+ as parameters and returns the type of the result, using Peer Type Resolution.
+
+
+ The expressions are evaluated, however they are guaranteed to have no runtime side-effects:
+
+ Returns the index of the work item in the work group in dimension dimension. This function returns values between 0 (inclusive) and @workGroupSize(dimension) (exclusive).
+
The overhead of Async Functions becomes equivalent to function call overhead.
+
The @import("builtin").single_threaded becomes true
+ and therefore various userland APIs which read this variable become more efficient.
+ For example std.Mutex becomes
+ an empty data structure and all of its functions become no-ops.
+ Many operations in Zig trigger what is known as "Illegal Behavior" (IB). If Illegal Behavior is detected at
+ compile-time, Zig emits a compile error and refuses to continue. Otherwise, when Illegal Behavior is not caught
+ at compile-time, it falls into one of two categories.
+
+
+ Some Illegal Behavior is safety-checked: this means that the compiler will insert "safety checks"
+ anywhere that the Illegal Behavior may occur at runtime, to determine whether it is about to happen. If it
+ is, the safety check "fails", which triggers a panic.
+
+
+ All other Illegal Behavior is unchecked, meaning the compiler is unable to insert safety checks for
+ it. If Unchecked Illegal Behavior is invoked at runtime, anything can happen: usually that will be some kind of
+ crash, but the optimizer is free to make Unchecked Illegal Behavior do anything, such as calling arbitrary functions
+ or clobbering arbitrary data. This is similar to the concept of "undefined behavior" in some other languages. Note that
+ Unchecked Illegal Behavior still always results in a compile error if evaluated at comptime, because the Zig
+ compiler is able to perform more sophisticated checks at compile-time than at runtime.
+
+
+ Most Illegal Behavior is safety-checked. However, to facilitate optimizations, safety checks are disabled by default
+ in the ReleaseFast and ReleaseSmall optimization modes. Safety checks can also be enabled or disabled
+ on a per-block basis, overriding the default for the current optimization mode, using @setRuntimeSafety. When
+ safety checks are disabled, Safety-Checked Illegal Behavior behaves like Unchecked Illegal Behavior; that is, any behavior
+ may result from invoking it.
+
+
+ When a safety check fails, Zig's default panic handler crashes with a stack trace, like this:
+
+ test_illegal_behavior.zig
test"safety check" {
+ unreachable;
+}
Shell
$ zig test test_illegal_behavior.zig
+1/1 test_illegal_behavior.test.safety check...thread 1083790 panic: reached unreachable code
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_illegal_behavior.zig:2:5: 0x10485f8 in test.safety check (test)
+ unreachable;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10ee8f9 in mainTerminal (test)
+ if (test_fn.func()) |_| {
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10e6c9d in main (test)
+ return mainTerminal();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e6112 in posixCallMainAndExit (test)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e5ced in _start (test)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/2b8c5b0a72f5884998aeae5b01332698/test --seed=0x6ebca125
+
$ zig test test_comptime_overflow.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_overflow.zig:3:10: error: overflow of integer type 'u8' with value '256'
+ byte += 1;
+ ~~~~~^~~~
+
+
$ zig test test_comptime_division_by_zero.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_division_by_zero.zig:4:19: error: division by zero here causes undefined behavior
+ const c = a / b;
+ ^
+
+
+
+
At runtime:
+ runtime_division_by_zero.zig
const std = @import("std");
+
+pubfnmain() void {
+ var a: u32 = 1;
+ var b: u32 = 0;
+ _ = .{ &a, &b };
+ const c = a / b;
+ std.debug.print("value: {}\n", .{c});
+}
Shell
$ zig build-exe runtime_division_by_zero.zig
+$ ./runtime_division_by_zero
+thread 1080185 panic: division by zero
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_division_by_zero.zig:7:17: 0x10de2ea in main (runtime_division_by_zero)
+ const c = a / b;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10ddc92 in posixCallMainAndExit (runtime_division_by_zero)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10dd86d in _start (runtime_division_by_zero)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+(process terminated by signal)
+
$ zig test test_comptime_remainder_division_by_zero.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_remainder_division_by_zero.zig:4:19: error: division by zero here causes undefined behavior
+ const c = a % b;
+ ^
+
+
+
+
At runtime:
+ runtime_remainder_division_by_zero.zig
const std = @import("std");
+
+pubfnmain() void {
+ var a: u32 = 10;
+ var b: u32 = 0;
+ _ = .{ &a, &b };
+ const c = a % b;
+ std.debug.print("value: {}\n", .{c});
+}
Shell
$ zig build-exe runtime_remainder_division_by_zero.zig
+$ ./runtime_remainder_division_by_zero
+thread 1086160 panic: division by zero
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_remainder_division_by_zero.zig:7:17: 0x10de2ea in main (runtime_remainder_division_by_zero)
+ const c = a % b;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10ddc92 in posixCallMainAndExit (runtime_remainder_division_by_zero)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10dd86d in _start (runtime_remainder_division_by_zero)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+(process terminated by signal)
+
$ zig test test_comptime_invalid_error_set_cast.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_error_set_cast.zig:10:19: error: 'error.B' not a member of error set 'error{A,C}'
+ _ = @as(Set2, @errorCast(Set1.B));
+ ^~~~~~~~~~~~~~~~~~
+
+
comptime {
+ var f = Foo{ .int = 42 };
+ f.float = 12.34;
+}
+
+const Foo = union {
+ float: f32,
+ int: u32,
+};
Shell
$ zig test test_comptime_wrong_union_field_access.zig
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_wrong_union_field_access.zig:3:6: error: access of union field 'float' while field 'int' is active
+ f.float = 12.34;
+ ~^~~~~~
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_wrong_union_field_access.zig:6:13: note: union declared here
+const Foo = union {
+ ^~~~~
+
+
$ zig build-exe runtime_wrong_union_field_access.zig
+$ ./runtime_wrong_union_field_access
+thread 1085377 panic: access of union field 'float' while field 'int' is active
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_wrong_union_field_access.zig:14:6: 0x10e43c8 in bar (runtime_wrong_union_field_access)
+ f.float = 12.34;
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_wrong_union_field_access.zig:10:8: 0x10e3b1c in main (runtime_wrong_union_field_access)
+ bar(&f);
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:651:22: 0x10e3502 in posixCallMainAndExit (runtime_wrong_union_field_access)
+ root.main();
+ ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e30dd in _start (runtime_wrong_union_field_access)
+ asm volatile (switch (native_arch) {
+ ^
+???:?:?: 0x0 in ??? (???)
+(process terminated by signal)
+
+
+
+ This safety is not available for extern or packed unions.
+
+
+ To change the active field of a union, assign the entire union, like this:
+
+ This happens when casting a pointer with the address 0 to a pointer which may not have the address 0.
+ For example, C Pointers, Optional Pointers, and allowzero pointers
+ allow address zero, but normal Pointers do not.
+
+ The Zig language performs no memory management on behalf of the programmer. This is
+ why Zig has no runtime, and why Zig code works seamlessly in so many environments,
+ including real-time software, operating system kernels, embedded devices, and
+ low latency servers. As a consequence, Zig programmers must always be able to answer
+ the question:
+
+ Like Zig, the C programming language has manual memory management. However, unlike Zig,
+ C has a default allocator - malloc, realloc, and free.
+ When linking against libc, Zig exposes this allocator with std.heap.c_allocator.
+ However, by convention, there is no default allocator in Zig. Instead, functions which need to
+ allocate accept an Allocator parameter. Likewise, data structures such as
+ std.ArrayList accept an Allocator parameter in
+ their initialization functions:
+
$ zig test test_allocator.zig
+1/1 test_allocator.test.using an allocator...OK
+All 1 tests passed.
+
+
+
+ In the above example, 100 bytes of stack memory are used to initialize a
+ FixedBufferAllocator, which is then passed to a function.
+ As a convenience there is a global FixedBufferAllocator
+ available for quick tests at std.testing.allocator,
+ which will also perform basic leak detection.
+
+
+ Zig has a general purpose allocator available to be imported
+ with std.heap.GeneralPurposeAllocator. However, it is still recommended to
+ follow the Choosing an Allocator guide.
+
What allocator to use depends on a number of factors. Here is a flow chart to help you decide:
+
+
+
+ Are you making a library? In this case, best to accept an Allocator
+ as a parameter and allow your library's users to decide what allocator to use.
+
+
Are you linking libc? In this case, std.heap.c_allocator is likely
+ the right choice, at least for your main allocator.
+
+ Need to use the same allocator in multiple threads? Use one of your choice
+ wrapped around std.heap.ThreadSafeAllocator
+
+
+ Is the maximum number of bytes that you will need bounded by a number known at
+ comptime? In this case, use std.heap.FixedBufferAllocator.
+
+
+ Is your program a command line application which runs from start to end without any fundamental
+ cyclical pattern (such as a video game main loop, or a web server request handler),
+ such that it would make sense to free everything at once at the end?
+ In this case, it is recommended to follow this pattern:
+ cli_allocation.zig
+
+ When using this kind of allocator, there is no need to free anything manually. Everything
+ gets freed at once with the call to arena.deinit().
+
+
+ Are the allocations part of a cyclical pattern such as a video game main loop, or a web
+ server request handler? If the allocations can all be freed at once, at the end of the cycle,
+ for example once the video game frame has been fully rendered, or the web server request has
+ been served, then std.heap.ArenaAllocator is a great candidate. As
+ demonstrated in the previous bullet point, this allows you to free entire arenas at once.
+ Note also that if an upper bound of memory can be established, then
+ std.heap.FixedBufferAllocator can be used as a further optimization.
+
+
+ Are you writing a test, and you want to make sure error.OutOfMemory
+ is handled correctly? In this case, use std.testing.FailingAllocator.
+
+
+ Are you writing a test? In this case, use std.testing.allocator.
+
+
+ Finally, if none of the above apply, you need a general purpose allocator.
+ Zig's general purpose allocator is available as a function that takes a comptime
+ struct of configuration options and returns a type.
+ Generally, you will set up one std.heap.GeneralPurposeAllocator in
+ your main function, and then pass it or sub-allocators around to various parts of your
+ application.
+
String literals such as "hello" are in the global constant data section.
+ This is why it is an error to pass a string literal to a mutable slice, like this:
+
$ zig test test_string_literal_to_const_slice.zig
+1/1 test_string_literal_to_const_slice.test.string literal to constant slice...OK
+All 1 tests passed.
+
+
+
+ Just like string literals, const declarations, when the value is known at comptime,
+ are stored in the global constant data section. Also Compile Time Variables are stored
+ in the global constant data section.
+
+
+ var declarations inside functions are stored in the function's stack frame. Once a function returns,
+ any Pointers to variables in the function's stack frame become invalid references, and
+ dereferencing them becomes unchecked Illegal Behavior.
+
+
+ var declarations at the top level or in struct declarations are stored in the global
+ data section.
+
+
+ The location of memory allocated with allocator.alloc or
+ allocator.create is determined by the allocator's implementation.
+
Zig programmers can implement their own allocators by fulfilling the Allocator interface.
+ In order to do this one must read carefully the documentation comments in std/mem.zig and
+ then supply a allocFn and a resizeFn.
+
+
+ There are many example allocators to look at for inspiration. Look at std/heap.zig and
+ std.heap.GeneralPurposeAllocator.
+
+ Many programming languages choose to handle the possibility of heap allocation failure by
+ unconditionally crashing. By convention, Zig programmers do not consider this to be a
+ satisfactory solution. Instead, error.OutOfMemory represents
+ heap allocation failure, and Zig libraries return this error code whenever heap allocation
+ failure prevented an operation from completing successfully.
+
+
+ Some have argued that because some operating systems such as Linux have memory overcommit enabled by
+ default, it is pointless to handle heap allocation failure. There are many problems with this reasoning:
+
+
+
Only some operating systems have an overcommit feature.
+
+
Linux has it enabled by default, but it is configurable.
+
Windows does not overcommit.
+
Embedded systems do not have overcommit.
+
Hobby operating systems may or may not have overcommit.
+
+
+
+ For real-time systems, not only is there no overcommit, but typically the maximum amount
+ of memory per application is determined ahead of time.
+
+
+ When writing a library, one of the main goals is code reuse. By making code handle
+ allocation failure correctly, a library becomes eligible to be reused in
+ more contexts.
+
+
+ Although some software has grown to depend on overcommit being enabled, its existence
+ is the source of countless user experience disasters. When a system with overcommit enabled,
+ such as Linux on default settings, comes close to memory exhaustion, the system locks up
+ and becomes unusable. At this point, the OOM Killer selects an application to kill
+ based on heuristics. This non-deterministic decision often results in an important process
+ being killed, and often fails to return the system back to working order.
+
+ The short summary is that currently recursion works normally as you would expect. Although Zig code
+ is not yet protected from stack overflow, it is planned that a future version of Zig will provide
+ such protection, with some degree of cooperation from Zig code required.
+
+ It is the Zig programmer's responsibility to ensure that a pointer is not
+ accessed when the memory pointed to is no longer available. Note that a slice
+ is a form of pointer, in that it references other memory.
+
+
+ In order to prevent bugs, there are some helpful conventions to follow when dealing with pointers.
+ In general, when a function returns a pointer, the documentation for the function should explain
+ who "owns" the pointer. This concept helps the programmer decide when it is appropriate, if ever,
+ to free the pointer.
+
+
+ For example, the function's documentation may say "caller owns the returned memory", in which case
+ the code that calls the function must have a plan for when to free that memory. Probably in this situation,
+ the function will accept an Allocator parameter.
+
+
+ Sometimes the lifetime of a pointer may be more complicated. For example, the
+ std.ArrayList(T).items slice has a lifetime that remains
+ valid until the next time the list is resized, such as by appending new elements.
+
+
+ The API documentation for functions and data structures should take great care to explain
+ the ownership and lifetime semantics of pointers. Ownership determines whose responsibility it
+ is to free the memory referenced by the pointer, and lifetime determines the point at which
+ the memory becomes inaccessible (lest Illegal Behavior occur).
+
+ Compile variables are accessible by importing the "builtin" package,
+ which the compiler makes available to every Zig source file. It contains
+ compile-time constants such as the current target, endianness, and release mode.
+
+ A Zig compilation is separated into modules. Each module is a collection of Zig source files,
+ one of which is the module's root source file. Each module can depend on any number of
+ other modules, forming a directed graph (dependency loops between modules are allowed). If module A
+ depends on module B, then any Zig source file in module A can import the root source file of
+ module B using @import with the module's name. In essence, a module acts as an
+ alias to import a Zig source file (which might exist in a completely separate part of the filesystem).
+
+
+ A simple Zig program compiled with zig build-exe has two key modules: the one containing your
+ code, known as the "main" or "root" module, and the standard library. Your module depends on
+ the standard library module under the name "std", which is what allows you to write
+ @import("std")! In fact, every single module in a Zig compilation — including
+ the standard library itself — implicitly depends on the standard library module under the name "std".
+
+
+ The "root module" (the one provided by you in the zig build-exe example) has a special
+ property. Like the standard library, it is implicitly made available to all modules (including itself),
+ this time under the name "root". So, @import("root") will always be equivalent to
+ @import of your "main" source file (often, but not necessarily, named
+ main.zig).
+
+ Every Zig source file is implicitly a struct declaration; you can imagine that
+ the file's contents are literally surrounded by struct { ... }. This means that
+ as well as declarations, the top level of a file is permitted to contain fields:
+
+ TopLevelFields.zig
//! Because this file contains fields, it is a type which is intended to be instantiated, and so
+//! is named in TitleCase instead of snake_case by convention.
+
+foo: u32,
+bar: u64,
+
+/// `@This()` can be used to refer to this struct type. In files with fields, it is quite common to
+/// name the type here, so it can be easily referenced by other declarations in this file.
+const TopLevelFields = @This();
+
+pubfninit(val: u32) TopLevelFields {
+ return .{
+ .foo = val,
+ .bar = val * 10,
+ };
+}
+
+ Such files can be instantiated just like any other struct type. A file's "root
+ struct type" can be referred to within that file using @This.
+
+ Zig places importance on the concept of whether any piece of code is semantically analyzed; in
+ essence, whether the compiler "looks at" it. What code is analyzed is based on what files and
+ declarations are "discovered" from a certain point. This process of "discovery" is based on a simple set
+ of recursive rules:
+
+
+
If a call to @import is analyzed, the file being imported is analyzed.
+
If a type (including a file) is analyzed, all comptime, usingnamespace, and export declarations within it are analyzed.
+
If a type (including a file) is analyzed, and the compilation is for a test, and the module the type is within is the root module of the compilation, then all test declarations within it are also analyzed.
+
If a reference to a named declaration (i.e. a usage of it) is analyzed, the declaration being referenced is analyzed. Declarations are order-independent, so this reference may be above or below the declaration being referenced, or even in another file entirely.
+
+
+ That's it! Those rules define how Zig files and declarations are discovered. All that remains is to
+ understand where this process starts.
+
+
+ The answer to that is the root of the standard library: every Zig compilation begins by analyzing the
+ file lib/std/std.zig. This file contains a comptime declaration
+ which imports lib/std/start.zig, and that file in turn uses
+ @import("root") to reference the "root module"; so, the file you provide as your
+ main module's root source file is effectively also a root, because the standard library will always
+ reference it.
+
+
+ It is often desirable to make sure that certain declarations — particularly test
+ or export declarations — are discovered. Based on the above rules, a common
+ strategy for this is to use @import within a comptime or
+ test block:
+
+ force_file_discovery.zig
comptime {
+ // This will ensure that the file 'api.zig' is always discovered (as long as this file is discovered).
+ // It is useful if 'api.zig' contains important exported declarations.
+ _ = @import("api.zig");
+
+ // We could also have a file which contains declarations we only want to export depending on a comptime
+ // condition. In that case, we can use an `if` statement here:
+ if (builtin.os.tag == .windows) {
+ _ = @import("windows_api.zig");
+ }
+}
+
+test {
+ // This will ensure that the file 'tests.zig' is always discovered (as long as this file is discovered),
+ // if this compilation is a test. It is useful if 'tests.zig' contains tests we want to ensure are run.
+ _ = @import("tests.zig");
+
+ // We could also have a file which contains tests we only want to run depending on a comptime condition.
+ // In that case, we can use an `if` statement here:
+ if (builtin.os.tag == .windows) {
+ _ = @import("windows_tests.zig");
+ }
+}
+
+const builtin = @import("builtin");
+ Because the root module's root source file is always accessible using
+ @import("root"), is is sometimes used by libraries — including the Zig Standard
+ Library — as a place for the program to expose some "global" information to that library. The Zig
+ Standard Library will look for several declarations in this file.
+
+ When building an executable, the most important thing to be looked up in this file is the program's
+ entry point. Most commonly, this is a function named main, which
+ std.start will call just after performing important initialization work.
+
+
+ Alternatively, the presence of a declaration named _start (for instance,
+ pubconst _start = {};) will disable the default std.start
+ logic, allowing your root source file to export a low-level entry point as needed.
+
+ entry_point.zig
/// `std.start` imports this file using `@import("root")`, and uses this declaration as the program's
+/// user-provided entry point. It can return any of the following types:
+/// * `void`
+/// * `E!void`, for any error set `E`
+/// * `u8`
+/// * `E!u8`, for any error set `E`
+/// Returning a `void` value from this function will exit with code 0.
+/// Returning a `u8` value from this function will exit with the given status code.
+/// Returning an error value from this function will print an Error Return Trace and exit with code 1.
+pubfnmain() void {
+ std.debug.print("Hello, World!\n", .{});
+}
+
+// If uncommented, this declaration would suppress the usual std.start logic, causing
+// the `main` declaration above to be ignored.
+//pub const _start = {};
+
+const std = @import("std");
+ std.start may also use other entry point declarations in certain situations, such
+ as wWinMain or EfiMain. Refer to the
+ lib/std/start.zig logic for details of these declarations.
+
+ The standard library also looks for a declaration in the root module's root source file named
+ std_options. If present, this declaration is expected to be a struct of type
+ std.Options, and allows the program to customize some standard library
+ functionality, such as the std.log implementation.
+
+ std_options.zig
/// The presence of this declaration allows the program to override certain behaviors of the standard library.
+/// For a full list of available options, see the documentation for `std.Options`.
+pubconst std_options: std.Options = .{
+ // By default, in safe build modes, the standard library will attach a segfault handler to the program to
+ // print a helpful stack trace if a segmentation fault occurs. Here, we can disable this, or even enable
+ // it in unsafe build modes.
+ .enable_segfault_handler = true,
+ // This is the logging function used by `std.log`.
+ .logFn = myLogFn,
+};
+
+fnmyLogFn(
+ comptime level: std.log.Level,
+ comptime scope: @Type(.enum_literal),
+ comptime format: []constu8,
+ args: anytype,
+) void {
+ // We could do anything we want here!
+ // ...but actually, let's just call the default implementation.
+ std.log.defaultLog(level, scope, format, args);
+}
+
+const std = @import("std");
+ The Zig Standard Library looks for a declaration named panic in the root module's
+ root source file. If present, it is expected to be a namespace (container type) with declarations
+ providing different panic handlers.
+
+
+ See std.debug.simple_panic for a basic implementation of this namespace.
+
+
+ Overriding how the panic handler actually outputs messages, but keeping the formatted safety panics
+ which are enabled by default, can be easily achieved with std.debug.FullPanic:
+
+ The Zig Build System provides a cross-platform, dependency-free way to declare
+ the logic required to build a project. With this system, the logic to build
+ a project is written in a build.zig file, using the Zig Build System API to
+ declare and configure build artifacts and other tasks.
+
+
+ Some examples of tasks the build system can help with:
+
+
+
Performing tasks in parallel and caching the results.
+
Depending on other projects.
+
Providing a package for other projects to depend on.
+
Creating build artifacts by executing the Zig compiler. This includes
+ building Zig source code as well as C and C++ source code.
+
Capturing user-configured options and using those options to configure
+ the build.
+
Surfacing build configuration as comptime values by providing a
+ file that can be imported by Zig code.
+
Caching build artifacts to avoid unnecessarily repeating steps.
+
Executing build artifacts or system-installed tools.
+
Running tests and verifying the output of executing a build artifact matches
+ the expected value.
+
Running zig fmt on a codebase or a subset of it.
+
Custom tasks.
+
+
+ To use the build system, run zig build --help
+ to see a command-line usage help menu. This will include project-specific
+ options that were declared in the build.zig script.
+
+
+ For the time being, the build system documentation is hosted externally:
+ Build System Documentation
+
+ Although Zig is independent of C, and, unlike most other languages, does not depend on libc,
+ Zig acknowledges the importance of interacting with existing C code.
+
+
+ There are a few ways that Zig facilitates C interop.
+
+ The @cImport function takes an expression as a parameter.
+ This expression is evaluated at compile-time and is used to control
+ preprocessor directives and include multiple .h files:
+
+ Zig's C translation capability is available as a CLI tool via zig translate-c.
+ It requires a single filename as an argument. It may also take a set of optional flags that are
+ forwarded to clang. It writes the translated file to stdout.
+
+ -I:
+ Specify a search directory for include files. May be used multiple times. Equivalent to
+
+ clang's -I flag. The current directory is not included by default;
+ use -I. to include it.
+
+ Important! When translating C code with zig translate-c,
+ you must use the same -target triple that you will use when compiling
+ the translated code. In addition, you must ensure that the -cflags used,
+ if any, match the cflags used by code on the target system. Using the incorrect -target
+ or -cflags could result in clang or Zig parse failures, or subtle ABI incompatibilities
+ when linking with C code.
+
@cImport and zig translate-c use the same underlying
+ C translation functionality, so on a technical level they are equivalent. In practice,
+ @cImport is useful as a way to quickly and easily access numeric constants, typedefs,
+ and record types without needing any extra setup. If you need to pass cflags
+ to clang, or if you would like to edit the translated code, it is recommended to use
+ zig translate-c and save the results to a file. Common reasons for editing
+ the generated code include: changing anytype parameters in function-like macros to more
+ specific types; changing [*c]T pointers to [*]T or
+ *T pointers for improved type safety; and
+ enabling or disabling runtime safety within specific functions.
+
+ The C translation feature (whether used via zig translate-c or
+ @cImport) integrates with the Zig caching system. Subsequent runs with
+ the same source file, target, and cflags will use the cache instead of repeatedly translating
+ the same code.
+
+
+ To see where the cached files are stored when compiling code that uses @cImport,
+ use the --verbose-cimport flag:
+
+ cimport.h contains the file to translate (constructed from calls to
+ @cInclude, @cDefine, and @cUndef),
+ cimport.h.d is the list of file dependencies, and
+ cimport.zig contains the translated output.
+
+ Some C constructs cannot be translated to Zig - for example, goto,
+ structs with bitfields, and token-pasting macros. Zig employs demotion to allow translation
+ to continue in the face of non-translatable entities.
+
+
+ Demotion comes in three varieties - opaque, extern, and
+ @compileError.
+
+ C structs and unions that cannot be translated correctly will be translated as opaque{}.
+ Functions that contain opaque types or code constructs that cannot be translated will be demoted
+ to extern declarations.
+
+ Thus, non-translatable types can still be used as pointers, and non-translatable functions
+ can be called so long as the linker is aware of the compiled function.
+
+
+ @compileError is used when top-level definitions (global variables,
+ function prototypes, macros) cannot be translated or demoted. Since Zig uses lazy analysis for
+ top-level declarations, untranslatable entities will not cause a compile error in your code unless
+ you actually use them.
+
+ C Translation makes a best-effort attempt to translate function-like macros into equivalent
+ Zig functions. Since C macros operate at the level of lexical tokens, not all C macros
+ can be translated to Zig. Macros that cannot be translated will be demoted to
+ @compileError. Note that C code which uses macros will be
+ translated without any additional issues (since Zig operates on the pre-processed source
+ with macros expanded). It is merely the macros themselves which may not be translatable to
+ Zig.
+
+
Consider the following example:
+ macro.c
#define MAKELOCAL(NAME, INIT) int NAME = INIT
+int foo(void) {
+ MAKELOCAL(a, 1);
+ MAKELOCAL(b, 2);
+ return a + b;
+}
+ Shell
$ zig translate-c macro.c > macro.zig
+
+ macro.zig
pubexportfnfoo() c_int {
+ var a: c_int = 1;
+ _ = &a;
+ var b: c_int = 2;
+ _ = &b;
+ return a + b;
+}
+pubconst MAKELOCAL = @compileError("unable to translate C expr: unexpected token .Equal"); // macro.c:1:9
+
+
Note that foo was translated correctly despite using a non-translatable
+ macro. MAKELOCAL was demoted to @compileError since
+ it cannot be expressed as a Zig function; this simply means that you cannot directly use
+ MAKELOCAL from Zig.
+
+ This type is to be avoided whenever possible. The only valid reason for using a C pointer is in
+ auto-generated code from translating C code.
+
+
+ When importing C header files, it is ambiguous whether pointers should be translated as
+ single-item pointers (*T) or many-item pointers ([*]T).
+ C pointers are a compromise so that Zig code can utilize translated header files directly.
+
+
[*c]T - C pointer.
+
+
Supports all the syntax of the other two pointer types (*T) and ([*]T).
+
Coerces to other pointer types, as well as Optional Pointers.
+ When a C pointer is coerced to a non-optional pointer, safety-checked
+ Illegal Behavior occurs if the address is 0.
+
+
Allows address 0. On non-freestanding targets, dereferencing address 0 is safety-checked
+ Illegal Behavior. Optional C pointers introduce another bit to keep track of
+ null, just like ?usize. Note that creating an optional C pointer
+ is unnecessary as one can use normal Optional Pointers.
+
Does not support Zig-only pointer attributes such as alignment. Use normal Pointers
+ please!
+
+
When a C pointer is pointing to a single struct (not an array), dereference the C pointer to
+ access the struct's fields or member data. That syntax looks like
+ this:
+
ptr_to_struct.*.struct_member
+
This is comparable to doing -> in C.
+
When a C pointer is pointing to an array of structs, the syntax reverts to this:
+ One of the primary use cases for Zig is exporting a library with the C ABI for other programming languages
+ to call into. The export keyword in front of functions, variables, and types causes them to
+ be part of the library API:
+
For host environments like the web browser and nodejs, build as an executable using the freestanding
+ OS target. Here's an example of running Zig code compiled to WebAssembly with nodejs.
Zig's support for WebAssembly System Interface (WASI) is under active development.
+ Example of using the standard library and reading command line arguments:
A more interesting example would be extracting the list of preopens from the runtime.
+ This is now supported in the standard library via std.fs.wasi.Preopens:
+ Target refers to the computer that will be used to run an executable.
+ It is composed of the CPU architecture, the set of enabled CPU features, operating system,
+ minimum and maximum operating system version, ABI, and ABI version.
+
+
+ Zig is a general-purpose programming language which means that it is designed to
+ generate optimal code for a large set of targets. The command zig targets
+ provides information about all of the targets the compiler is aware of.
+
When no target option is provided to the compiler, the default choice
+ is to target the host computer, meaning that the
+ resulting executable will be unsuitable for copying to a different
+ computer. In order to copy an executable to another computer, the compiler
+ needs to know about the target requirements via the -target option.
+
+
+ The Zig Standard Library (@import("std")) has
+ cross-platform abstractions, making the same source code viable on many targets.
+ Some code is more portable than other code. In general, Zig code is extremely
+ portable compared to other programming languages.
+
+
+ Each platform requires its own implementations to make Zig's
+ cross-platform abstractions work. These implementations are at various
+ degrees of completion. Each tagged release of the compiler comes with
+ release notes that provide the full support table for each target.
+
+These coding conventions are not enforced by the compiler, but they are shipped in
+this documentation along with the compiler in order to provide a point of
+reference, should anyone wish to point to an authority on agreed upon Zig
+coding style.
+
Everything is a value, all types are data, everything is context, all logic manages state.
+ Nothing is communicated by using a word that applies to all types.
+
Temptation to use "utilities", "miscellaneous", or somebody's initials
+ is a failure to categorize, or more commonly, overcategorization. Such
+ declarations can live at the root of a module that needs them with no
+ namespace needed.
Every declaration is assigned a fully qualified
+ namespace by the compiler, creating a tree structure. Choose names based
+ on the fully-qualified namespace, and avoid redundant name segments.
In this example, "json" is repeated in the fully-qualified namespace. The solution
+ is to delete Json from JsonValue. In this example we have
+ an empty struct named json but remember that files also act
+ as part of the fully-qualified namespace.
+
This example is an exception to the rule specified in Avoid Redundancy in Names.
+ The meaning of the type has been reduced to its core: it is a json value. The name
+ cannot be any more specific without being incorrect.
+ Roughly speaking: camelCaseFunctionName, TitleCaseTypeName,
+ snake_case_variable_name. More precisely:
+
+
+
+ If x is a type
+ then x should be TitleCase, unless it
+ is a struct with 0 fields and is never meant to be instantiated,
+ in which case it is considered to be a "namespace" and uses snake_case.
+
+
+ If x is callable, and x's return type is
+ type, then x should be TitleCase.
+
+
+ If x is otherwise callable, then x should
+ be camelCase.
+
+
+ Otherwise, x should be snake_case.
+
+
+
+ Acronyms, initialisms, proper nouns, or any other word that has capitalization
+ rules in written English are subject to naming conventions just like any other
+ word. Even acronyms that are only 2 letters long are subject to these
+ conventions.
+
+
+ File names fall into two categories: types and namespaces. If the file
+ (implicitly a struct) has top level fields, it should be named like any
+ other struct with fields using TitleCase. Otherwise,
+ it should use snake_case. Directory names should be
+ snake_case.
+
+
+ These are general rules of thumb; if it makes sense to do something different,
+ do what makes sense. For example, if there is an established convention such as
+ ENOENT, follow the established convention.
+
Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.
+
Throughout all zig source code (including in comments), some code points are never allowed:
+
+
Ascii control characters, except for U+000a (LF), U+000d (CR), and U+0009 (HT): U+0000 - U+0008, U+000b - U+000c, U+000e - U+0001f, U+007f.
+
Non-Ascii Unicode line endings: U+0085 (NEL), U+2028 (LS), U+2029 (PS).
+
+
+ LF (byte value 0x0a, code point U+000a, '\n') is the line terminator in Zig source code.
+ This byte value terminates every line of zig source code except the last line of the file.
+ It is recommended that non-empty source files end with an empty line, which means the last byte would be 0x0a (LF).
+
+
+ Each LF may be immediately preceded by a single CR (byte value 0x0d, code point U+000d, '\r')
+ to form a Windows style line ending, but this is discouraged. Note that in multiline strings, CRLF sequences will
+ be encoded as LF when compiled into a zig program.
+ A CR in any other context is not allowed.
+
+
+ HT hard tabs (byte value 0x09, code point U+0009, '\t') are interchangeable with
+ SP spaces (byte value 0x20, code point U+0020, ' ') as a token separator,
+ but use of hard tabs is discouraged. See Grammar.
+
+
+ For compatibility with other tools, the compiler ignores a UTF-8-encoded byte order mark (U+FEFF)
+ if it is the first Unicode code point in the source text. A byte order mark is not allowed anywhere else in the source.
+
+
+ Note that running zig fmt on a source file will implement all recommendations mentioned here.
+
+
+ Note that a tool reading Zig source code can make assumptions if the source code is assumed to be correct Zig code.
+ For example, when identifying the ends of lines, a tool can use a naive search such as /\n/,
+ or an advanced
+ search such as /\r\n?|[\n\u0085\u2028\u2029]/, and in either case line endings will be correctly identified.
+ For another example, when identifying the whitespace before the first token on a line,
+ a tool can either use a naive search such as /[ \t]/,
+ or an advanced search such as /\s/,
+ and in either case whitespace will be correctly identified.
+
+ align can be used to specify the alignment of a pointer.
+ It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function.
+
+ await can be used to suspend the current function until the frame provided after the await completes.
+ await copies the value returned from the target function's frame to the caller.
+
+ catch can be used to evaluate an expression if the expression before it evaluates to an error.
+ The expression after the catch can optionally capture the error value.
+
+ comptime before a declaration can be used to label variables or function parameters as known at compile time.
+ It can also be used to guarantee an expression is run at compile time.
+
+ const declares a variable that can not be modified.
+ Used as a pointer attribute, it denotes the value referenced by the pointer cannot be modified.
+
+ errdefer will execute an expression when control flow leaves the current block if the function returns an error, the errdefer expression can capture the unwrapped value.
+
+ extern can be used to declare a function or variable that will be resolved at link time, when linking statically
+ or at runtime, when linking dynamically.
+
+ An if expression can test boolean expressions, optional values, or error unions.
+ For optional values or error unions, the if expression can capture the unwrapped value.
+
+ inline can be used to label a loop expression such that it will be unrolled at compile time.
+ It can also be used to force a function to be inlined at all call sites.
+
+ The nosuspend keyword can be used in front of a block, statement or expression, to mark a scope where no suspension points are reached.
+ In particular, inside a nosuspend scope:
+
+
Using the suspend keyword results in a compile error.
+
Using await on a function frame which hasn't completed yet results in safety-checked Illegal Behavior.
+
Calling an async function may result in safety-checked Illegal Behavior, because it's equivalent to await async some_async_fn(), which contains an await.
+
+ Code inside a nosuspend scope does not cause the enclosing function to become an async function.
+
+ suspend will cause control flow to return to the call site or resumer of the function.
+ suspend can also be used before a block within a function,
+ to allow the function access to its frame before control flow returns to the call site.
+
+
+
+
+
switch
+
+
+ A switch expression can be used to test values of a common type.
+ switch cases can capture field values of a Tagged union.
+
+ try evaluates an error union expression.
+ If it is an error, it returns from the current function with the same error.
+ Otherwise, the expression results in the unwrapped value.
+
+ unreachable can be used to assert that control flow will never happen upon a particular location.
+ Depending on the build mode, unreachable may emit a panic.
+
+
Emits a panic in Debug and ReleaseSafe mode, or when using zig test.
+
Does not emit a panic in ReleaseFast and ReleaseSmall mode.
+ usingnamespace is a top-level declaration that imports all the public declarations of the operand,
+ which must be a struct, union, or enum, into the current scope.
+
+ volatile can be used to denote loads or stores of a pointer have side effects.
+ It can also modify an inline assembly expression to denote it has side effects.
+
+ A while expression can be used to repeatedly test a boolean, optional, or error union expression,
+ and cease looping when that expression evaluates to false, null, or an error, respectively.
+
+ A container in Zig is any syntactical construct that acts as a namespace to hold variable and function declarations.
+ Containers are also type definitions which can be instantiated.
+ Structs, enums, unions, opaques, and even Zig source files themselves are containers.
+
+
+ Although containers (except Zig source files) use curly braces to surround their definition, they should not be confused with blocks or functions.
+ Containers do not contain statements.
+