ArraySegment<T> Struct

Definition

Delimits a section of a one-dimensional array.

generic <typename T>
public value class ArraySegment : System::Collections::Generic::ICollection<T>, System::Collections::Generic::IEnumerable<T>, System::Collections::Generic::IList<T>, System::Collections::Generic::IReadOnlyCollection<T>, System::Collections::Generic::IReadOnlyList<T>
[System.Serializable]
public struct ArraySegment<T> : System.Collections.Generic.ICollection<T>, System.Collections.Generic.IEnumerable<T>, System.Collections.Generic.IList<T>, System.Collections.Generic.IReadOnlyCollection<T>, System.Collections.Generic.IReadOnlyList<T>
type ArraySegment<'T> = struct
    interface IList<'T>
    interface IReadOnlyList<'T>
    interface ICollection<'T>
    interface seq<'T>
    interface IEnumerable
    interface IReadOnlyCollection<'T>
Public Structure ArraySegment(Of T)
Implements ICollection(Of T), IEnumerable(Of T), IList(Of T), IReadOnlyCollection(Of T), IReadOnlyList(Of T)

Type Parameters

T

The type of the elements in the array segment.

Inheritance
ArraySegment<T>
Attributes
Implements

Examples

The following code example passes an ArraySegment<T> structure to a method.

using namespace System;


namespace Sample
{
    public ref class SampleArray  
    {
    public:
        static void Work()  
        {

            // Create and initialize a new string array.
            array <String^>^ words = {"The", "quick", "brown",
                "fox", "jumps", "over", "the", "lazy", "dog"};

            // Display the initial contents of the array.
            Console::WriteLine("The first array segment"
                " (with all the array's elements) contains:");
            PrintIndexAndValues(words);

            // Define an array segment that contains the entire array.
            ArraySegment<String^> segment(words);
            
            // Display the contents of the ArraySegment.
            Console::WriteLine("The first array segment"
                " (with all the array's elements) contains:");
            PrintIndexAndValues(segment);

            // Define an array segment that contains the middle five 
            // values of the array.
            ArraySegment<String^> middle(words, 2, 5);
            
            // Display the contents of the ArraySegment.
            Console::WriteLine("The second array segment"
                " (with the middle five elements) contains:");
            PrintIndexAndValues(middle);

            // Modify the fourth element of the first array 
            // segment
            segment.Array[3] = "LION";

            // Display the contents of the second array segment 
            // middle. Note that the value of its second element 
            // also changed.
            Console::WriteLine("After the first array segment"
                " is modified,the second array segment"
                " now contains:");
            PrintIndexAndValues(middle);
            Console::ReadLine();
        }

        static void PrintIndexAndValues(ArraySegment<String^>^ segment)  
        {
            for (int i = segment->Offset; 
                i < (segment->Offset + segment->Count); i++)  
            {
                Console::WriteLine("   [{0}] : {1}", i,
                    segment->Array[i]);
            }
            Console::WriteLine();
        }

        static void PrintIndexAndValues(array<String^>^ words) 
        {
            for (int i = 0; i < words->Length; i++)  
            {
                Console::WriteLine("   [{0}] : {1}", i,
                    words[i]);
            }
            Console::WriteLine();
        }
    };
}

int main()
{
    Sample::SampleArray::Work();
    return 0; 
}


    /* 
    This code produces the following output.

    The original array initially contains:
    [0] : The
    [1] : quick
    [2] : brown
    [3] : fox
    [4] : jumps
    [5] : over
    [6] : the
    [7] : lazy
    [8] : dog

    The first array segment (with all the array's elements) contains:
    [0] : The
    [1] : quick
    [2] : brown
    [3] : fox
    [4] : jumps
    [5] : over
    [6] : the
    [7] : lazy
    [8] : dog

    The second array segment (with the middle five elements) contains:
    [2] : brown
    [3] : fox
    [4] : jumps
    [5] : over
    [6] : the

    After the first array segment is modified, the second array segment now contains:
    [2] : brown
    [3] : LION
    [4] : jumps
    [5] : over
    [6] : the

    */

