Added [Memory|Span]Owner<T>.DangerousGetArray (#3530)

## PR Type
What kind of change does this PR introduce?

- Feature
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->


## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
There is currently no way to get the underlying `T[]` array from a `MemoryOwner<T>` or `SpanOwner<T>` instance without going through some hoops that are very inconvenient (and which are only possible for `MemoryOwner<T>`). Being able to use the array directly is necessary when working with some older APIs that don't offer a `Span<T>` or `Memory<T>` overload.

## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
This PR introduces a new `DangerousGetArray` method that mirrors the `MemoryMarshal.TryGetArray` method and works on `MemoryOwner<T>` and `SpanOwner<T>` instances. I've removed the try pattern since here the types guarantee that the underlying memory store will always be an array. The methods are called `Dangerous___` because using the array is potentially dangerous in case a user keeps the array after disposing the original owner, as it means that that array might've been rented to some other consumer, so using it could lead to unexpected behavior. The methods are not inherently dangerous per se.

## API surface

```csharp
namespace Microsoft.Toolkit.HighPerformance.Buffers
{
    public sealed class MemoryOwner<T>
    {
        public ArraySegment<T> DangerousGetArray();
    }

    public readonly ref struct SpanOwner<T>
    {
        public ArraySegment<T> DangerousGetArray();
    }
}
```

## Example usage

Suppose we have a `Person` class with `string Name`, `string Surname` and `int Age` properties, and we want to calculate an MD5 hash with the current state of the class. This was originally asked by a user in the C# Discord server ([here](https://discordapp.com/channels/143867839282020352/312132327348240384/766694351383560205)).

```csharp
public static string GetMD5Hash(Person person)
{
    using var buffer = new ArrayPoolBufferWriter<byte>();

    buffer.Write<char>(person.Name);
    buffer.Write<char>(person.Surname);
    buffer.Write(person.Age);

    using SpanOwner<byte> hash = SpanOwner<byte>.Allocate(16);

    using var md5 = MD5.Create();

    md5.TryComputeHash(buffer.WrittenSpan, hash.Span, out _);

    return BitConverter.ToString(hash.DangerousGetArray().Array!, 0, 16);
}
```

You can see how here we can leverage the new `DangerousGetArray` API to get the underlying array to use with the `BitConverter.ToString` API, which doesn't have an overload accepting a `ReadOnlySpan<byte>`. The same goes for many other existing APIs that only accept an array as input data instead of the new memory APIs.

## PR Checklist

Please check if your PR fulfills the following requirements:

- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] ~~Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->~~
- [ ] ~~Sample in sample app has been added / updated (for bug fixes / features)~~
    - [ ] ~~Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)~~
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [X] Contains **NO** breaking changes

Author: msftbot[bot]

Microsoft.Toolkit.HighPerformance/Buffers/MemoryOwner{T}.cs

@@ -7,6 +7,9 @@
 using System.Diagnostics;
 using System.Diagnostics.Contracts;
 using System.Runtime.CompilerServices;
+#if NETCORE_RUNTIME
+using System.Runtime.InteropServices;
+#endif
 using Microsoft.Toolkit.HighPerformance.Buffers.Views;
 using Microsoft.Toolkit.HighPerformance.Extensions;
 
@@ -180,7 +183,22 @@ public Span<T> Span
                     ThrowObjectDisposedException();
                 }
 
+#if NETCORE_RUNTIME
+                ref T r0 = ref array!.DangerousGetReferenceAt(this.start);
+
+                // On .NET Core runtimes, we can manually create a span from the starting reference to
+                // skip the argument validations, which include an explicit null check, covariance check
+                // for the array and the actual validation for the starting offset and target length. We
+                // only do this on .NET Core as we can leverage the runtime-specific array layout to get
+                // a fast access to the initial element, which makes this trick worth it. Otherwise, on
+                // runtimes where we would need to at least access a static field to retrieve the base
+                // byte offset within an SZ array object, we can get better performance by just using the
+                // default Span<T> constructor and paying the cost of the extra conditional branches,
+                // especially if T is a value type, in which case the covariance check is JIT removed.
+                return MemoryMarshal.CreateSpan(ref r0, this.length);
+#else
                 return new Span<T>(array!, this.start, this.length);
