Proposal: make by-ref capture semantics consistent

[mlugg]

Background

In Zig, several constructs can capture a value "by reference" using the syntax |*x|. The captures which can be by-ref are:

• The capture of an iterable for operand (i.e. not a range)
• The payload capture of a if on an optional or error union
• The payload capture of a while on an optional or error union
• The payload capture of a switch prong

However, there is an inconsistency in how these by-ref captures work between for operands and other constructs. The inconsistency is made clear by these two examples:

var arr: [5]u32 = undefined;
for (arr) |*x| x.* = 0;

var opt: ?u32 = 123;
if (opt) |*x| x.* = 456;

The second of these snippets compiles; the first does not. For the first snippet to compile, the for operand needs to be &arr.

This difference occurs because in the latter case, Zig effectively inserts an & before the operand when the capture is "by-ref". while and switch captures also follow the latter behavior.

The for behavior has some advantages. Mainly, it is more explicit; you can tell exactly what the code is doing. Implicit references can look a bit weird in a few cases. Consider:

while (it.next()) |*x| {
    // ...
}

What's that snippet doing? You'd be forgiven for thinking that next returns a *?T or similar, but actually, this inserts an implicit &, meaning x is a pointer to a local temporary. If next did return *?T, you'd currently have to write:

while (it.next().*) |*x| {
    // ...
}

Okay, so we're dereferencing the pointer... but we somehow get a pointer out which is derived from it? The logic here does make sense, but it's quite weird.

The implicit-ref behavior also meshes particularly strangely with switch, because any prong having a by-ref capture changes how the operand is evaluated. This means there can be arbitrary distance between the operand and the code which decides how it is evaluated, which is pretty strange.

Proposal

Remove the implicit-ref behavior of if, while, and switch on their operands. These constructs will now accept pointers to their operand types, and pointers will be required for by-ref captures.

Here's how this looks in practice:

var opt: ?u32 = 123;
if (&opt) |*x| x.* = 456;
// this is also allowed, although redundant, when you capture by value
if (&opt) |x| _ = x;

// and likewise for error unions
var eu: anyerror!u32 = 123;
if (&eu) |*x| {
    x.* = 456;
} else |_| {}
if (&eu) |x| {
    _ = x; // by-val capture even though the operand is a pointer
} else |_| {}

// `while` works exactly like `if`

// `switch` looks like this:
const U = union(enum) {
    foo: u32,
    bar: u64,
};
var u: U = .{ .x = 123 };
switch (&u) {
    .foo => |*x| x.* = 456,
    .bar => |y| _ = y,
}
// again, it's okay for the captures to be by-val
switch (&u) {
    .foo => |x| _ = x,
    .bar => |y| _ = y,
}

There's one problem here: switch (&u) already has a different meaning! Currently, switch on pointers is allowed, and switches on the address. As such, this proposal also proposes removing switch on pointers as it works today. If desired, the exact same behavior can be achieved by switching on @intFromPtr of a pointer. (I don't think switch on pointers is heavily relied upon in the wild; my source for this is that it's pretty much completely broken on the LLVM backend right now!)

[rohlem]

