[API Proposal]: Simple one-shot hashing methods that produce the relevant type

[stephentoub]

Background and motivation

System.IO.Hashing contains types for Crc32, Crc64, XxHash32, and XxHash64, and XxHash3 is being added. These types all have one-shot static methods for performing hashes over ReadOnlySpan<byte>, but all of these methods either allocate a resulting byte[] or write the result into a Span<byte>. However, the natural data types expecting in many use cases is just an int/uint for 32-bit or long/ulong for 64-bit hashes. We should add helpers for this.

API Proposal

namespace System.IO.Hashing;

public sealed class Crc32 : NonCryptographicHashAlgorithm
{
+   public static int HashToInt32(ReadOnlySpan<byte> source);
+   public int GetCurrentHashAsInt32();
    ...
}

public sealed class XxHash32 : NonCryptographicHashAlgorithm
{
+   public static int HashToInt32(ReadOnlySpan<byte> source, int seed = 0);
+   public int GetCurrentHashAsInt32();
    ...
}

public sealed class Crc64 : NonCryptographicHashAlgorithm
{
+   public static long HashToInt64(ReadOnlySpan<byte> source);
+   public long GetCurrentHashAsInt64();
    ...
}

public sealed class XxHash64 : NonCryptographicHashAlgorithm
{
+   public static long HashToInt64(ReadOnlySpan<byte> source, long seed = 0);
+   public long GetCurrentHashAsInt64();
    ...
}

public sealed class XxHash3 : NonCryptographicHashAlgorithm
{
+   public static long HashToInt64(ReadOnlySpan<byte> source, long seed = 0);
+   public long GetCurrentHashAsInt64();
    ...
}

public sealed class XxHash128 : NonCryptographicHashAlgorithm // assuming https://github.com/dotnet/runtime/issues/77885
{
+   public static Int128 HashToInt128(ReadOnlySpan<byte> source, long seed = 0);
+   public Int128 GetCurrentHashAsInt128();
    ...
}

• All of these implementations already compute the relevant int/long and then write it to either a newly-allocated array or the destination span. We'd just return it instead from the new method.
• The existing methods write the value to the destination as big-endian. The int/long-returning methods would simply return the value in machine-endianness.
• Should we use unsigned types instead? All of the algorithms internally operate in unsigned land.

API Usage

ReadOnlySpan<byte> data = ...;
int hash = XxHash32.HashToInt32(data);

Alternative Designs

No response

Risks

No response

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

Issue Details

---

Background and motivation

System.IO.Hashing contains types for Crc32, Crc64, XxHash32, and XxHash64, and XxHash3 is being added. These types all have one-shot static methods for performing hashes over ReadOnlySpan<byte>, but all of these methods either allocate a resulting byte[] or write the result into a Span<byte>. However, the natural data types expecting in many use cases is just an int/uint for 32-bit or long/ulong for 64-bit hashes. We should add helpers for this.

API Proposal

namespace System.IO.Hashing;

public sealed class Crc32 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static uint HashToUInt32(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash32 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static uint HashToUInt32(ReadOnlySpan<byte> source);
    ...
}

public sealed class Crc64 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash64 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash3 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

• All of these implementations already compute the relevant uint/ulong and then write it to either a newly-allocated array or the destination span. We'd just return it instead from the new method.
• The existing methods write the value to the destination as big-endian. The uint/ulong-returning methods would simply return the value in machine-endianness.
• If we ever added a 128-bit hash, like XxHash128, we'd return UInt128.
• We could choose to return int/long instead of uint/ulong, but internally we're operating in terms of unsigned, our BitOperations APIs that hash operate on unsigned (e.g. Expose general purpose Crc32 APIs #2036 (comment)), and looking around the web, unsigned is generally what others appear to use.

API Usage

ReadOnlySpan<byte> data = ...;
uint hash = XxHash32.HashToUInt32(data);

Alternative Designs

No response

Risks

No response

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

[LeaFrock]

Hah, that's what I want!

But so sad that I have to wait for .NET 8 😭

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

Issue Details

---

Background and motivation

System.IO.Hashing contains types for Crc32, Crc64, XxHash32, and XxHash64, and XxHash3 is being added. These types all have one-shot static methods for performing hashes over ReadOnlySpan<byte>, but all of these methods either allocate a resulting byte[] or write the result into a Span<byte>. However, the natural data types expecting in many use cases is just an int/uint for 32-bit or long/ulong for 64-bit hashes. We should add helpers for this.

API Proposal

namespace System.IO.Hashing;

public sealed class Crc32 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static uint HashToUInt32(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash32 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static uint HashToUInt32(ReadOnlySpan<byte> source);
    ...
}

public sealed class Crc64 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash64 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

public sealed class XxHash3 : NonCryptographicHashAlgorithm
{
    public static byte[] Hash(ReadOnlySpan<byte> source);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination);
+   public static ulong HashToUInt64(ReadOnlySpan<byte> source);
    ...
}

• All of these implementations already compute the relevant uint/ulong and then write it to either a newly-allocated array or the destination span. We'd just return it instead from the new method.
• The existing methods write the value to the destination as big-endian. The uint/ulong-returning methods would simply return the value in machine-endianness.
• If we ever added a 128-bit hash, like XxHash128, we'd return UInt128.
• We could choose to return int/long instead of uint/ulong, but internally we're operating in terms of unsigned, our BitOperations APIs that hash operate on unsigned (e.g. Expose general purpose Crc32 APIs #2036 (comment)), and looking around the web, unsigned is generally what others appear to use.

API Usage

ReadOnlySpan<byte> data = ...;
uint hash = XxHash32.HashToUInt32(data);

Alternative Designs

No response

Risks

No response

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

[LeaFrock]

I have a very small question. Let's take XxHash64 for example: why is the API long HashToInt64 rather than ulong HashToUInt64?

The existing methods write the value to the destination as big-endian. The int/long-returning methods would simply return the value in machine-endianness.

Is it just a convention? I have this question because I see many underlying calculations use unsigned number in fact, such as String.GetHashCode(),

Marvin.ComputeHash32(ref Unsafe.As<char, byte>(ref _firstChar), (uint)_stringLength * 2 /* in bytes, not chars */, (uint)seed, (uint)(seed >> 32));

[bartonjs]

@stephentoub I've removed ready-for-review because I want @GrabYourPitchforks to acknowledge the existence of the proposal (and perhaps even express opinions) before it comes up in a review meeting.