Span<T> Span<T> Span<T> Span<T> Struct

Definición

Proporciona una representación para tipos y memoria de una región contigua de memoria arbitraria.Provides a type- and memory-safe representation of a contiguous region of arbitrary memory.

generic <typename T>
public value class Span
public struct Span<T>
type Span<'T> = struct
Public Structure Span(Of T)

Parámetros de tipo

T

El tipo de elementos en el Span<T>.The type of items in the Span<T>.

Herencia

Comentarios

Span<T> es un ref struct que se asigna en la pila, en lugar de en el montón administrado.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Tipos de struct ref tienen un número de restricciones para asegurarse de que no se puede promocionar al montón administrado, incluidos los que no se puede realizar la conversión boxing, no se puede asignar a variables de tipo Object, dynamic o a cualquier tipo de interfaz no pueden ser campos de un tipo de referencia y no se puede usar a través de await y yield los límites.Ref struct types have a number of restrictions to ensure that they cannot be promoted to the managed heap, including that they can't be boxed, they can't be assigned to variables of type Object, dynamic or to any interface type, they can't be fields in a reference type, and they can't be used across await and yield boundaries. Además, las llamadas a dos métodos, Equals(Object) y GetHashCode, producir una NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Importante

Porque es un tipo de solo pila Span<T> no es adecuado para muchos escenarios que requieren almacenar referencias a los búferes en el montón.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Esto es así, por ejemplo, de rutinas que realizan llamadas de método asincrónico.This is true, for example, of routines that make asynchronous method calls. Para estos escenarios, puede usar el complementarias System.Memory<T> y System.ReadOnlyMemory<T> tipos.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Para los intervalos que representan las estructuras inmutables o de solo lectura, utilice System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Intervalo<T > y la memoriaSpan<T> and memory

Un Span<T> representa una región contigua de memoria arbitraria.A Span<T> represents a contiguous region of arbitrary memory. Un Span<T> instancia a menudo se usa para contener los elementos de una matriz o una parte de una matriz.A Span<T> instance is often used to hold the elements of an array or a portion of an array. A diferencia de una matriz, sin embargo, un Span<T> instancia puede apuntar a la memoria administrada, memoria nativa, o memoria administrada en la pila.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. En el ejemplo siguiente se crea un Span<Byte> desde una matriz:The following example creates a Span<Byte> from an array:

// Create a span over an array.
var array = new byte[100];
var arraySpan = new Span<byte>(array);

byte data = 0;
for (int ctr = 0; ctr < arraySpan.Length; ctr++)
   arraySpan[ctr] = data++;

int arraySum = 0;
foreach (var value in array)
   arraySum += value;

Console.WriteLine($"The sum is {arraySum}");
// Output:  The sum is 4950

En el ejemplo siguiente se crea un Span<Byte> de 100 bytes de memoria nativa:The following example creates a Span<Byte> from 100 bytes of native memory:

// Create a span from native memory.
var native = Marshal.AllocHGlobal(100);
Span<byte> nativeSpan;
unsafe
{
    nativeSpan = new Span<byte>(native.ToPointer(), 100);
}
byte data = 0;
for (int ctr = 0; ctr < nativeSpan.Length; ctr++)
   nativeSpan[ctr] = data++;

int nativeSum = 0;
foreach (var value in nativeSpan)    
   nativeSum += value;

Console.WriteLine($"The sum is {nativeSum}");    
Marshal.FreeHGlobal(native);
// Output:  The sum is 4950

En el ejemplo siguiente se usa el C# stackalloc palabra clave para asignar 100 bytes de memoria en la pila:The following example uses the C# stackalloc keyword to allocate 100 bytes of memory on the stack:

// Create a span on the stack.
byte data = 0;
Span<byte> stackSpan = stackalloc byte[100];
for (int ctr = 0; ctr < stackSpan.Length; ctr++)
   stackSpan[ctr] = data++;