While I think the proposal seems clearer than status-quo in the common case,
I don't like that it introduces type-dependent behavior of inserting an implicit .* for normal capture syntax |x| for pointer-to-one types.
Since this is syntax-invisible (and can be different across instantiations in generic code),
it can lead to other, more subtle bugs than status-quo
(though to be fair, I think most will result in compile errors, so aren't really "dangerous").

Example:

In status-quo we have this implicit & inserted by the compiler if a capture has by-ref syntax |*x|.
This is a quite specific mechanism that might be confusing, but I would argue it is 100% manageable,
and it can be used quite well once you understand it.

The proposal instead opts for an implict .* to be inserted for subjects of pointer-to-one type
when a capture has normal capture syntax |x|.
Say you want to read the elements of a generic container: Its Element type might be u8 or *u8.
Capturing .get(index) in |element| will now dereference one pointer level by default, so you get a u8 either way.

Maybe a simple fix is calling a method that always returns *Element,
so that the one level of indirection which the compiler removes cancels it out.
However, in my eyes that's semantically more convoluted, and not at all obvious/intuitive.
(Changing the code from .getPointer(index) back to .get(index) will trigger compile errors only if
Element is a pointer-to-one, but still work for other types, which is I'd find quite confusing.)

---

I've commented my suggestion for this in #14734 (comment) .
In short: Opt into status-quo by-reference capture behavior with a new keyword, as in if byref (optional) |*payload|.
Writing a by-ref capture |*x| without the keyword becomes a compile error.
We can also make it a compile error (or not) to write byref when not using it (having only normal |c| captures).

It's probably not perfect in someone's eyes (feels a little clunky even to me personally),
but I'd prefer a solution that is explicit, and introduces no type-dependent behavior.
EDIT: This proposal's primary motivation seems to be to make semantics more consistent.
To me consistency includes no type-dependent behavior, since it disadvantages generic code.

[Littleote]

@rohlem
In your example you mention a generic type Element which might be either u8 or *u8. This means that the type you'd pass to the if or while would be ?Element (or an error union), that is ?u8 or ?*u8. As I understand the proposal, both of this cases would only allow for a normal capture |x| resulting each in the types u8 and *u8 (the type of Element). To use capture by reference |*x| you'd need to pass either a *?u8 or *?*u8 yielding types *u8 and **u8 (or types u8 and *u8 if using a normal capture) which would only happen if you used &maybe_element.

[rohlem]

@Littleote I was talking about an abstract / any container/iterator/view, not one particular type.
You are right that the result type of a get method will commonly be ?Element.
It could also be defined as !Element, or plain Element if all available indices are (statically) mapped (or if it's a getAssert method).
This was just a made-up example, in a real use case I might have applied .?, orelse, catch etc.,
either ad-hoc or to place the unwrapped version into a separate variable/constant.

Also note that ?Element can be chained right into the next capture:
if (container.get(index)) |maybe_element| if(maybe_element) |element|.
My concern still stands for element here being auto-dereferenced
under new semantics if it is of a pointer-to-one type.

As stated, I agree that this proposal might not lead to issues in common scenarios.
My concerns regard edge cases behaving irregularly,
under the premise that edge cases matter.
In my eyes a more regular solution (without legal semantics depending on type) remains preferable.

[KilianHanich]

if (&eu) |*x| {
    x.* = 456;
} else |_| {}```

I guess this should work like that with your proposal? Currently at least you can't do that:

var eu: MyErrorSet!u32 = 123;
if (&eu) |*x| {
    x.* = 456;
    assert(@TypeOf(x.*) == u32);
} else |*e| {
    e.* = MyErrorSet.Something;
    assert(@TypeOf(e.*) == MyErrorSet);
}```

[Littleote]

@rohlem
Given a generic type Element used in any container, iterator, view, etc. (i.e. Element shouldn't be dereferenced nor unwrapped). We can check all combinations of pointers and optionals (the same applies for while and for error unions):

• An if on a variable of type?Element with normal capture leads to Element. (Remains the same)
• An if on a variable of type ?Element with capture by reference (under this proposal) would lead to a compile error. You'll need to take a reference even if Element is a pointer to something. Currently this captures a pointer to a local variable of type *Element.
• An if on a variable of type*?Element with normal capture leads to Element. (This now works)
• An if on a variable of type*?Element with capture by reference leads to *Element. (This now works)
• An if on a variable of type Element or *Element with normal capture or by reference is always a bug in the user's code. It either results in a compile error or unwraps Element (Element shouldn't be dereferenced nor unwrapped) in the capture of the if (an under this proposal may also dereference it).

The only problematic case I see is the last one (the one you are refering to), which is always a bug in the user's code. It's present whether you use the status quo or this proposal.

[rohlem]

(EDIT 5: I realize I wrote way too many words again.
It seems I'm very defensive about language changes like this.
I'm sorry if the tone in my over-explicit comments ever comes across as combative,
my intention is to stay constructive and point out things that I believe others might have missed, nothing more.)

@Littleote I personally read the proposal differently, but it's probably best to ask for clarification from @mlugg (- please point out where either comment is inaccurate).

EDIT 2: I actually only now noticed that the proposal section explicitly mentions if, while and switch but not for.
I'm not sure if this is on purpose - if for is specifically omitted, then its semantics still wouldn't be fully consistent with the rest.
(For now I've assumed a for capture (EDIT3: i.e. each element) to also be affected by the proposed auto-dereference of pointer-to-one values.
Maybe instead only its subject would be affected as in status-quo, and each element type would stay the same.
EDIT 3: This would be irregular compared to while, which is proposed to auto-dereference every "element".
I guess it's somewhat regular though in that it's always the "subject" - the for "subject" is the iterable whereas the while "subject" is every element.)

Detailed response:

The way I read the proposal, every by-value capture |x| would auto-dereference when given a pointer-to-one type (f.e. *u8).
(Note that lists are allowed to hold *u8 as element type, and it might make sense to manage a list of pointers.)

• An if on a variable of type ?Element with normal capture leads to Element. (Remains the same)

If Element is a pointer-to-one, it might lead to Element.* (pseudo-syntax, more correctly @typeInfo(Element).pointer.child)
Being able to write code that works on lists of objects just as well as on lists of pointers-to-object
is a feature of Zig's current regularity across types.

• An if on a variable of type *?Element with [normal | by-reference] capture leads to [Element|*Element]. (This now works)

Stating "this now works" reads to me like an implication that it didn't work previously.
It does work in status-quo, according to status-quo rules.
I have written (a bunch of) code with normal captures that are supposed to take *?u8 and give me *u8, not u8.
They already work, and changing language behavior means I need to change my code to retain the same behavior.
(Which I'm fine with, I'm just stating my preference to regularity,
and would prefer that whatever change we settle on doesn't degrade that aspect too much.)

EDIT4: My mistake, this point is about how *?Element wasn't previously even valid as an if subject.
Compile errors can be features too.
Previously only ?*E made sense, so the compiler pointed out if you passed *?E instead.
I'm not sure whether extending the syntax here is a net-positive or net-negative.
Previously if I had written this code, it would have been my mistake. Under the proposal, you might intend something with it.
Seems less explicit to me, but I also can't imagine use cases that might be helped by this yet, so I'll remain neutral.

• An if on a variable of type Element or *Element with normal capture or by reference is always a bug in the user's code.

I disagree that this is already a bug under status-quo semantics.

EDIT:

It either results in a compile error or unwraps Element

Maybe this is a source for our disagreement - if (on optionals and error unions) always unwraps, yes.
while-loops in status-quo unwrap optionals, for-loops in status-quo don't.
Neither dereferences pointer-to-one values (EDIT3: as element values, for-loops do auto-dereference the iterable subject)
in status-quo, under the proposal that is a new mechanism introduced
(that can only be avoided by purposely type-checking or ensuring one additional level of indirection to cancel it out).

In status-quo I can copy from a: [N]T into b: []T by for(a, b) |x, *y| y.* = x; for any T.
If T = u8, I want to copy bytes, if T = *u8, I want to copy pointers.
Under the proposal, if T = *u8, the concrete type becomes a: [N]*u8,
then x will auto-dereference each element, which breaks the code.
(EDIT 3: Unless I'm misinterpreting, see above.
In that case we can still construct the same case with a while loop that iterates over a via iterator.)
I'd instead have to write the capture as |*x, *y| if T is a pointer-to-one type,
but keep writing |x, *y| if it isn't.

(Note that current for-loop semantics of requiring a pointer argument for element byref capture already makes the example a bit artificial/finicky.
I agree we should settle on consistent semantics for all constructs.)
(EDIT2: See also EDIT 2 above - I assumed for captures are affected the same, but now I'm not sure anymore.)