+#endif
             }
         }
 
@@ -208,6 +226,31 @@ public ref T DangerousGetReference()
             return ref array!.DangerousGetReferenceAt(this.start);
         }
 
+        /// <summary>
+        /// Gets an <see cref="ArraySegment{T}"/> instance wrapping the underlying <typeparamref name="T"/> array in use.
+        /// </summary>
+        /// <returns>An <see cref="ArraySegment{T}"/> instance wrapping the underlying <typeparamref name="T"/> array in use.</returns>
+        /// <exception cref="ObjectDisposedException">Thrown when the buffer in use has already been disposed.</exception>
+        /// <remarks>
+        /// This method is meant to be used when working with APIs that only accept an array as input, and should be used with caution.
+        /// In particular, the returned array is rented from an array pool, and it is responsibility of the caller to ensure that it's
+        /// not used after the current <see cref="MemoryOwner{T}"/> instance is disposed. Doing so is considered undefined behavior,
+        /// as the same array might be in use within another <see cref="MemoryOwner{T}"/> instance.
+        /// </remarks>
+        [Pure]
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ArraySegment<T> DangerousGetArray()
+        {
+            T[]? array = this.array;
+
+            if (array is null)
+            {
+                ThrowObjectDisposedException();
+            }
+
+            return new ArraySegment<T>(array!, this.start, this.length);
+        }
+
         /// <summary>
         /// Slices the buffer currently in use and returns a new <see cref="MemoryOwner{T}"/> instance.
         /// </summary>
@@ -222,7 +265,6 @@ public ref T DangerousGetReference()
         /// size and copy the previous items into the new one, or needing an additional variable/field
         /// to manually handle to track the used range within a given <see cref="MemoryOwner{T}"/> instance.
         /// </remarks>
-        [Pure]
         public MemoryOwner<T> Slice(int start, int length)
         {
             T[]? array = this.array;

Microsoft.Toolkit.HighPerformance/Buffers/SpanOwner{T}.cs

@@ -7,6 +7,9 @@
 using System.Diagnostics;
 using System.Diagnostics.Contracts;
 using System.Runtime.CompilerServices;
+#if NETCORE_RUNTIME
+using System.Runtime.InteropServices;
+#endif
 using Microsoft.Toolkit.HighPerformance.Buffers.Views;
 using Microsoft.Toolkit.HighPerformance.Extensions;
 
@@ -143,7 +146,16 @@ public int Length
         public Span<T> Span
         {
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
-            get => new Span<T>(this.array, 0, this.length);
+            get
+            {
+#if NETCORE_RUNTIME
+                ref T r0 = ref array!.DangerousGetReference();
+
+                return MemoryMarshal.CreateSpan(ref r0, this.length);
+#else
+                return new Span<T>(this.array, 0, this.length);
+#endif
+            }
         }
 
         /// <summary>
@@ -157,6 +169,23 @@ public ref T DangerousGetReference()
             return ref this.array.DangerousGetReference();
         }
 
+        /// <summary>
+        /// Gets an <see cref="ArraySegment{T}"/> instance wrapping the underlying <typeparamref name="T"/> array in use.
+        /// </summary>
+        /// <returns>An <see cref="ArraySegment{T}"/> instance wrapping the underlying <typeparamref name="T"/> array in use.</returns>
+        /// <remarks>
+        /// This method is meant to be used when working with APIs that only accept an array as input, and should be used with caution.
+        /// In particular, the returned array is rented from an array pool, and it is responsibility of the caller to ensure that it's
+        /// not used after the current <see cref="SpanOwner{T}"/> instance is disposed. Doing so is considered undefined behavior,
+        /// as the same array might be in use within another <see cref="SpanOwner{T}"/> instance.
+        /// </remarks>
+        [Pure]
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ArraySegment<T> DangerousGetArray()
+        {
+            return new ArraySegment<T>(array!, 0, this.length);
+        }
+
         /// <summary>
         /// Implements the duck-typed <see cref="IDisposable.Dispose"/> method.
         /// </summary>

UnitTests/UnitTests.HighPerformance.Shared/Buffers/Test_MemoryOwner{T}.cs