int stackSum = 0;
foreach (var value in stackSpan)    
   stackSum += value;

Console.WriteLine($"The sum is {stackSum}");    
// Output:  The sum is 4950

Dado que Span<T> es una abstracción sobre un bloque arbitrario de memoria, los métodos de la Span<T> clases y métodos con Span<T> parámetros operan en cualquier Span<T> objeto independientemente del tipo de memoria encapsula.Because Span<T> is an abstraction over an arbitrary block of memory, methods of the Span<T> class and methods with Span<T> parameters operate on any Span<T> object regardless of the kind of memory it encapsulates. Por ejemplo, cada una de las secciones de código independientes que inicializar el intervalo y calcular que la suma de sus elementos se puede cambiar en la inicialización única y métodos de cálculo, como en el ejemplo siguiente se muestra:For example, each of the separate sections of code that initialize the span and calculate the sum of its elements can be changed into single initialization and calculation methods, as the following example illustrates:

public static void WorkWithSpans()
{
    // Create a span over an array.
    var array = new byte[100];
    var arraySpan = new Span<byte>(array);
    
    InitializeSpan(arraySpan);
    Console.WriteLine($"The sum is {ComputeSum(arraySpan):N0}");    

    // Create an array from native memory.
    var native = Marshal.AllocHGlobal(100);
    Span<byte> nativeSpan;
    unsafe 
    {
        nativeSpan = new Span<byte>(native.ToPointer(), 100);
    }

    InitializeSpan(nativeSpan);
    Console.WriteLine($"The sum is {ComputeSum(arraySpan):N0}");    
    
    Marshal.FreeHGlobal(native);

    // Create a span on the stack.
    Span<byte> stackSpan = stackalloc byte[100];

    InitializeSpan(stackSpan);
    Console.WriteLine($"The sum is {ComputeSum(arraySpan):N0}");    
}        

public static void InitializeSpan(Span<byte> span)
{
    byte value = 0;
    for (int ctr = 0; ctr < span.Length; ctr++)
        span[ctr] = value++;
}

public static int ComputeSum(Span<byte> span)
{
    int sum = 0;
    foreach (var value in span)
       sum += value;

    return sum;
}
// The example displays the following output:
//    The sum is 4,950
//    The sum is 4,950
//    The sum is 4,950

Intervalo<T > y matricesSpan<T> and arrays

Cuando se ajusta una matriz, Span<T> puede encapsular la matriz completa, como lo hacía en los ejemplos de la intervalo<T > y la memoria sección.When it wraps an array, Span<T> can wrap an entire array, as it did in the examples in the Span<T> and memory section. Ya que admite la segmentación, Span<T> también puede señalar a un intervalo contiguo dentro de la matriz.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

El ejemplo siguiente crea un segmento de los elementos de cinco centrales de una matriz de enteros de 10 elementos.The following example creates a slice of the middle five elements of a 10-element integer array. Tenga en cuenta que el código duplica los valores de cada entero en el segmento.Note that the code doubles the values of each integer in the slice. Como se muestra el resultado, los cambios realizados por el intervalo se reflejan en los valores de la matriz.As the output shows, the changes made by the span are reflected in the values of the array.

using System;

namespace span
{
    class Program
    {
        static void Main(string[] args)
        {
            var array = new int[] { 2, 4, 6, 8, 10, 12, 14, 16, 18, 20 };
            var slice = new Span<int>(array, 2, 5);
            for (int ctr = 0; ctr < slice.Length; ctr++)
               slice[ctr] *= 2;
            
            // Examine the original array values.
            foreach (var value in array)
                Console.Write($"{value}  ");
            Console.WriteLine();
        }
    }
}
// The example displays the following output:
//      2  4  12  16  20  24  28  16  18  20

Intervalo<T > y los segmentosSpan<T> and slices