using System;

public class SamplesArray  {
 
   public static void Main()  {
 
      // Create and initialize a new string array.
      String[] myArr = { "The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog" };
 
      // Display the initial contents of the array.
      Console.WriteLine( "The original array initially contains:" );
      PrintIndexAndValues( myArr );

      // Define an array segment that contains the entire array.
      ArraySegment<String> myArrSegAll = new ArraySegment<String>( myArr );

      // Display the contents of the ArraySegment.
      Console.WriteLine( "The first array segment (with all the array's elements) contains:" );
      PrintIndexAndValues( myArrSegAll );

      // Define an array segment that contains the middle five values of the array.
      ArraySegment<String> myArrSegMid = new ArraySegment<String>( myArr, 2, 5 );

      // Display the contents of the ArraySegment.
      Console.WriteLine( "The second array segment (with the middle five elements) contains:" );
      PrintIndexAndValues( myArrSegMid );

      // Modify the fourth element of the first array segment myArrSegAll.
      myArrSegAll.Array[3] = "LION";

      // Display the contents of the second array segment myArrSegMid.
      // Note that the value of its second element also changed.
      Console.WriteLine( "After the first array segment is modified, the second array segment now contains:" );
      PrintIndexAndValues( myArrSegMid );

   }
 
   public static void PrintIndexAndValues( ArraySegment<String> arrSeg )  {
      for ( int i = arrSeg.Offset; i < (arrSeg.Offset + arrSeg.Count); i++ )  {
         Console.WriteLine( "   [{0}] : {1}", i, arrSeg.Array[i] );
      }
      Console.WriteLine();
   }

   public static void PrintIndexAndValues( String[] myArr )  {
      for ( int i = 0; i < myArr.Length; i++ )  {
         Console.WriteLine( "   [{0}] : {1}", i, myArr[i] );
      }
      Console.WriteLine();
   }

}


/* 
This code produces the following output.

The original array initially contains:
   [0] : The
   [1] : quick
   [2] : brown
   [3] : fox
   [4] : jumps
   [5] : over
   [6] : the
   [7] : lazy
   [8] : dog

The first array segment (with all the array's elements) contains:
   [0] : The
   [1] : quick
   [2] : brown
   [3] : fox
   [4] : jumps
   [5] : over
   [6] : the
   [7] : lazy
   [8] : dog

The second array segment (with the middle five elements) contains:
   [2] : brown
   [3] : fox
   [4] : jumps
   [5] : over
   [6] : the

After the first array segment is modified, the second array segment now contains:
   [2] : brown
   [3] : LION
   [4] : jumps
   [5] : over
   [6] : the

*/

Public Class SamplesArray

    Public Shared Sub Main()

        ' Create and initialize a new string array.
        Dim myArr As String() =  {"The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog"}

        ' Display the initial contents of the array.
        Console.WriteLine("The original array initially contains:")
        PrintIndexAndValues(myArr)

        ' Define an array segment that contains the entire array.
        Dim myArrSegAll As New ArraySegment(Of String)(myArr)

        ' Display the contents of the ArraySegment.
        Console.WriteLine("The first array segment (with all the array's elements) contains:")
        PrintIndexAndValues(myArrSegAll)

        ' Define an array segment that contains the middle five values of the array.
        Dim myArrSegMid As New ArraySegment(Of String)(myArr, 2, 5)

        ' Display the contents of the ArraySegment.
        Console.WriteLine("The second array segment (with the middle five elements) contains:")
        PrintIndexAndValues(myArrSegMid)

        ' Modify the fourth element of the first array segment myArrSegAll.
        myArrSegAll.Array(3) = "LION"

        ' Display the contents of the second array segment myArrSegMid.
        ' Note that the value of its second element also changed.
        Console.WriteLine("After the first array segment is modified, the second array segment now contains:")
        PrintIndexAndValues(myArrSegMid)

    End Sub

    Public Shared Sub PrintIndexAndValues(arrSeg As ArraySegment(Of String))
        Dim i As Integer
        For i = arrSeg.Offset To (arrSeg.Offset + arrSeg.Count - 1)
            Console.WriteLine("   [{0}] : {1}", i, arrSeg.Array(i))
        Next i
        Console.WriteLine()
    End Sub

    Public Shared Sub PrintIndexAndValues(myArr as String())
        Dim i As Integer
        For i = 0 To (myArr.Length - 1)
            Console.WriteLine("   [{0}] : {1}", i, myArr(i))
        Next i
        Console.WriteLine()
    End Sub

