src/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
  30             {
  31                 return _length;
  32             }
  33         }
  34
  35         /// <summary>
  36         /// Returns true if Length is 0.
  37         /// </summary>
  38         public bool IsEmpty
  39         {
  40             [NonVersionable]
  41             get
  42             {
  43                 return _length == 0;
  44             }
  45         }
  46
  47         /// <summary>
  48         /// Returns false if left and right point at the same memory and have the same length.  Note that
  49         /// this does *not* check to see if the *contents* are equal.
  50         /// </summary>
  51         public static bool operator !=(Span<T> left, Span<T> right) => !(left == right);
  52
  53         /// <summary>
  54         /// This method is not supported as spans cannot be boxed. To compare two spans, use operator==.
  55         /// <exception cref="System.NotSupportedException">
  56         /// Always thrown by this method.
  57         /// </exception>
  58         /// </summary>
  59         [Obsolete("Equals() on Span will always throw an exception. Use == instead.")]
  60         [EditorBrowsable(EditorBrowsableState.Never)]
  61         public override bool Equals(object obj)
  62         {
  63             throw new NotSupportedException(SR.NotSupported_CannotCallEqualsOnSpan);
  64         }
  65
  66         /// <summary>
  67         /// This method is not supported as spans cannot be boxed.
  68         /// <exception cref="System.NotSupportedException">
  69         /// Always thrown by this method.
  70         /// </exception>
  71         /// </summary>
  72         [Obsolete("GetHashCode() on Span will always throw an exception.")]
  73         [EditorBrowsable(EditorBrowsableState.Never)]
  74         public override int GetHashCode()
  75         {
  76             throw new NotSupportedException(SR.NotSupported_CannotCallGetHashCodeOnSpan);
  77         }
  78
  79         /// <summary>
  80         /// Defines an implicit conversion of an array to a <see cref="Span{T}"/>
  81         /// </summary>
  82         public static implicit operator Span<T>(T[] array) => new Span<T>(array);
  83
  84         /// <summary>
  85         /// Defines an implicit conversion of a <see cref="ArraySegment{T}"/> to a <see cref="Span{T}"/>
  86         /// </summary>
  87         public static implicit operator Span<T>(ArraySegment<T> segment)
  88             => new Span<T>(segment.Array, segment.Offset, segment.Count);
  89
  90         /// <summary>
  91         /// Returns an empty <see cref="Span{T}"/>
  92         /// </summary>
  93         public static Span<T> Empty => default;
  94
  95         /// <summary>Gets an enumerator for this span.</summary>
  96         public Enumerator GetEnumerator() => new Enumerator(this);
  97
  98         /// <summary>Enumerates the elements of a <see cref="Span{T}"/>.</summary>
  99         public ref struct Enumerator
 100         {
 101             /// <summary>The span being enumerated.</summary>
 102             private readonly Span<T> _span;
 103             /// <summary>The next index to yield.</summary>
 104             private int _index;
 105
 106             /// <summary>Initialize the enumerator.</summary>
 107             /// <param name="span">The span to enumerate.</param>
 108             [MethodImpl(MethodImplOptions.AggressiveInlining)]
 109             internal Enumerator(Span<T> span)
 110             {
 111                 _span = span;
 112                 _index = -1;
 113             }
 114
 115             /// <summary>Advances the enumerator to the next element of the span.</summary>
 116             [MethodImpl(MethodImplOptions.AggressiveInlining)]
 117             public bool MoveNext()
 118             {
 119                 int index = _index + 1;
 120                 if (index < _span.Length)
 121                 {
 122                     _index = index;
 123                     return true;
 124                 }
 125
 126                 return false;
 127             }
 128
 129             /// <summary>Gets the element at the current position of the enumerator.</summary>
 130             public ref T Current
 131             {
 132                 [MethodImpl(MethodImplOptions.AggressiveInlining)]
 133                 get => ref _span[_index];
 134             }
 135         }
 136     }
 137 }