Span<T> incluye dos sobrecargas de los Slice método que forman un segmento fuera del intervalo actual que se inicia en el índice especificado.Span<T> includes two overloads of the Slice method that form a slice out of the current span that starts at a specified index. Esto permite tratar los datos en un Span<T> como un conjunto de fragmentos lógicos que se pueden procesar según sea necesario por las partes de una canalización de procesamiento de datos con un impacto mínimo en el rendimiento.This makes it possible to treat the data in a Span<T> as a set of logical chunks that can be processed as needed by portions of a data processing pipeline with minimal performance impact. Por ejemplo, puesto que los protocolos de servidor moderno son a menudo basado en texto, manipulación de cadenas y las subcadenas es especialmente importante.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. En el String clase, el método principal para extraer subcadenas es Substring.In the String class, the major method for extracting substrings is Substring. Para las canalizaciones de datos que se basan en la manipulación de cadenas amplia, su uso ofrece algunos disminuciones de rendimiento, ya que:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Crea una nueva cadena que contenga la subcadena.Creates a new string to hold the substring.

  2. Copia un subconjunto de los caracteres de la cadena original a la nueva cadena.Copies a subset of the characters from the original string to the new string.

Esta operación de asignación y la copia se puede eliminar mediante el uso Span<T> o ReadOnlySpan<T>, tal y como se muestra en el ejemplo siguiente:This allocation and copy operation can be eliminated by using either Span<T> or ReadOnlySpan<T>, as the following example shows:

using System;

class Program
{
    static void Main()
    {
        string contentLength = "Content-Length: 132";
        var length = GetContentLength(contentLength.ToCharArray());	
        Console.WriteLine($"Content length: {length}"); 
    }

    private static int GetContentLength(ReadOnlySpan<char> span)
    {
        var slice = span.Slice(16);
	    return int.Parse(slice);	
    }
}
// Output:
//      Content length: 132

Constructores

Span<T>(T[]) Span<T>(T[]) Span<T>(T[]) Span<T>(T[])

Crea un nuevo objeto Span<T> a través de la totalidad de una matriz especificada.Creates a new Span<T> object over the entirety of a specified array.

Span<T>(Void*, Int32) Span<T>(Void*, Int32) Span<T>(Void*, Int32) Span<T>(Void*, Int32)

Crea un objeto Span<T> a partir de un número especificado de elementos T desde una dirección de memoria especificada.Creates a new Span<T> object from a specified number of T elements starting at a specified memory address.

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

Crea un nuevo objeto Span<T> que incluye un número especificado de elementos de una matriz a partir de un índice especificado.Creates a new Span<T> object that includes a specified number of elements of an array starting at a specified index.

Propiedades

Empty Empty Empty Empty

Devuelve un objeto Span<T> vacío.Returns an empty Span<T> object.

IsEmpty IsEmpty IsEmpty IsEmpty

Devuelve un valor que indica si el elemento Span<T> actual está vacío.Returns a value that indicates whether the current Span<T> is empty.

Item[Range] Item[Range] Item[Range] Item[Range]
Item[Int32] Item[Int32] Item[Int32] Item[Int32]

Obtiene el elemento en el índice basado en cero especificado.Gets the element at the specified zero-based index.

Item[Index] Item[Index] Item[Index] Item[Index]
Length Length Length Length

Devuelve la longitud del intervalo actual.Returns the length of the current span.

Métodos

Clear() Clear() Clear() Clear()

Borra el contenido de este objeto Span<T>.Clears the contents of this Span<T> object.

CopyTo(Span<T>) CopyTo(Span<T>) CopyTo(Span<T>) CopyTo(Span<T>)

Copia el contenido de este elemento Span<T> en un elemento Span<T> de destino.Copies the contents of this Span<T> into a destination Span<T>.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

No se admiten llamadas a este método.Calls to this method are not supported.

Fill(T) Fill(T) Fill(T) Fill(T)

Rellena los elementos de este intervalo con un valor especificado.Fills the elements of this span with a specified value.

GetEnumerator() GetEnumerator() GetEnumerator() GetEnumerator()

