059

July 23, 2026, 1:12am 1

I’m trying to learn this language, and it’s great, but it is hard, but due to lack of documentation/examples more than anything else, which I understand is low priority (deferred during major development, til 1.0) and that is totally fair - not a criticism.

But, I’ve looked through the documentation, gone through the overview, gone through the list of operators, and I can’t find a mention of what |this| is or how it works. From context clues I figure it’s a variable capture. But I don’t know specifics and want to read about it. When can it be used? It’s shown to be used in optionals with ifs, iterators within whiles, and with catching:

if (optional_foo) |foo| {

while (it.next()) |item| {

_ = foo() catch |err| return err;

So, you can use it when a preceding expression returns a value…? (Actually, you must use it if you can - just learned that from the compiler, which is excellent, it points you in the right direction.) But from that logic, that would imply you could do:

test "capture as declaration" {
    const math = @import("std").math;

    const two = math.floor(math.e);
    math.floor(math.pi) |three| {
        _ = two + three;
    }
}

But, that fails, so we can’t do that, and it would be weird anyways. But, can you understand my confusion?

Anyways… Is this anywhere in the docs? Also surely I’m overthinking this, but it’s just introduced sans explanation.

Tekla July 23, 2026, 1:20am 2

It’s called a capture and it’s commonly used when the value is an union (error or nullable).

It can be used on if, switch, catch and errdefer, as far as I know.

It’s basically sugar for unwrapping the actual value.

Edit: I have search the docs and I don’t see a specific block of text where they explain it. I’m on mobile rn, sorry if I missed it

Hello, welcome.

“Lack of documentation” is criticism - the good kind! The constructive kind. And it’s always appreciated.

However, the language reference is in fact complete, save for the ~7 TODOs sprinkled throughout for fringe topics. So it’s not accurate to say that documenting the language is not a priority, and if you find it lacking, more specifics are needed (what exactly is lacking?) for it to be helpful.

The reason you don’t see a section explicitly dedicated to capture syntax is that save for being a grammatical construct (it’s called “payload” in the formal grammar in the appendix), captures only exist as part of other syntax such as if, while, and switch, as you already noted. Captures are not a standalone concept.

Here are a few examples to help you out. I think between these 2 links (to the same thread) you should see every version of payload captures.

Several examples from @dude_the_builder

One extra from me

059 July 23, 2026, 2:35am 6

I see, okay.

I thought I had read at some point that due to zig being in early development, docs would be done or polished later. Not sure where I read that and it was a year or two ago.

Perhaps what I meant by lacking, was more targeted towards the overview. Starting with example 8, they stop passing tests (most issues are just includes which are easy to solve yourself). I was very hung up on the capture syntax. The wording on example 15 confused me last night ("switch ensures all cases are handled), but looking back I understand it now. Around this point I decided to look elsewhere for a tutorial/intro to the language.

It’s probably a big ask, but having example usage within the documentation, would be so helpful. For example, a tcp socket server:
https://ziglang.org/documentation/master/std/#std.Io.net.Server
(Some structs have descriptions, some don’t, not really a big deal in this case.)

Compared to the docs for C#'s tcp listener:
https://learn.microsoft.com/en-us/dotnet/api/system.net.sockets.tcplistener?view=net-10.0

The MSDN has examples straight away. Having examples up are very nice, I feel like I can immediately grasp how to put it to use, otherwise it can be a puzzle.

Ah, that makes a lot of sense, it exists as a sub concept to other concepts. Thank you.

You are likely thinking of the standard library documentation, and you would be correct that is the rough roadmap, as it is lacking.
The language reference explains grammar and syntax of Zig, and is more or less complete.

059 July 23, 2026, 4:17am 8

Such an active forum! Thanks for the help everyone, going to experiment again now.