@@ -3,7 +3,6 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
-using System.Buffers;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using Microsoft.Toolkit.HighPerformance.Buffers;
@@ -105,7 +104,7 @@ public void Test_MemoryOwnerOfT_MultipleDispose()
             // by accident doesn't cause issues, and just does nothing.
         }
 
-        [TestCategory("HashCodeOfT")]
+        [TestCategory("MemoryOwnerOfT")]
         [TestMethod]
         public void Test_MemoryOwnerOfT_PooledBuffersAndClear()
         {
@@ -124,5 +123,44 @@ public void Test_MemoryOwnerOfT_PooledBuffersAndClear()
                 Assert.IsTrue(buffer.Span.ToArray().All(i => i == 0));
             }
         }
+
+        [TestCategory("MemoryOwnerOfT")]
+        [TestMethod]
+        public void Test_MemoryOwnerOfT_AllocateAndGetArray()
+        {
+            var buffer = MemoryOwner<int>.Allocate(127);
+
+            // Here we allocate a MemoryOwner<T> instance with a requested size of 127, which means it
+            // internally requests an array of size 127 from ArrayPool<T>.Shared. We then get the array
+            // segment, so we need to verify that (since buffer is not disposed) the returned array is
+            // not null, is of size >= the requested one (since ArrayPool<T> by definition returns an
+            // array that is at least of the requested size), and that the offset and count properties
+            // match our input values (same length, and offset at 0 since the buffer was not sliced).
+            var segment = buffer.DangerousGetArray();
+
+            Assert.IsNotNull(segment.Array);
+            Assert.IsTrue(segment.Array.Length >= buffer.Length);
+            Assert.AreEqual(segment.Offset, 0);
+            Assert.AreEqual(segment.Count, buffer.Length);
+
+            var second = buffer.Slice(10, 80);
+
+            // The original buffer instance is disposed here, because calling Slice transfers
+            // the ownership of the internal buffer to the new instance (this is documented in
+            // XML docs for the MemoryOwner<T>.Slice method).
+            Assert.ThrowsException<ObjectDisposedException>(() => buffer.DangerousGetArray());
+
+            segment = second.DangerousGetArray();
+
+            // Same as before, but we now also verify the initial offset != 0, as we used Slice
+            Assert.IsNotNull(segment.Array);
+            Assert.IsTrue(segment.Array.Length >= second.Length);
+            Assert.AreEqual(segment.Offset, 10);
+            Assert.AreEqual(segment.Count, second.Length);
+
+            second.Dispose();
+
+            Assert.ThrowsException<ObjectDisposedException>(() => second.DangerousGetArray());
+        }
     }
 }

UnitTests/UnitTests.HighPerformance.Shared/Buffers/Test_SpanOwner{T}.cs

@@ -60,7 +60,7 @@ public void Test_SpanOwnerOfT_InvalidRequestedSize()
             Assert.Fail("You shouldn't be here");
         }
 
-        [TestCategory("HashCodeOfT")]
+        [TestCategory("SpanOwnerOfT")]
         [TestMethod]
         public void Test_SpanOwnerOfT_PooledBuffersAndClear()
         {
@@ -79,5 +79,23 @@ public void Test_SpanOwnerOfT_PooledBuffersAndClear()
                 Assert.IsTrue(buffer.Span.ToArray().All(i => i == 0));
             }
         }
+
+        [TestCategory("SpanOwnerOfT")]
+        [TestMethod]
+        public void Test_SpanOwnerOfT_AllocateAndGetArray()
+        {
+            using var buffer = SpanOwner<int>.Allocate(127);
+
+            var segment = buffer.DangerousGetArray();
+
+            // See comments in the MemoryOwner<T> tests about this. The main difference
+            // here is that we don't do the disposed checks, as SpanOwner<T> is optimized
+            // with the assumption that usages after dispose are undefined behavior. This
+            // is all documented in the XML docs for the SpanOwner<T> type.
+            Assert.IsNotNull(segment.Array);
+            Assert.IsTrue(segment.Array.Length >= buffer.Length);
+            Assert.AreEqual(segment.Offset, 0);
+            Assert.AreEqual(segment.Count, buffer.Length);
+        }
     }
 }