`==` on collections containing `missing` breaks its contract

[Seelengrab]

help?> ==
search: == === !== = .= >= => <= !=

==(x, y)
[...]
For collections, missing is returned if at least one of the
operands contains a missing value and all non-missing values are equal. Use isequal or === to always get a Bool result.

Yet:

julia> (1,missing) == (missing,2)
missing

julia> [1,missing] == [missing,2]
missing

Per the docstring, these should both be false, since the non-missing values are not equal.

[nalimilan]

Maybe the docs could be made more explicit and say "all non-missing pairs of values".

[Seelengrab]

To me, the docstring implies usage of a skipmissing-like behavior, i.e. "in the absence of missing, are the two equal?". If that is true, and there is at least one missing in either collection, then the result is missing. If there is no missing, the result is whatever the former returns. Changing that seems breaking to me, so IMO the implementations should be fixed.

[adienes]

I would expect it to be the same as all(x .== y) so I think the current behavior is correct

[nalimilan]

And at least I can assure you that it behaves as intended. ;-)

To me, the docstring implies usage of a skipmissing-like behavior, i.e. "in the absence of missing, are the two equal?". If that is true, and there is at least one missing in either collection, then the result is missing.

Actually the reasoning behind the implemented behavior is different. The idea is that missing is returned if it's not possible to determine whether the two collections are equal or different, because by replacing missing values by some values they could be made either equal or different. missing represents a quantity which could have been measured but for some reason isn't known. This is exactly the same as three-valued logic that is implemented by & and |.

Changing that seems breaking to me, so IMO the implementations should be fixed.

You mean the documentation? Existing code can rely on the implementation, but not on an interpretation of the docstring which doesn't match the actual behavior.

[Seelengrab]

And at least I can assure you that it behaves as intended. ;-)

Then the docstring isn't precise enough in the behavior that is guaranteed, since the docstring is at the very least ambiguous in what is required/guaranteed.

Existing code can rely on the implementation, but not on an interpretation of the docstring which doesn't match the actual behavior.

That seems backwards to me - relying on what is documented is what has always been the go-to in Julia ("if it's not in the Manual, it's not API"), so hearing this is directly counter to what has been practiced so far. To me it feels like you're trying to justify the existing behavior post-fact.

[adienes]

my reading of the existing documentation matches the existing behavior

since the docstring is at the very least ambiguous

I would call it at the very most ambiguous? maybe the intersection of those two bounds makes it exactly equal ambiguous.

I certainly wouldn't agree that it's worded in a way counter to existing behavior

[Seelengrab]

If swapping the order in the conditional changes the result (that is, checking for "all non-missing values are equal" first), the documentation is certainly ambiguous. You're reading the docstring like return_missing = has_missing || all_different, whereas I'm reading it like return_missing = has_missing && all_different, because of that and there, suggesting a conjunction instead of a disjunction. I don't know how you get to that disjunction when the docstring clearly says and.

[mbauman]

The "all non-missing values are equal" clause could actually be read in at least three ways:

• Every single non-missing value on both LHS and RHS must be == to eachother. In other words, both sides must only have two unique values: missing and some x.
• After applying skipmissing to each argument independently, the resulting missing-less collections are iterated jointly and the iterated pairs of values must be equal.
• After applying Missings.skipmissings to the arguments jointly, the resulting missing-less collections are iterated jointly and the iterated pairs of values must be equal.

Docs do double-duty: they must be both accessible to newcomers while still giving technical guidance to advanced users.

[Seelengrab]

You can add at least two more, duplicating the last two - == doesn't say anything about iteration or order. That's why I only wrote "skipmissing-like" above, because not everything you can == is necessarily actually iterable or orderable.

[mbauman]

Right, which is precisely why this isn't well-specified enough to be a "contract" that should force implementation changes counter to the very much intended design.

[Seelengrab]

So what can I as a user that wants to implement == on a type refer to as a "ground truth"? What properties do I need to obey? "Check the implementation" just isn't feasible when there isn't necessarily an applicable reference implementation to compare to.

[nalimilan]

Maybe the simplest way to document this would be by mentioning the result of calling == on each pair of values? Something like:

For collections, missing is returned if calling == on each pair of values in matching positions
in x and y returns at least one missing and no false. For arrays, this is equivalent to all(x .== y).