Devuelve un enumerador para este elemento Span<T>.Returns an enumerator for this Span<T>.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Produce una excepción NotSupportedException.Throws a NotSupportedException.

GetPinnableReference() GetPinnableReference() GetPinnableReference() GetPinnableReference()

Devuelve una referencia al elemento de Span<T> en el índice cero.Returns a reference to the element of the Span<T> at index zero.

Slice(Index) Slice(Index) Slice(Index) Slice(Index)
Slice(Int32) Slice(Int32) Slice(Int32) Slice(Int32)

Forma un segmento fuera del intervalo actual que comienza en un índice especificado.Forms a slice out of the current span that begins at a specified index.

Slice(Range) Slice(Range) Slice(Range) Slice(Range)
Slice(Int32, Int32) Slice(Int32, Int32) Slice(Int32, Int32) Slice(Int32, Int32)

Forma un segmento fuera del intervalo actual a partir de un índice especificado durante una longitud determinada.Forms a slice out of the current span starting at a specified index for a specified length.

ToArray() ToArray() ToArray() ToArray()

Copia el contenido de este intervalo en una nueva matriz.Copies the contents of this span into a new array.

ToString() ToString() ToString() ToString()

Devuelve la representación en forma de cadena de este objeto Span<T>.Returns the string representation of this Span<T> object.

TryCopyTo(Span<T>) TryCopyTo(Span<T>) TryCopyTo(Span<T>) TryCopyTo(Span<T>)

Intenta copiar el elemento Span<T> actual en un destino Span<T> y devuelve un valor que indica si la operación de copia se ha realizado correctamente.Attempts to copy the current Span<T> to a destination Span<T> and returns a value that indicates whether the copy operation succeeded.

Operadores

Equality(Span<T>, Span<T>) Equality(Span<T>, Span<T>) Equality(Span<T>, Span<T>) Equality(Span<T>, Span<T>)

Devuelve un valor que indica si dos objetos Span<T> son iguales.Returns a value that indicates whether two Span<T> objects are equal.

Implicit(ArraySegment<T> to Span<T>) Implicit(ArraySegment<T> to Span<T>) Implicit(ArraySegment<T> to Span<T>) Implicit(ArraySegment<T> to Span<T>)

Define una conversión implícita de un elemento ArraySegment<T> en Span<T>.Defines an implicit conversion of an ArraySegment<T> to a Span<T>.

Implicit(Span<T> to ReadOnlySpan<T>) Implicit(Span<T> to ReadOnlySpan<T>) Implicit(Span<T> to ReadOnlySpan<T>) Implicit(Span<T> to ReadOnlySpan<T>)

Define una conversión implícita de un elemento Span<T> en ReadOnlySpan<T>.Defines an implicit conversion of a Span<T> to a ReadOnlySpan<T>.

Implicit(T[] to Span<T>) Implicit(T[] to Span<T>) Implicit(T[] to Span<T>) Implicit(T[] to Span<T>)

Define una conversión implícita de una matriz en Span<T>.Defines an implicit conversion of an array to a Span<T>.

Inequality(Span<T>, Span<T>) Inequality(Span<T>, Span<T>) Inequality(Span<T>, Span<T>) Inequality(Span<T>, Span<T>)

Devuelve un valor que indica si dos objetos Span<T> no son iguales.Returns a value that indicates whether two Span<T> objects are not equal.

Extension Methods

