diff options
Diffstat (limited to 'src/mscorlib/src/System/Span.cs')
| -rw-r--r-- | src/mscorlib/src/System/Span.cs | 477 |
1 files changed, 477 insertions, 0 deletions
diff --git a/src/mscorlib/src/System/Span.cs b/src/mscorlib/src/System/Span.cs new file mode 100644 index 0000000000..9fa55c63d7 --- /dev/null +++ b/src/mscorlib/src/System/Span.cs @@ -0,0 +1,477 @@ +// 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.Collections.Generic; +using System.Diagnostics; +using System.Runtime.CompilerServices; + +#pragma warning disable 0809 //warning CS0809: Obsolete member 'Span<T>.Equals(object)' overrides non-obsolete member 'object.Equals(object)' + +namespace System +{ + /// <summary> + /// Span represents contiguous region of arbitrary memory, with performance + /// characteristics on par with T[]. Unlike arrays, it can point to either managed + /// or native memory, or to memory allocated on the stack. It is type- and memory-safe. + /// </summary> + public struct Span<T> + { + /// <summary>A byref or a native ptr.</summary> + private readonly ByReference<T> _pointer; + /// <summary>The number of elements this Span contains.</summary> + private readonly int _length; + + /// <summary> + /// Creates a new span over the entirety of the target array. + /// </summary> + /// <param name="array">The target array.</param> + /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="array"/> is a null + /// reference (Nothing in Visual Basic).</exception> + /// <exception cref="System.ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception> + public Span(T[] array) + { + if (array == null) + ThrowHelper.ThrowArgumentNullException(ExceptionArgument.array); + if (default(T) == null) { // Arrays of valuetypes are never covariant + if (array.GetType() != typeof(T[])) + ThrowHelper.ThrowArrayTypeMismatchException(); + } + + _pointer = new ByReference<T>(ref JitHelpers.GetArrayData(array)); + _length = array.Length; + } + + /// <summary> + /// Creates a new span over the portion of the target array beginning + /// at 'start' index and covering the remainder of the array. + /// </summary> + /// <param name="array">The target array.</param> + /// <param name="start">The index at which to begin the span.</param> + /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="array"/> is a null + /// reference (Nothing in Visual Basic).</exception> + /// <exception cref="System.ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="start"/> is not in the range (<0 or >=Length). + /// </exception> + public Span(T[] array, int start) + { + if (array == null) + ThrowHelper.ThrowArgumentNullException(ExceptionArgument.array); + if (default(T) == null) { // Arrays of valuetypes are never covariant + if (array.GetType() != typeof(T[])) + ThrowHelper.ThrowArrayTypeMismatchException(); + } + if ((uint)start > (uint)array.Length) + ThrowHelper.ThrowArgumentOutOfRangeException(); + + _pointer = new ByReference<T>(ref Unsafe.Add(ref JitHelpers.GetArrayData(array), start)); + _length = array.Length - start; + } + + /// <summary> + /// Creates a new span over the portion of the target array beginning + /// at 'start' index and ending at 'end' index (exclusive). + /// </summary> + /// <param name="array">The target array.</param> + /// <param name="start">The index at which to begin the span.</param> + /// <param name="length">The number of items in the span.</param> + /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="array"/> is a null + /// reference (Nothing in Visual Basic).</exception> + /// <exception cref="System.ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="start"/> or end index is not in the range (<0 or >=Length). + /// </exception> + public Span(T[] array, int start, int length) + { + if (array == null) + ThrowHelper.ThrowArgumentNullException(ExceptionArgument.array); + if (default(T) == null) { // Arrays of valuetypes are never covariant + if (array.GetType() != typeof(T[])) + ThrowHelper.ThrowArrayTypeMismatchException(); + } + if ((uint)start > (uint)array.Length || (uint)length > (uint)(array.Length - start)) + ThrowHelper.ThrowArgumentOutOfRangeException(); + + _pointer = new ByReference<T>(ref Unsafe.Add(ref JitHelpers.GetArrayData(array), start)); + _length = length; + } + + /// <summary> + /// Creates a new span over the target unmanaged buffer. Clearly this + /// is quite dangerous, because we are creating arbitrarily typed T's + /// out of a void*-typed block of memory. And the length is not checked. + /// But if this creation is correct, then all subsequent uses are correct. + /// </summary> + /// <param name="pointer">An unmanaged pointer to memory.</param> + /// <param name="length">The number of <typeparamref name="T"/> elements the memory contains.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when <typeparamref name="T"/> is reference type or contains pointers and hence cannot be stored in unmanaged memory. + /// </exception> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="length"/> is negative. + /// </exception> + [CLSCompliant(false)] + public unsafe Span(void* pointer, int length) + { + if (JitHelpers.ContainsReferences<T>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(T)); + if (length < 0) + ThrowHelper.ThrowArgumentOutOfRangeException(); + + _pointer = new ByReference<T>(ref Unsafe.As<byte, T>(ref *(byte*)pointer)); + _length = length; + } + + /// <summary> + /// Create a new span over a portion of a regular managed object. This can be useful + /// if part of a managed object represents a "fixed array." This is dangerous because + /// "length" is not checked, nor is the fact that "rawPointer" actually lies within the object. + /// </summary> + /// <param name="obj">The managed object that contains the data to span over.</param> + /// <param name="objectData">A reference to data within that object.</param> + /// <param name="length">The number of <typeparamref name="T"/> elements the memory contains.</param> + /// <exception cref="System.ArgumentNullException"> + /// Thrown when the specified object is null. + /// </exception> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="length"/> is negative. + /// </exception> + public static Span<T> DangerousCreate(object obj, ref T objectData, int length) + { + if (obj == null) + ThrowHelper.ThrowArgumentNullException(ExceptionArgument.obj); + if (length < 0) + ThrowHelper.ThrowArgumentOutOfRangeException(ExceptionArgument.length); + + return new Span<T>(ref objectData, length); + } + + + /// <summary> + /// An internal helper for creating spans. + /// </summary> + internal Span(ref T ptr, int length) + { + _pointer = new ByReference<T>(ref ptr); + _length = length; + } + + /// <summary> + /// Returns a reference to the 0th element of the Span. If the Span is empty, returns a reference to the location where the 0th element + /// would have been stored. Such a reference can be used for pinning but must never be dereferenced. + /// </summary> + public ref T DangerousGetPinnableReference() + { + return ref _pointer.Value; + } + + /// <summary> + /// Gets the number of elements contained in the <see cref="Span{T}"/> + /// </summary> + public int Length => _length; + + /// <summary> + /// Returns whether the <see cref="Span{T}"/> is empty. + /// </summary> + public bool IsEmpty => _length == 0; + + /// <summary> + /// Fetches the element at the specified index. + /// </summary> + /// <exception cref="System.IndexOutOfRangeException"> + /// Thrown when the specified <paramref name="index"/> is not in range (<0 or >&eq;Length). + /// </exception> + public T this[int index] + { + get + { + if ((uint)index >= (uint)_length) + ThrowHelper.ThrowIndexOutOfRangeException(); + + return Unsafe.Add(ref DangerousGetPinnableReference(), index); + } + set + { + if ((uint)index >= (uint)_length) + ThrowHelper.ThrowIndexOutOfRangeException(); + + Unsafe.Add(ref DangerousGetPinnableReference(), index) = value; + } + } + + /// <summary> + /// Copies the contents of this span into destination span. If the source + /// and destinations overlap, this method behaves as if the original values in + /// a temporary location before the destination is overwritten. + /// </summary> + /// <param name="destination">The span to copy items into.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when the destination Span is shorter than the source Span. + /// </exception> + public void CopyTo(Span<T> destination) + { + if (!TryCopyTo(destination)) + ThrowHelper.ThrowArgumentException_DestinationTooShort(); + } + + /// <summary> + /// Copies the contents of this span into destination span. If the source + /// and destinations overlap, this method behaves as if the original values in + /// a temporary location before the destination is overwritten. + /// </summary> + /// <param name="destination">The span to copy items into.</param> + /// <returns>If the destination span is shorter than the source span, this method + /// return false and no data is written to the destination.</returns> + public bool TryCopyTo(Span<T> destination) + { + if ((uint)_length > (uint)destination.Length) + return false; + + SpanHelper.CopyTo<T>(ref destination.DangerousGetPinnableReference(), ref DangerousGetPinnableReference(), _length); + return true; + } + + /// <summary> + /// Returns true if left and right point at the same memory and have the same length. Note that + /// this does *not* check to see if the *contents* are equal. + /// </summary> + public static bool operator ==(Span<T> left, Span<T> right) + { + return left._length == right._length && Unsafe.AreSame<T>(ref left.DangerousGetPinnableReference(), ref right.DangerousGetPinnableReference()); + } + + /// <summary> + /// Returns false if left and right point at the same memory and have the same length. Note that + /// this does *not* check to see if the *contents* are equal. + /// </summary> + public static bool operator !=(Span<T> left, Span<T> right) => !(left == right); + + /// <summary> + /// This method is not supported as spans cannot be boxed. To compare two spans, use operator==. + /// <exception cref="System.NotSupportedException"> + /// Always thrown by this method. + /// </exception> + /// </summary> + [Obsolete("Equals() on Span will always throw an exception. Use == instead.")] + public override bool Equals(object obj) + { + ThrowHelper.ThrowNotSupportedException_CannotCallEqualsOnSpan(); + // Prevent compiler error CS0161: 'Span<T>.Equals(object)': not all code paths return a value + return default(bool); + } + + /// <summary> + /// This method is not supported as spans cannot be boxed. + /// <exception cref="System.NotSupportedException"> + /// Always thrown by this method. + /// </exception> + /// </summary> + [Obsolete("GetHashCode() on Span will always throw an exception.")] + public override int GetHashCode() + { + ThrowHelper.ThrowNotSupportedException_CannotCallGetHashCodeOnSpan(); + // Prevent compiler error CS0161: 'Span<T>.GetHashCode()': not all code paths return a value + return default(int); + } + + /// <summary> + /// Defines an implicit conversion of an array to a <see cref="Span{T}"/> + /// </summary> + public static implicit operator Span<T>(T[] array) => new Span<T>(array); + + /// <summary> + /// Defines an implicit conversion of a <see cref="ArraySegment{T}"/> to a <see cref="Span{T}"/> + /// </summary> + public static implicit operator Span<T>(ArraySegment<T> arraySegment) => new Span<T>(arraySegment.Array, arraySegment.Offset, arraySegment.Count); + + /// <summary> + /// Defines an implicit conversion of a <see cref="Span{T}"/> to a <see cref="ReadOnlySpan{T}"/> + /// </summary> + public static implicit operator ReadOnlySpan<T>(Span<T> span) => new ReadOnlySpan<T>(ref span.DangerousGetPinnableReference(), span._length); + + /// <summary> + /// Forms a slice out of the given span, beginning at 'start'. + /// </summary> + /// <param name="start">The index at which to begin this slice.</param> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="start"/> index is not in range (<0 or >Length). + /// </exception> + [MethodImpl(MethodImplOptions.NoOptimization)] // TODO-SPAN: Workaround for https://github.com/dotnet/coreclr/issues/7894 + public Span<T> Slice(int start) + { + if ((uint)start > (uint)_length) + ThrowHelper.ThrowArgumentOutOfRangeException(); + + return new Span<T>(ref Unsafe.Add(ref DangerousGetPinnableReference(), start), _length - start); + } + + /// <summary> + /// Forms a slice out of the given span, beginning at 'start', of given length + /// </summary> + /// <param name="start">The index at which to begin this slice.</param> + /// <param name="length">The desired length for the slice (exclusive).</param> + /// <exception cref="System.ArgumentOutOfRangeException"> + /// Thrown when the specified <paramref name="start"/> or end index is not in range (<0 or >&eq;Length). + /// </exception> + [MethodImpl(MethodImplOptions.NoOptimization)] // TODO-SPAN: Workaround for https://github.com/dotnet/coreclr/issues/7894 + public Span<T> Slice(int start, int length) + { + if ((uint)start > (uint)_length || (uint)length > (uint)(_length - start)) + ThrowHelper.ThrowArgumentOutOfRangeException(); + + return new Span<T>(ref Unsafe.Add(ref DangerousGetPinnableReference(), start), length); + } + + /// <summary> + /// Copies the contents of this span into a new array. This heap + /// allocates, so should generally be avoided, however it is sometimes + /// necessary to bridge the gap with APIs written in terms of arrays. + /// </summary> + public T[] ToArray() + { + if (_length == 0) + return Array.Empty<T>(); + + var destination = new T[_length]; + SpanHelper.CopyTo<T>(ref JitHelpers.GetArrayData(destination), ref DangerousGetPinnableReference(), _length); + return destination; + } + + // <summary> + /// Returns an empty <see cref="Span{T}"/> + /// </summary> + public static Span<T> Empty => default(Span<T>); + } + + public static class SpanExtensions + { + /// <summary> + /// Casts a Span of one primitive type <typeparamref name="T"/> to Span of bytes. + /// That type may not contain pointers or references. This is checked at runtime in order to preserve type safety. + /// </summary> + /// <param name="source">The source slice, of type <typeparamref name="T"/>.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when <typeparamref name="T"/> contains pointers. + /// </exception> + public static Span<byte> AsBytes<T>(this Span<T> source) + where T : struct + { + if (JitHelpers.ContainsReferences<T>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(T)); + + return new Span<byte>( + ref Unsafe.As<T, byte>(ref source.DangerousGetPinnableReference()), + checked(source.Length * Unsafe.SizeOf<T>())); + } + + /// <summary> + /// Casts a ReadOnlySpan of one primitive type <typeparamref name="T"/> to ReadOnlySpan of bytes. + /// That type may not contain pointers or references. This is checked at runtime in order to preserve type safety. + /// </summary> + /// <param name="source">The source slice, of type <typeparamref name="T"/>.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when <typeparamref name="T"/> contains pointers. + /// </exception> + public static ReadOnlySpan<byte> AsBytes<T>(this ReadOnlySpan<T> source) + where T : struct + { + if (JitHelpers.ContainsReferences<T>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(T)); + + return new ReadOnlySpan<byte>( + ref Unsafe.As<T, byte>(ref source.DangerousGetPinnableReference()), + checked(source.Length * Unsafe.SizeOf<T>())); + } + + /// <summary> + /// Casts a Span of one primitive type <typeparamref name="TFrom"/> to another primitive type <typeparamref name="TTo"/>. + /// These types may not contain pointers or references. This is checked at runtime in order to preserve type safety. + /// </summary> + /// <remarks> + /// Supported only for platforms that support misaligned memory access. + /// </remarks> + /// <param name="source">The source slice, of type <typeparamref name="TFrom"/>.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when <typeparamref name="TFrom"/> or <typeparamref name="TTo"/> contains pointers. + /// </exception> + public static Span<TTo> NonPortableCast<TFrom, TTo>(this Span<TFrom> source) + where TFrom : struct + where TTo : struct + { + if (JitHelpers.ContainsReferences<TFrom>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(TFrom)); + if (JitHelpers.ContainsReferences<TTo>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(TTo)); + + return new Span<TTo>( + ref Unsafe.As<TFrom, TTo>(ref source.DangerousGetPinnableReference()), + checked((int)((long)source.Length * Unsafe.SizeOf<TFrom>() / Unsafe.SizeOf<TTo>()))); + } + + /// <summary> + /// Casts a ReadOnlySpan of one primitive type <typeparamref name="TFrom"/> to another primitive type <typeparamref name="TTo"/>. + /// These types may not contain pointers or references. This is checked at runtime in order to preserve type safety. + /// </summary> + /// <remarks> + /// Supported only for platforms that support misaligned memory access. + /// </remarks> + /// <param name="source">The source slice, of type <typeparamref name="TFrom"/>.</param> + /// <exception cref="System.ArgumentException"> + /// Thrown when <typeparamref name="TFrom"/> or <typeparamref name="TTo"/> contains pointers. + /// </exception> + public static ReadOnlySpan<TTo> NonPortableCast<TFrom, TTo>(this ReadOnlySpan<TFrom> source) + where TFrom : struct + where TTo : struct + { + if (JitHelpers.ContainsReferences<TFrom>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(TFrom)); + if (JitHelpers.ContainsReferences<TTo>()) + ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(TTo)); + + return new ReadOnlySpan<TTo>( + ref Unsafe.As<TFrom, TTo>(ref source.DangerousGetPinnableReference()), + checked((int)((long)source.Length * Unsafe.SizeOf<TFrom>() / Unsafe.SizeOf<TTo>()))); + } + } + + internal static class SpanHelper + { + internal static unsafe void CopyTo<T>(ref T destination, ref T source, int elementsCount) + { + if (elementsCount == 0) + return; + + if (Unsafe.AreSame(ref destination, ref source)) + return; + + if (!JitHelpers.ContainsReferences<T>()) + { + fixed (byte* pDestination = &Unsafe.As<T, byte>(ref destination)) + { + fixed (byte* pSource = &Unsafe.As<T, byte>(ref source)) + { +#if BIT64 + Buffer.Memmove(pDestination, pSource, (ulong)elementsCount * (ulong)Unsafe.SizeOf<T>()); +#else + Buffer.Memmove(pDestination, pSource, (uint)elementsCount * (uint)Unsafe.SizeOf<T>()); +#endif + } + } + } + else + { + if (JitHelpers.ByRefLessThan(ref destination, ref source)) // copy forward + { + for (int i = 0; i < elementsCount; i++) + Unsafe.Add(ref destination, i) = Unsafe.Add(ref source, i); + } + else // copy backward to avoid overlapping issues + { + for (int i = elementsCount - 1; i >= 0; i--) + Unsafe.Add(ref destination, i) = Unsafe.Add(ref source, i); + } + } + } + } +} |