End Class


'This code produces the following output.
'
'The original array initially contains:
'   [0] : The
'   [1] : quick
'   [2] : brown
'   [3] : fox
'   [4] : jumps
'   [5] : over
'   [6] : the
'   [7] : lazy
'   [8] : dog
'
'The first array segment (with all the array's elements) contains:
'   [0] : The
'   [1] : quick
'   [2] : brown
'   [3] : fox
'   [4] : jumps
'   [5] : over
'   [6] : the
'   [7] : lazy
'   [8] : dog
'
'The second array segment (with the middle five elements) contains:
'   [2] : brown
'   [3] : fox
'   [4] : jumps
'   [5] : over
'   [6] : the
'
'After the first array segment is modified, the second array segment now contains:
'   [2] : brown
'   [3] : LION
'   [4] : jumps
'   [5] : over
'   [6] : the

Remarks

ArraySegment<T> is a wrapper around an array that delimits a range of elements in that array. Multiple ArraySegment<T> instances can refer to the same original array and can overlap. The original array must be one-dimensional and must have zero-based indexing.

Note

ArraySegment<T> implements the IReadOnlyCollection<T> interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the ArraySegment<T> structure did not implement this interface.

The ArraySegment<T> structure is useful whenever the elements of an array will be manipulated in distinct segments. For example:

  • You can pass an ArraySegment<T> object that represents only a portion of an array as an argument to a method, rather than call a relatively expensive method like Copy to pass a copy of a portion of an array.

  • In a multithreaded app, you can use the ArraySegment<T> structure to have each thread operate on only a portion of the array.

  • For task-based asynchronous operations, you can use an ArraySegment<T> object to ensure that each task operates on a distinct segment of the array. The following example divides an array into individual segments with up to ten elements. Each element in the segment is multiplied by its segment number. The result shows that using the ArraySegment<T> class to manipulate elements in this way changes the values of its underlying array.

    using System;
    using System.Collections.Generic;
    using System.Threading.Tasks;
    
    public class Example
    {
       private const int segmentSize = 10;
       
       public static async Task Main()
       {
          List<Task> tasks = new List<Task>();
    
          // Create array.
          int[] arr = new int[50];
          for (int ctr = 0; ctr <= arr.GetUpperBound(0); ctr++)
             arr[ctr] = ctr + 1;
    
          // Handle array in segments of 10.
          for (int ctr = 1; ctr <= Math.Ceiling(((double)arr.Length)/segmentSize); ctr++) {
             int multiplier = ctr;
             int elements = (multiplier - 1) * 10 + segmentSize > arr.Length ?
                             arr.Length - (multiplier - 1) * 10 : segmentSize;
             ArraySegment<int> segment = new ArraySegment<int>(arr, (ctr - 1) * 10, elements);
             tasks.Add(Task.Run( () => { IList<int> list = (IList<int>) segment;
                                         for (int index = 0; index < list.Count; index++)
                                            list[index] = list[index] * multiplier;
                                       } ));
          }
          try {
             await Task.WhenAll(tasks.ToArray());
             int elementsShown = 0;
             foreach (var value in arr) {
                Console.Write("{0,3} ", value);
                elementsShown++;
                if (elementsShown % 18 == 0)
                   Console.WriteLine();
             }
          }
          catch (AggregateException e) {
             Console.WriteLine("Errors occurred when working with the array:");
             foreach (var inner in e.InnerExceptions)
                Console.WriteLine("{0}: {1}", inner.GetType().Name, inner.Message);
          }
       }
    }
    // The example displays the following output:
    //      1   2   3   4   5   6   7   8   9  10  22  24  26  28  30  32  34  36
    //     38  40  63  66  69  72  75  78  81  84  87  90 124 128 132 136 140 144
    //    148 152 156 160 205 210 215 220 225 230 235 240 245 250
    
    Imports System.Collections.Generic
    Imports System.Threading.Tasks
    
    Module Example
      Private Const SegmentSize As Integer = 10
      
       Public Sub Main()
          Dim tasks As New List(Of Task)
          
           ' Create array.
          Dim arr(49) As Integer
          For ctr As Integer = 0 To arr.GetUpperBound(0)
             arr(ctr) = ctr + 1
          Next
    
          ' Handle array in segments of 10.
          For ctr As Integer = 1 To CInt(Math.Ceiling(arr.Length / segmentSize))
             Dim multiplier As Integer = ctr
             Dim elements As Integer = If((multiplier - 1) * 10 + segmentSize > arr.Length,
                                          arr.Length - (multiplier - 1) * 10,
                                          segmentSize)
             Dim segment As New ArraySegment(Of Integer)(arr, (ctr - 1) * 10, elements)
             tasks.Add(Task.Run( Sub()
                                    Dim list As IList(Of Integer) = CType(segment, IList(Of Integer))
                                    For index As Integer = 0 To list.Count - 1
                                       list(index) = list(index) * multiplier
                                    Next
                                 End Sub ))
          Next
          Try
             Task.WaitAll(tasks.ToArray())
             Dim elementsShown As Integer = 0
             For Each value In arr
                Console.Write("{0,3} ", value)
                elementsShown += 1
                If elementsShown Mod 18 = 0 Then Console.WriteLine()
             Next
          Catch e As AggregateException
             Console.WriteLine("Errors occurred when working with the array:")
             For Each inner As Exception In e.InnerExceptions
                Console.WriteLine("{0}: {1}", inner.GetType().Name, inner.Message)
             Next
          End Try
       End Sub
    End Module
    ' The example displays the following output:
    '         1   2   3   4   5   6   7   8   9  10  22  24  26  28  30  32  34  36
    '        38  40  63  66  69  72  75  78  81  84  87  90 124 128 132 136 140 144
    '       148 152 156 160 205 210 215 220 225 230 235 240 245 250
    

