API proposal: MemoryExtensions.ReferenceEqual

[GrabYourPitchforks]

API proposal: MemoryExtensions.ReferenceEqual

See #54794 for context. In a nutshell, we want developers to stop using the equality and inequality operators on Span<T> and ReadOnlySpan<T>.

ReadOnlySpan<char> span1, span2;

// Don't do this
// It checks for *referential* equality, which you probably didn't intend!
bool areEqual = (span1 == span2);

// Do this instead
// It checks for *content* equality, which you probably intended.
bool areEqual = span1.SequenceEqual(span2);

But there are some cases where callers really do need to check for referential equality, such as if they're trying to special-case "an arbitrary empty span" vs. "a span that specifically references nullptr." Another use case is string interning dictionaries, where callers may want to know as an optimization whether a span references a specific instance of a string value rather than simply containing the same contents.

Proposed API

namespace System
{
    // new APIs added to existing class (asm: System.Memory)
    public partial static class MemoryExtensions
    {
        public static bool ReferenceEqual<T>(this ReadOnlySpan<T> span, ReadOnlySpan<T> other);
        public static bool ReferenceEqual<T>(this Span<T> span, ReadOnlySpan<T> other);
    }
}

Discussion

If we eventually obsolete the span equality comparison operators, callers will need to answer the question "was this comparison intended to be a referential equality comparison or a value equality comparison?" We're betting on that most callers wanted value equality and will opt to change their call sites to target the existing SequenceEqual method. The new ReferenceEqual method proposed here provides an alternative for developers to preserve reference-equality comparison without needing to #pragma warning disable ... every call to the existing equality operators.

.NET already exposes two related contepts: static bool object.ReferenceEquals(object, object), which is pure referential equality; and static bool MemoryExtensions.SequenceEqual<T>(Span<T>, Span<T>) where T : IEquatable<T>, which performs content equality comparison.

For consistency with the existing MemoryExtensions.SequenceEqual API, we'll keep its parameter names in the proposed MemoryExtensions.ReferenceEqual API. We'll also drop the s from ReferenceEquals to match the existing extension method naming conventions.

Risks

The name ReferenceEqual might inadvertently convey "only referential equality" instead of the intended "both referential and length equality" behavior. That is, somebody might expect the following to return true.

ReadOnlySpan<char> span1 = "Hello!";
ReadOnlySpan<char> span2 = span1.Slice(0, 2);
bool equal = span1.ReferenceEqual(span2); // they both start at (reference) the same place!

We may be able to mitigate this risk through careful messaging and encouraging callers to think about "references to blocks of memory" rather than "references to addresses in memory". If you consider that a block of memory contains both a start and an end position - as distinct from just a single address - then the analogy makes sense.

[alexrp]

The name ReferenceEqual might inadvertently convey "only referential equality"

FWIW, that was what I expected at first glance.

Considering that and the potential confusion with object.ReferenceEquals(), I feel like there has to be a better name here, though I don't have any good suggestions off the top of my head.

[DaZombieKiller]

I feel like there has to be a better name here, though I don't have any good suggestions off the top of my head.

Maybe MemoryMarshal.AreSame/MemoryExtensions.IsSame, mirroring Unsafe.AreSame?

[Joe4evr]

The name ReferenceEqual might inadvertently convey "only referential equality" instead of the intended "both referential and length equality" behavior. That is, somebody might expect the following to return true.

ReferenceAndLengthEquals? 🙃

[GrabYourPitchforks]

I had considered "are same" but didn't like it because "same" and "equal" are too similar. The ambiguity would still exist.

Another alternative is RangeEqual, which clearly indicates it's talking about a range of memory. It also works with the Range slicing operator, which is a nice coincidence.

[terrajobst]

• We don't like ReferenceEquals because it's not clear that it covers start and length (as opposed to just start)

namespace System;

public partial static class MemoryExtensions
{
    public static bool ReferenceEqual<T>(this ReadOnlySpan<T> span, ReadOnlySpan<T> other);
    public static bool ReferenceEqual<T>(this Span<T> span, ReadOnlySpan<T> other);
}

[carlreinke]

IdentityEqual?

[jeffhandley]

Moving to 8.0.0 since we don't have agreement on the name yet.