466 lines
16 KiB
C#
466 lines
16 KiB
C#
// Licensed to the .NET Foundation under one or more agreements.
|
|
// The .NET Foundation licenses this file to you under the MIT license.
|
|
// See the LICENSE file in the project root for more information.
|
|
|
|
using System;
|
|
using System.Runtime.CompilerServices;
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
using System.Runtime.InteropServices;
|
|
#endif
|
|
using CommunityToolkit.HighPerformance.Helpers.Internals;
|
|
using CommunityToolkit.HighPerformance.Memory.Internals;
|
|
#if !NETSTANDARD2_1_OR_GREATER
|
|
using RuntimeHelpers = CommunityToolkit.HighPerformance.Helpers.Internals.RuntimeHelpers;
|
|
#endif
|
|
|
|
namespace CommunityToolkit.HighPerformance.Enumerables;
|
|
|
|
/// <summary>
|
|
/// A <see langword="ref"/> <see langword="struct"/> that iterates readonly items from arbitrary memory locations.
|
|
/// </summary>
|
|
/// <typeparam name="T">The type of items to enumerate.</typeparam>
|
|
public readonly ref struct ReadOnlyRefEnumerable<T>
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <summary>
|
|
/// The <see cref="ReadOnlySpan{T}"/> instance pointing to the first item in the target memory area.
|
|
/// </summary>
|
|
/// <remarks>The <see cref="ReadOnlySpan{T}.Length"/> field maps to the total available length.</remarks>
|
|
private readonly ReadOnlySpan<T> span;
|
|
#else
|
|
/// <summary>
|
|
/// The target <see cref="object"/> instance, if present.
|
|
/// </summary>
|
|
private readonly object? instance;
|
|
|
|
/// <summary>
|
|
/// The initial offset within <see cref="instance"/>.
|
|
/// </summary>
|
|
private readonly IntPtr offset;
|
|
|
|
/// <summary>
|
|
/// The total available length for the sequence.
|
|
/// </summary>
|
|
private readonly int length;
|
|
#endif
|
|
|
|
/// <summary>
|
|
/// The distance between items in the sequence to enumerate.
|
|
/// </summary>
|
|
/// <remarks>The distance refers to <typeparamref name="T"/> items, not byte offset.</remarks>
|
|
private readonly int step;
|
|
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <summary>
|
|
/// Initializes a new instance of the <see cref="ReadOnlyRefEnumerable{T}"/> struct.
|
|
/// </summary>
|
|
/// <param name="span">The <see cref="ReadOnlySpan{T}"/> instance pointing to the first item in the target memory area.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private ReadOnlyRefEnumerable(ReadOnlySpan<T> span, int step)
|
|
{
|
|
this.span = span;
|
|
this.step = step;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Initializes a new instance of the <see cref="ReadOnlyRefEnumerable{T}"/> struct.
|
|
/// </summary>
|
|
/// <param name="reference">A reference to the first item of the sequence.</param>
|
|
/// <param name="length">The number of items in the sequence.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
internal ReadOnlyRefEnumerable(in T reference, int length, int step)
|
|
{
|
|
this.span = MemoryMarshal.CreateReadOnlySpan(ref Unsafe.AsRef(reference), length);
|
|
this.step = step;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Creates a new instance of the <see cref="ReadOnlyRefEnumerable{T}"/> struct with the specified parameters.
|
|
/// </summary>
|
|
/// <param name="value">The reference to the first <typeparamref name="T"/> item to map.</param>
|
|
/// <param name="length">The number of items in the sequence.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
/// <returns>A <see cref="ReadOnlyRefEnumerable{T}"/> instance with the specified parameters.</returns>
|
|
/// <exception cref="ArgumentOutOfRangeException">Thrown when one of the parameters are negative.</exception>
|
|
public static ReadOnlyRefEnumerable<T> DangerousCreate(in T value, int length, int step)
|
|
{
|
|
if (length < 0)
|
|
{
|
|
ThrowArgumentOutOfRangeExceptionForLength();
|
|
}
|
|
|
|
if (step < 0)
|
|
{
|
|
ThrowArgumentOutOfRangeExceptionForStep();
|
|
}
|
|
|
|
OverflowHelper.EnsureIsInNativeIntRange(length, 1, step);
|
|
|
|
return new(in value, length, step);
|
|
}
|
|
#else
|
|
/// <summary>
|
|
/// Initializes a new instance of the <see cref="ReadOnlyRefEnumerable{T}"/> struct.
|
|
/// </summary>
|
|
/// <param name="instance">The target <see cref="object"/> instance.</param>
|
|
/// <param name="offset">The initial offset within <see paramref="instance"/>.</param>
|
|
/// <param name="length">The number of items in the sequence.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
internal ReadOnlyRefEnumerable(object? instance, IntPtr offset, int length, int step)
|
|
{
|
|
this.instance = instance;
|
|
this.offset = offset;
|
|
this.length = length;
|
|
this.step = step;
|
|
}
|
|
#endif
|
|
|
|
/// <summary>
|
|
/// Gets the total available length for the sequence.
|
|
/// </summary>
|
|
public int Length
|
|
{
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
get => this.span.Length;
|
|
#else
|
|
get => this.length;
|
|
#endif
|
|
}
|
|
|
|
/// <summary>
|
|
/// Gets the element at the specified zero-based index.
|
|
/// </summary>
|
|
/// <param name="index">The zero-based index of the element.</param>
|
|
/// <returns>A reference to the element at the specified index.</returns>
|
|
/// <exception cref="IndexOutOfRangeException">
|
|
/// Thrown when <paramref name="index"/> is invalid.
|
|
/// </exception>
|
|
public ref readonly T this[int index]
|
|
{
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
get
|
|
{
|
|
if ((uint)index >= (uint)Length)
|
|
{
|
|
ThrowHelper.ThrowIndexOutOfRangeException();
|
|
}
|
|
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
ref T r0 = ref MemoryMarshal.GetReference(this.span);
|
|
#else
|
|
ref T r0 = ref RuntimeHelpers.GetObjectDataAtOffsetOrPointerReference<T>(this.instance, this.offset);
|
|
#endif
|
|
nint offset = (nint)(uint)index * (nint)(uint)this.step;
|
|
ref T ri = ref Unsafe.Add(ref r0, offset);
|
|
|
|
return ref ri;
|
|
}
|
|
}
|
|
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <summary>
|
|
/// Gets the element at the specified zero-based index.
|
|
/// </summary>
|
|
/// <param name="index">The zero-based index of the element.</param>
|
|
/// <returns>A reference to the element at the specified index.</returns>
|
|
/// <exception cref="IndexOutOfRangeException">
|
|
/// Thrown when <paramref name="index"/> is invalid.
|
|
/// </exception>
|
|
public ref readonly T this[Index index]
|
|
{
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
get => ref this[index.GetOffset(Length)];
|
|
}
|
|
#endif
|
|
|
|
/// <inheritdoc cref="System.Collections.IEnumerable.GetEnumerator"/>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public Enumerator GetEnumerator()
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
return new(this.span, this.step);
|
|
#else
|
|
return new(this.instance, this.offset, this.length, this.step);
|
|
#endif
|
|
}
|
|
|
|
/// <summary>
|
|
/// Copies the contents of this <see cref="ReadOnlyRefEnumerable{T}"/> into a destination <see cref="RefEnumerable{T}"/> instance.
|
|
/// </summary>
|
|
/// <param name="destination">The destination <see cref="RefEnumerable{T}"/> instance.</param>
|
|
/// <exception cref="ArgumentException">
|
|
/// Thrown when <paramref name="destination"/> is shorter than the source <see cref="ReadOnlyRefEnumerable{T}"/> instance.
|
|
/// </exception>
|
|
public void CopyTo(RefEnumerable<T> destination)
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
if (this.step == 1)
|
|
{
|
|
destination.CopyFrom(this.span);
|
|
|
|
return;
|
|
}
|
|
|
|
if (destination.Step == 1)
|
|
{
|
|
CopyTo(destination.Span);
|
|
|
|
return;
|
|
}
|
|
|
|
ref T sourceRef = ref this.span.DangerousGetReference();
|
|
ref T destinationRef = ref destination.Span.DangerousGetReference();
|
|
int sourceLength = this.span.Length;
|
|
int destinationLength = destination.Span.Length;
|
|
#else
|
|
ref T sourceRef = ref RuntimeHelpers.GetObjectDataAtOffsetOrPointerReference<T>(this.instance, this.offset);
|
|
ref T destinationRef = ref RuntimeHelpers.GetObjectDataAtOffsetOrPointerReference<T>(destination.Instance, destination.Offset);
|
|
int sourceLength = this.length;
|
|
int destinationLength = destination.Length;
|
|
#endif
|
|
|
|
if ((uint)destinationLength < (uint)sourceLength)
|
|
{
|
|
ThrowArgumentExceptionForDestinationTooShort();
|
|
}
|
|
|
|
RefEnumerableHelper.CopyTo(ref sourceRef, ref destinationRef, (nint)(uint)sourceLength, (nint)(uint)this.step, (nint)(uint)destination.Step);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Attempts to copy the current <see cref="ReadOnlyRefEnumerable{T}"/> instance to a destination <see cref="RefEnumerable{T}"/>.
|
|
/// </summary>
|
|
/// <param name="destination">The target <see cref="RefEnumerable{T}"/> of the copy operation.</param>
|
|
/// <returns>Whether or not the operation was successful.</returns>
|
|
public bool TryCopyTo(RefEnumerable<T> destination)
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
int sourceLength = this.span.Length;
|
|
int destinationLength = destination.Span.Length;
|
|
#else
|
|
int sourceLength = this.length;
|
|
int destinationLength = destination.Length;
|
|
#endif
|
|
|
|
if (destinationLength >= sourceLength)
|
|
{
|
|
CopyTo(destination);
|
|
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Copies the contents of this <see cref="RefEnumerable{T}"/> into a destination <see cref="Span{T}"/> instance.
|
|
/// </summary>
|
|
/// <param name="destination">The destination <see cref="Span{T}"/> instance.</param>
|
|
/// <exception cref="ArgumentException">
|
|
/// Thrown when <paramref name="destination"/> is shorter than the source <see cref="RefEnumerable{T}"/> instance.
|
|
/// </exception>
|
|
public void CopyTo(Span<T> destination)
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
if (this.step == 1)
|
|
{
|
|
this.span.CopyTo(destination);
|
|
|
|
return;
|
|
}
|
|
|
|
ref T sourceRef = ref this.span.DangerousGetReference();
|
|
int length = this.span.Length;
|
|
#else
|
|
ref T sourceRef = ref RuntimeHelpers.GetObjectDataAtOffsetOrPointerReference<T>(this.instance, this.offset);
|
|
int length = this.length;
|
|
#endif
|
|
if ((uint)destination.Length < (uint)length)
|
|
{
|
|
ThrowArgumentExceptionForDestinationTooShort();
|
|
}
|
|
|
|
ref T destinationRef = ref destination.DangerousGetReference();
|
|
|
|
RefEnumerableHelper.CopyTo(ref sourceRef, ref destinationRef, (nint)(uint)length, (nint)(uint)this.step);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Attempts to copy the current <see cref="RefEnumerable{T}"/> instance to a destination <see cref="Span{T}"/>.
|
|
/// </summary>
|
|
/// <param name="destination">The target <see cref="Span{T}"/> of the copy operation.</param>
|
|
/// <returns>Whether or not the operation was successful.</returns>
|
|
public bool TryCopyTo(Span<T> destination)
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
int length = this.span.Length;
|
|
#else
|
|
int length = this.length;
|
|
#endif
|
|
|
|
if (destination.Length >= length)
|
|
{
|
|
CopyTo(destination);
|
|
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/// <inheritdoc cref="RefEnumerable{T}.ToArray"/>
|
|
public T[] ToArray()
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
int length = this.span.Length;
|
|
#else
|
|
int length = this.length;
|
|
#endif
|
|
|
|
// Empty array if no data is mapped
|
|
if (length == 0)
|
|
{
|
|
return Array.Empty<T>();
|
|
}
|
|
|
|
T[] array = new T[length];
|
|
|
|
CopyTo(array);
|
|
|
|
return array;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Implicitly converts a <see cref="RefEnumerable{T}"/> instance into a <see cref="ReadOnlyRefEnumerable{T}"/> one.
|
|
/// </summary>
|
|
/// <param name="enumerable">The input <see cref="RefEnumerable{T}"/> instance.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public static implicit operator ReadOnlyRefEnumerable<T>(RefEnumerable<T> enumerable)
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
return new(enumerable.Span, enumerable.Step);
|
|
#else
|
|
return new(enumerable.Instance, enumerable.Offset, enumerable.Length, enumerable.Step);
|
|
#endif
|
|
}
|
|
|
|
/// <summary>
|
|
/// A custom enumerator type to traverse items within a <see cref="ReadOnlyRefEnumerable{T}"/> instance.
|
|
/// </summary>
|
|
public ref struct Enumerator
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <inheritdoc cref="ReadOnlyRefEnumerable{T}.span"/>
|
|
private readonly ReadOnlySpan<T> span;
|
|
#else
|
|
/// <inheritdoc cref="ReadOnlyRefEnumerable{T}.instance"/>
|
|
private readonly object? instance;
|
|
|
|
/// <inheritdoc cref="ReadOnlyRefEnumerable{T}.offset"/>
|
|
private readonly IntPtr offset;
|
|
|
|
/// <inheritdoc cref="ReadOnlyRefEnumerable{T}.length"/>
|
|
private readonly int length;
|
|
#endif
|
|
|
|
/// <inheritdoc cref="ReadOnlyRefEnumerable{T}.step"/>
|
|
private readonly int step;
|
|
|
|
/// <summary>
|
|
/// The current position in the sequence.
|
|
/// </summary>
|
|
private int position;
|
|
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <summary>
|
|
/// Initializes a new instance of the <see cref="Enumerator"/> struct.
|
|
/// </summary>
|
|
/// <param name="span">The <see cref="ReadOnlySpan{T}"/> instance with the info on the items to traverse.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
internal Enumerator(ReadOnlySpan<T> span, int step)
|
|
{
|
|
this.span = span;
|
|
this.step = step;
|
|
this.position = -1;
|
|
}
|
|
#else
|
|
/// <summary>
|
|
/// Initializes a new instance of the <see cref="Enumerator"/> struct.
|
|
/// </summary>
|
|
/// <param name="instance">The target <see cref="object"/> instance.</param>
|
|
/// <param name="offset">The initial offset within <see paramref="instance"/>.</param>
|
|
/// <param name="length">The number of items in the sequence.</param>
|
|
/// <param name="step">The distance between items in the sequence to enumerate.</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
internal Enumerator(object? instance, IntPtr offset, int length, int step)
|
|
{
|
|
this.instance = instance;
|
|
this.offset = offset;
|
|
this.length = length;
|
|
this.step = step;
|
|
this.position = -1;
|
|
}
|
|
#endif
|
|
|
|
/// <inheritdoc cref="System.Collections.IEnumerator.MoveNext"/>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public bool MoveNext()
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
return ++this.position < this.span.Length;
|
|
#else
|
|
return ++this.position < this.length;
|
|
#endif
|
|
}
|
|
|
|
/// <inheritdoc cref="System.Collections.Generic.IEnumerator{T}.Current"/>
|
|
public readonly ref readonly T Current
|
|
{
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
get
|
|
{
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
ref T r0 = ref this.span.DangerousGetReference();
|
|
#else
|
|
ref T r0 = ref RuntimeHelpers.GetObjectDataAtOffsetOrPointerReference<T>(this.instance, this.offset);
|
|
#endif
|
|
nint offset = (nint)(uint)this.position * (nint)(uint)this.step;
|
|
ref T ri = ref Unsafe.Add(ref r0, offset);
|
|
|
|
return ref ri;
|
|
}
|
|
}
|
|
}
|
|
|
|
#if NETSTANDARD2_1_OR_GREATER
|
|
/// <summary>
|
|
/// Throws an <see cref="ArgumentOutOfRangeException"/> when the "length" parameter is invalid.
|
|
/// </summary>
|
|
private static void ThrowArgumentOutOfRangeExceptionForLength()
|
|
{
|
|
throw new ArgumentOutOfRangeException("length");
|
|
}
|
|
|
|
/// <summary>
|
|
/// Throws an <see cref="ArgumentOutOfRangeException"/> when the "step" parameter is invalid.
|
|
/// </summary>
|
|
private static void ThrowArgumentOutOfRangeExceptionForStep()
|
|
{
|
|
throw new ArgumentOutOfRangeException("step");
|
|
}
|
|
#endif
|
|
|
|
/// <summary>
|
|
/// Throws an <see cref="ArgumentException"/> when the target span is too short.
|
|
/// </summary>
|
|
private static void ThrowArgumentExceptionForDestinationTooShort()
|
|
{
|
|
throw new ArgumentException("The target span is too short to copy all the current items to.");
|
|
}
|
|
}
|