[API Proposal]: MemoryExtensions.BitwiseAnd/Or/Xor/Not

[stephentoub]

Background and motivation

BitArray has And, Or, and Xor methods that combine another BitArray's bits with this BitArray's bits, and a Not method that operates on the BitArray's bits. These are vectorized and operate on the BitArray's internal int[]. But such And/Or/Xor/Not operations are more general, and as long as we've gone to the trouble to implement these efficiently, we can expose those operations for others to use as well.

API Proposal

namespace System;

public class MemoryExtensions
{
    public static void BitwiseAnd(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] &= other[i];
    public static void BitwiseOr(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] |= other[i];
    public static void BitwiseXor(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] ^= other[i];
    public static void BitwiseNot(this Span<byte> span); // span[i] = ~span[i];
}

Notes:

• The inputs would need to be the same byte length. Differing lengths would result in exception.
• Callers with data types other than byte would use MemoryMarshal.AsBytes to get a byte span from their data type. We don't want to have tons of overloads for these methods to accomodate lots of different types being used to hold the bits.
• Name is negotiable, as always.

API Usage

e.g. BitArray.And would become:

public unsafe BitArray And(BitArray value)
{
    ...
    Span<byte> thisSpan = MemoryMarshal.AsBytes(m_array.AsSpan(0, count));
    Span<byte> valueSpan = MemoryMarshal.AsBytes(value.m_array.AsSpan(0, count));

    thisSpan.BitwiseAnd(valueSpan);

    _version++;
    return this;
}

Alternative Designs

• We might consider overloads that take two ReadOnlySpan<byte> sources and a third Span<byte> destination. Such an overload could also be instead of the two-arg overloads if we document that the same span can be used as both a source and destination input.

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-memory
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

BitArray has And, Or, and Xor methods that combine another BitArray's bits with this BitArray's bits, and a Not method that operates on the BitArray's bits. These are vectorized and operate on the BitArray's internal int[]. But such And/Or/Xor/Not operations are more general, and as long as we've gone to the trouble to implement these efficiently, we can expose those operations for others to use as well.

API Proposal

namespace System;

public class MemoryExtensions
{
    public static void BitwiseAnd(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] &= other[i];
    public static void BitwiseOr(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] |= other[i];
    public static void BitwiseXor(this Span<byte> span, ReadOnlySpan<byte> other); // span[i] ^= other[i];
    public static void BitwiseNot(this Span<byte> span); // span[i] = ~span[i];
}

Notes:

• The inputs would need to be the same byte length. Differing lengths would result in exception.
• Callers with data types other than byte would use MemoryMarshal.AsBytes to get a byte span from their data type. We don't want to have tons of overloads for these methods to accomodate lots of different types being used to hold the bits.
• Name is negotiable, as always.

API Usage

e.g. BitArray.And would become:

public unsafe BitArray And(BitArray value)
{
    ...
    Span<byte> thisSpan = MemoryMarshal.AsBytes(m_array.AsSpan(0, count));
    Span<byte> valueSpan = MemoryMarshal.AsBytes(value.m_array.AsSpan(0, count));

    thisSpan.And(valueSpan);

    _version++;
    return this;
}

Alternative Designs

No response

Risks

No response

Author:	stephentoub
Assignees:	-
Labels:	api-suggestion, area-System.Memory
Milestone:	8.0.0

[stephentoub]

For reference, it's fairly easy to find others already doing such operations manually using Vector<T>, e.g.

• https://github.com/Thealexbarney/LibHac/blob/afeb3d391b2faf8f5091a4bab7182ffa440324c8/src/LibHac/Common/Utilities.cs#L56
• https://github.com/sdrapkin/SecurityDriven.Inferno/blob/ea96bf962768ca7932c03f4feca5cf96df438428/Cipher/AesCtrCryptoTransform.cs#L101
• https://github.com/shadowsocks/Shadowsocks-Net/blob/aab87a688ee9d8d85162c1ffdbeb5ec796b55960/Shadowsocks-Net/Shadowsocks.Cryptography/SpanExtensions.cs#L60
• https://github.com/FanTranslatorsInternational/Kuriimu2/blob/2efc25ac3091236b433f5043dffd1949aae45c5a/src/Kryptography/XorStream.cs#L122

etc.

[vcsjones]

As a point of some previous discussion, there is a similar proposal for this at #26651 that expresses interest in this functionality.

[stephentoub]

Thanks; I searched but somehow missed that. Will close this in favor of that one since it's preexisting and has existing discussion.
cc: @GrabYourPitchforks