netcore/System.Private.CoreLib/shared/System/Span.cs

   1 // Licensed to the .NET Foundation under one or more agreements.
   2 // The .NET Foundation licenses this file to you under the MIT license.
   3 // See the LICENSE file in the project root for more information.
   4
   5 using System.ComponentModel;
   6 using System.Diagnostics;
   7 using System.Runtime.CompilerServices;
   8
   9 using System.Runtime.Versioning;
  10
  11 #pragma warning disable 0809  //warning CS0809: Obsolete member 'Span<T>.Equals(object)' overrides non-obsolete member 'object.Equals(object)'
  12
  13 namespace System
  14 {
  15     /// <summary>
  16     /// Span represents a contiguous region of arbitrary memory. Unlike arrays, it can point to either managed
  17     /// or native memory, or to memory allocated on the stack. It is type- and memory-safe.
  18     /// </summary>
  19     [DebuggerTypeProxy(typeof(SpanDebugView<>))]
  20     [DebuggerDisplay("{ToString(),raw}")]
  21     public readonly ref partial struct Span<T>
  22     {
  23         /// <summary>
  24         /// The number of items in the span.
  25         /// </summary>
  26         public int Length
  27         {
  28             [NonVersionable]
  29             get => _length;
  30         }
  31
  32         /// <summary>
  33         /// Returns true if Length is 0.
  34         /// </summary>
  35         public bool IsEmpty
  36         {
  37             [NonVersionable]
  38             get => 0 >= (uint)_length; // Workaround for https://github.com/dotnet/coreclr/issues/19620
  39         }
  40
  41         /// <summary>
  42         /// Returns false if left and right point at the same memory and have the same length.  Note that
  43         /// this does *not* check to see if the *contents* are equal.
  44         /// </summary>
  45         public static bool operator !=(Span<T> left, Span<T> right) => !(left == right);
  46
  47         /// <summary>
  48         /// This method is not supported as spans cannot be boxed. To compare two spans, use operator==.
  49         /// <exception cref="System.NotSupportedException">
  50         /// Always thrown by this method.
  51         /// </exception>
  52         /// </summary>
  53         [Obsolete("Equals() on Span will always throw an exception. Use == instead.")]
  54         [EditorBrowsable(EditorBrowsableState.Never)]
  55         public override bool Equals(object? obj) =>
  56             throw new NotSupportedException(SR.NotSupported_CannotCallEqualsOnSpan);
  57
  58         /// <summary>
  59         /// This method is not supported as spans cannot be boxed.
  60         /// <exception cref="System.NotSupportedException">
  61         /// Always thrown by this method.
  62         /// </exception>
  63         /// </summary>
  64         [Obsolete("GetHashCode() on Span will always throw an exception.")]
  65         [EditorBrowsable(EditorBrowsableState.Never)]
  66         public override int GetHashCode() =>
  67             throw new NotSupportedException(SR.NotSupported_CannotCallGetHashCodeOnSpan);
  68
  69         /// <summary>
  70         /// Defines an implicit conversion of an array to a <see cref="Span{T}"/>
  71         /// </summary>
  72         public static implicit operator Span<T>(T[]? array) => new Span<T>(array);
  73
  74         /// <summary>
  75         /// Defines an implicit conversion of a <see cref="ArraySegment{T}"/> to a <see cref="Span{T}"/>
  76         /// </summary>
  77         public static implicit operator Span<T>(ArraySegment<T> segment) =>
  78             new Span<T>(segment.Array, segment.Offset, segment.Count);
  79
  80         /// <summary>
  81         /// Returns an empty <see cref="Span{T}"/>
  82         /// </summary>
  83         public static Span<T> Empty => default;
  84
  85         /// <summary>Gets an enumerator for this span.</summary>
  86         public Enumerator GetEnumerator() => new Enumerator(this);
  87
  88         /// <summary>Enumerates the elements of a <see cref="Span{T}"/>.</summary>
  89         public ref struct Enumerator
  90         {
  91             /// <summary>The span being enumerated.</summary>
  92             private readonly Span<T> _span;
  93             /// <summary>The next index to yield.</summary>
  94             private int _index;
  95
  96             /// <summary>Initialize the enumerator.</summary>
  97             /// <param name="span">The span to enumerate.</param>
  98             [MethodImpl(MethodImplOptions.AggressiveInlining)]
  99             internal Enumerator(Span<T> span)
 100             {
 101                 _span = span;
 102                 _index = -1;
 103             }
 104
 105             /// <summary>Advances the enumerator to the next element of the span.</summary>
 106             [MethodImpl(MethodImplOptions.AggressiveInlining)]
 107             public bool MoveNext()
 108             {
 109                 int index = _index + 1;
 110                 if (index < _span.Length)
 111                 {
 112                     _index = index;
 113                     return true;
 114                 }
 115
 116                 return false;
 117             }
 118
 119             /// <summary>Gets the element at the current position of the enumerator.</summary>
 120             public ref T Current
 121             {
 122                 [MethodImpl(MethodImplOptions.AggressiveInlining)]
 123                 get => ref _span[_index];
 124             }
 125         }
 126     }
 127 }