Note, however, that although the ArraySegment<T> structure can be used to divide an array into distinct segments, the segments are not completely independent of one another. The Array property returns the entire original array, not a copy of the array; therefore, changes made to the array returned by the Array property are made to the original array. If this is undesirable, you should perform operations on a copy of the array, rather than an ArraySegment<T> object that represents a portion of the array.

The Equals method and the equality and inequality operators test for reference equality when they compare two ArraySegment<T> objects. For two ArraySegment<T> objects to be considered equal, they must meet all of the following conditions:

  • Reference the same array.

  • Begin at the same index in the array.

  • Have the same number of elements.

If you want to retrieve an element by its index in the ArraySegment<T> object, you must cast it to an IList<T> object and retrieve it or modify it by using the IList<T>.Item[Int32] property. The following example retrieves the element in an ArraySegment<T> object that delimits a section of a string array.

using System;
using System.Collections.Generic;

public class Example
{
   public static void Main()
   {
      String[] names = { "Adam", "Bruce", "Charles", "Daniel", 
                         "Ebenezer", "Francis", "Gilbert", 
                         "Henry", "Irving", "John", "Karl",
                         "Lucian", "Michael" };
      var partNames = new ArraySegment<String>(names, 2, 5);
      
      // Cast the ArraySegment object to an IList<String> and enumerate it.
      var list = (IList<String>) partNames;
      for (int ctr = 0; ctr <= list.Count - 1; ctr++)
         Console.WriteLine(list[ctr]);
   }
}
// The example displays the following output:
//    Charles
//    Daniel
//    Ebenezer
//    Francis
//    Gilbert
Imports System.Collections.Generic

