<BEGIN>

Zig Problems

I have been enjoying learning Zig. The language does some nice things by default, seems to have a decent community, and is mostly pleasant to write. However, it is still an immature language with an immature ecosystem, which means there are speedbumps and roadblocks to learning in some very unfortunate places. I’ve attempted to distill some of my headaches into useful, succinct information. Here it is.

Disclaimer: not everything complained about here is Zig’s fault. I’m coming from Javascript, so there were always going to be some growing pains. Or perhaps I’m just a little goofy with it.

For a little while, I couldn’t figure out how to specify a slice as a function parameter type. An array where I know the size is easy. Take [N]T, where N is the length and T is the type. But the slice just won’t go! I first ran into this problem with strings. The zig compiler will tell you they have a type of const [N]u8. Ok, but what if I want to take an arbitrary* string? Tell me what to type!

You will keep reading this, but it is important: a slice is a pointer. Or, actually, a slice is more like a struct with a pointer and a length.

Separately, you will learn that pointers can be “const”. This, confusingly, means two different things. It can either mean: - The pointer has been declared with const, in which case the value the pointer points to can be changed (unless, of course, it is also const) but the pointer cannot be changed to reference another address - The pointer points to a const value, in which case it needs const in its type declaration. This kind of pointer can changed to point at a different address, but its vale cannot be changed.

This confused me a great deal. I don’t think it’s entirely my fault. To illustrate what I mean, let’s compare these two zig tutorials. zig.guide (archived version) appears to use a different definition of “const pointer” than Zig by Example (archived version)! zig.guide gets demerit points for not even trying to disambiguate. But the lesson for you is to be careful. “const pointer” could mean two vastly different things. Make sure you understand what you’re reading (check the examples, if there are any). And, if you’re writing zig resources, consider simply using the c terminology.

The Zig error messages are not necessarily helpful here, either. They will confidently assert that you tried to pass in *const [N]T or * [N]T. No need to take them literally. You can take a slice as []T, you just need to remember that this is a pointer and that it can be const. You don’t need a comptime-known length, you can just do []const T. The [] is basically standing in for the * here? I guess? Neither the tutorials nor the documentation nor the compiler are every really lying to you, but none of them give anywhere near enough information on their own.

We need to talk about the zig documentation a little bit. I found it very frustrating that while it was easy enough to call zig std from the command line to pull of the stdlib documentation, there didn’t seem to be an easy way to get the language reference offline. And, well, there isn’t an easy way, but there is a way. If you know where your zig installation is located (try zig env), you should be able to pull up $ZIG_LOCATION/doc/langref.html. Yes, seriously, this appears to be the only way right now.

Even reading the documentation (in your browser) may not be enough, though. Something appears to be broken with doc generation; some doc comments simply do not appear in the generated markup. I recommend clicking [src] near the top of a page if you find any suspiciously glaring omissions. Here are some things this caused me to miss:

<END>