This means that some combinations of operators no longer have a defined precedence, and for those that don’t, the compiler will now require parentheses:
However, common cases can remain parenthesis-free:
const a = x + y * z;
The idea behind this is to reduce the number of rules a programmer needs to know when reading and writing Zig code. For example, no matter how experienced you are with Zig, it’s unlikely that you’d be able to explain the evaluation order of the following expression without looking up the precedence rules:
a & b + c * d >> e | f orelse g() catch h + i == j or k and l
With the now-required parentheses added (while maintaining the same evaluation order as the Zig 0.17.x precedence rules), that expression would look like this:
((((a & ((b + c * d) >> e)) | f) orelse g()) catch (h + i)) == j or (k and l);
Still quite hairy, and not something I’d like to see in the wild, but nonetheless it’s understandable without knowing any precedence rules beyond arithmetic and comparison. Outside of this contrived example, though, the expressions that will now require parentheses are relatively rare (353 lines needed changes out of the million+ lines of code in the Zig codebase).
What you need to know
In practice, going forward, you will only need to remember the rules around operator combinations that still have a defined/unambiguous precedence. For example, when reading or writing code involving arithmetic operators, you’ll only need to remember the following precedence table:
* / *% *| %
+ - +% -% +| -|
== != < > <= >=
and or
You might notice that there isn’t anything too surprising there, and that lack of surprise was a (subjective) guiding principle for what should and should not require parentheses. As an example, while % has unambiguous precedence with regards to addition/subtraction operators, parentheses must be used when mixing % with multiplication/division operators, and with itself. However, this, and other ambiguous operator combinations, aren’t something you’ll need to commit to memory. Any (future) code you read will already have parentheses to disambiguate, and for any code you write, the compiler will let you know when you need parentheses.
For the full explanation, and to see the relevant precedence tables pertaining to other operators, see the updated Precedence section of the language reference.
Upgrading existing code
There are two possible approaches here:
- Manually fix each “ambiguous operator precedence” error as they are surfaced by the compiler (this might be a good opportunity to try out incremental compilation if it’s supported on your platform)
- Use zig fmt --upgrade (the --upgrade flag was added for this purpose). This will cause zig fmt to add parentheses automatically, maintaining the evaluation order from the previous precedence rules (note: the --upgrade flag will be removed after one release cycle)
My personal recommendation would be option 1, as the process of redetermining the intended evaluation order for these uncommon precedence scenarios can occasionally serve to uncover bugs (here’s an example of that).
If you go with option 2, I’d still recommend perusing the diff afterwards to ensure that nothing looks unusual, or is different than you expected/intended. A potentially common example of that is something like a orelse b() catch c which previously evaluated to (a orelse b()) catch c, but changing that to a orelse (b() catch c) likely makes more sense, even if the end result is unaffected. Also worth noting that in some scenarios, redundant parentheses will be added by zig fmt --upgrade (e.g. you might see something like a orelse ((b + c) - d) where the parentheses around b + c are unnecessary), so avoiding that will take a bit of manual cleanup.
That’s about it. I’m hopeful that this change will make bugs stemming from misremembered precedence rules much less likely, and that it will put some attention onto any of those bugs that may currently exist.
Thanks again to CMDRZero for the implementation, and to Isaac Freund for help with the corresponding grammar changes.