Module Example
   Public Sub Main()
      Dim names() As String = { "Adam", "Bruce", "Charles", "Daniel", 
                                "Ebenezer", "Francis", "Gilbert", 
                                "Henry", "Irving", "John", "Karl",
                                "Lucian", "Michael" }
      Dim partNames As New ArraySegment(Of String)(names, 2, 5)
      
      ' Cast the ArraySegment object to an IList<String> and enumerate it.
      Dim list = CType(partNames, IList(Of String))
      For ctr As Integer = 0 To list.Count - 1
         Console.WriteLine(list(ctr))
      Next     
   End Sub
End Module
' The example displays the following output:
'    Charles
'    Daniel
'    Ebenezer
'    Francis
'    Gilbert

Constructors

ArraySegment<T>(T[])

Initializes a new instance of the ArraySegment<T> structure that delimits all the elements in the specified array.

ArraySegment<T>(T[], Int32, Int32)

Initializes a new instance of the ArraySegment<T> structure that delimits the specified range of the elements in the specified array.

Properties

Array

Gets the original array containing the range of elements that the array segment delimits.

Count

Gets the number of elements in the range delimited by the array segment.

Empty

Represents the empty array segment. This field is read-only.

Item[Int32]

Gets or sets the element at the specified index.

Offset

Gets the position of the first element in the range delimited by the array segment, relative to the start of the original array.

Methods

CopyTo(ArraySegment<T>)

Copies the contents of this instance into the specified destination array segment of the same type T.

CopyTo(T[])

Copies the contents of this instance into the specified destination array of the same type T.

CopyTo(T[], Int32)

Copies the contents of this instance into the specified destination array of the same type T, starting at the specified destination index.

Equals(ArraySegment<T>)

Determines whether the specified ArraySegment<T> structure is equal to the current instance.

Equals(Object)

Determines whether the specified object is equal to the current instance.

GetEnumerator()

Returns an enumerator that can be used to iterate through the array segment.

GetHashCode()

Returns the hash code for the current instance.

Slice(Int32)

Forms a slice out of the current array segment starting at the specified index.

Slice(Int32, Int32)

Forms a slice of the specified length out of the current array segment starting at the specified index.

ToArray()

Copies the contents of this array segment into a new array.

Operators

Equality(ArraySegment<T>, ArraySegment<T>)

Indicates whether two ArraySegment<T> structures are equal.

Implicit(T[] to ArraySegment<T>)

Defines an implicit conversion of an array of type T to an array segment of type T.

Inequality(ArraySegment<T>, ArraySegment<T>)

Indicates whether two ArraySegment<T> structures are unequal.

Explicit Interface Implementations

ICollection<T>.Add(T)

Throws a NotSupportedException exception in all cases.

ICollection<T>.Clear()

Throws a NotSupportedException exception in all cases.

ICollection<T>.Contains(T)

Determines whether the array segment contains a specific value.

ICollection<T>.CopyTo(T[], Int32)

Copies the elements of the array segment to an array, starting at the specified array index.

ICollection<T>.IsReadOnly

Gets a value that indicates whether the array segment is read-only.

ICollection<T>.Remove(T)

Throws a NotSupportedException exception in all cases.

IEnumerable.GetEnumerator()

Returns an enumerator that iterates through an array segment.