BinarySearch<T>(Span<T>, IComparable<T>) BinarySearch<T>(Span<T>, IComparable<T>) BinarySearch<T>(Span<T>, IComparable<T>) BinarySearch<T>(Span<T>, IComparable<T>)
BinarySearch<T,TComparer>(Span<T>, T, TComparer) BinarySearch<T,TComparer>(Span<T>, T, TComparer) BinarySearch<T,TComparer>(Span<T>, T, TComparer) BinarySearch<T,TComparer>(Span<T>, T, TComparer)
BinarySearch<T,TComparable>(Span<T>, TComparable) BinarySearch<T,TComparable>(Span<T>, TComparable) BinarySearch<T,TComparable>(Span<T>, TComparable) BinarySearch<T,TComparable>(Span<T>, TComparable)
EndsWith<T>(Span<T>, ReadOnlySpan<T>) EndsWith<T>(Span<T>, ReadOnlySpan<T>) EndsWith<T>(Span<T>, ReadOnlySpan<T>) EndsWith<T>(Span<T>, ReadOnlySpan<T>)
IndexOf<T>(Span<T>, T) IndexOf<T>(Span<T>, T) IndexOf<T>(Span<T>, T) IndexOf<T>(Span<T>, T)
IndexOf<T>(Span<T>, ReadOnlySpan<T>) IndexOf<T>(Span<T>, ReadOnlySpan<T>) IndexOf<T>(Span<T>, ReadOnlySpan<T>) IndexOf<T>(Span<T>, ReadOnlySpan<T>)
IndexOfAny<T>(Span<T>, T, T) IndexOfAny<T>(Span<T>, T, T) IndexOfAny<T>(Span<T>, T, T) IndexOfAny<T>(Span<T>, T, T)
IndexOfAny<T>(Span<T>, T, T, T) IndexOfAny<T>(Span<T>, T, T, T) IndexOfAny<T>(Span<T>, T, T, T) IndexOfAny<T>(Span<T>, T, T, T)
IndexOfAny<T>(Span<T>, ReadOnlySpan<T>) IndexOfAny<T>(Span<T>, ReadOnlySpan<T>) IndexOfAny<T>(Span<T>, ReadOnlySpan<T>) IndexOfAny<T>(Span<T>, ReadOnlySpan<T>)
LastIndexOf<T>(Span<T>, T) LastIndexOf<T>(Span<T>, T) LastIndexOf<T>(Span<T>, T) LastIndexOf<T>(Span<T>, T)
LastIndexOf<T>(Span<T>, ReadOnlySpan<T>) LastIndexOf<T>(Span<T>, ReadOnlySpan<T>) LastIndexOf<T>(Span<T>, ReadOnlySpan<T>) LastIndexOf<T>(Span<T>, ReadOnlySpan<T>)
LastIndexOfAny<T>(Span<T>, T, T) LastIndexOfAny<T>(Span<T>, T, T) LastIndexOfAny<T>(Span<T>, T, T) LastIndexOfAny<T>(Span<T>, T, T)
LastIndexOfAny<T>(Span<T>, T, T, T) LastIndexOfAny<T>(Span<T>, T, T, T) LastIndexOfAny<T>(Span<T>, T, T, T) LastIndexOfAny<T>(Span<T>, T, T, T)
LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>) LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>) LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>) LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>)
Overlaps<T>(Span<T>, ReadOnlySpan<T>) Overlaps<T>(Span<T>, ReadOnlySpan<T>) Overlaps<T>(Span<T>, ReadOnlySpan<T>) Overlaps<T>(Span<T>, ReadOnlySpan<T>)
Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32) Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32) Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32) Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32)
Reverse<T>(Span<T>) Reverse<T>(Span<T>) Reverse<T>(Span<T>) Reverse<T>(Span<T>)
SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>) SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>) SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>) SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>)
SequenceEqual<T>(Span<T>, ReadOnlySpan<T>) SequenceEqual<T>(Span<T>, ReadOnlySpan<T>) SequenceEqual<T>(Span<T>, ReadOnlySpan<T>) SequenceEqual<T>(Span<T>, ReadOnlySpan<T>)
StartsWith<T>(Span<T>, ReadOnlySpan<T>) StartsWith<T>(Span<T>, ReadOnlySpan<T>) StartsWith<T>(Span<T>, ReadOnlySpan<T>) StartsWith<T>(Span<T>, ReadOnlySpan<T>)

Se aplica a