IEnumerable<T>.GetEnumerator()

Returns an enumerator that iterates through the array segment.

IList<T>.IndexOf(T)

Determines the index of a specific item in the array segment.

IList<T>.Insert(Int32, T)

Throws a NotSupportedException exception in all cases.

IList<T>.Item[Int32]

Gets or sets the element at the specified index.

IList<T>.RemoveAt(Int32)

Throws a NotSupportedException exception in all cases.

IReadOnlyList<T>.Item[Int32]

Gets the element at the specified index of the array segment.

Extension Methods

CopyToDataTable<T>(IEnumerable<T>)

Returns a DataTable that contains copies of the DataRow objects, given an input IEnumerable<T> object where the generic parameter T is DataRow.

CopyToDataTable<T>(IEnumerable<T>, DataTable, LoadOption)

Copies DataRow objects to the specified DataTable, given an input IEnumerable<T> object where the generic parameter T is DataRow.

CopyToDataTable<T>(IEnumerable<T>, DataTable, LoadOption, FillErrorEventHandler)

Copies DataRow objects to the specified DataTable, given an input IEnumerable<T> object where the generic parameter T is DataRow.

Cast<TResult>(IEnumerable)

Casts the elements of an IEnumerable to the specified type.

OfType<TResult>(IEnumerable)

Filters the elements of an IEnumerable based on a specified type.

AsParallel(IEnumerable)

Enables parallelization of a query.

AsQueryable(IEnumerable)

Converts an IEnumerable to an IQueryable.

AsMemory<T>(ArraySegment<T>)

Creates a new memory region over the portion of the target array segment.

AsMemory<T>(ArraySegment<T>, Int32)

Creates a new memory region over the portion of the target array segment starting at a specified position to the end of the segment.

AsMemory<T>(ArraySegment<T>, Int32, Int32)

Creates a new memory region over the portion of the target array segment beginning at a specified position with a specified length.

AsSpan<T>(ArraySegment<T>)

Creates a new span over a target array segment.

AsSpan<T>(ArraySegment<T>, Index)

Creates a new span over a portion of the target array segment beginning at a specified index and ending at the end of the segment.

AsSpan<T>(ArraySegment<T>, Int32)

Creates a new span over a portion of a target array segment from a specified position to the end of the segment.

AsSpan<T>(ArraySegment<T>, Int32, Int32)

Creates a new span over a portion of a target array segment from a specified position for a specified length.

AsSpan<T>(ArraySegment<T>, Range)

Creates a new span over a portion of a target array segment using the range start and end indexes.

Ancestors<T>(IEnumerable<T>)

Returns a collection of elements that contains the ancestors of every node in the source collection.

Ancestors<T>(IEnumerable<T>, XName)

Returns a filtered collection of elements that contains the ancestors of every node in the source collection. Only elements that have a matching XName are included in the collection.

DescendantNodes<T>(IEnumerable<T>)

Returns a collection of the descendant nodes of every document and element in the source collection.

Descendants<T>(IEnumerable<T>)

Returns a collection of elements that contains the descendant elements of every element and document in the source collection.

Descendants<T>(IEnumerable<T>, XName)

Returns a filtered collection of elements that contains the descendant elements of every element and document in the source collection. Only elements that have a matching XName are included in the collection.

Elements<T>(IEnumerable<T>)

Returns a collection of the child elements of every element and document in the source collection.

Elements<T>(IEnumerable<T>, XName)

Returns a filtered collection of the child elements of every element and document in the source collection. Only elements that have a matching XName are included in the collection.

InDocumentOrder<T>(IEnumerable<T>)

Returns a collection of nodes that contains all nodes in the source collection, sorted in document order.

Nodes<T>(IEnumerable<T>)

Returns a collection of the child nodes of every document and element in the source collection.

Remove<T>(IEnumerable<T>)

Removes every node in the source collection from its parent node.

Applies to

See also