Span<T> Estructura

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

Tipo de elementos del Span<T>.The type of items in the Span<T>.

Herencia
Span<T>

Comentarios

Span<T> es un struct de referencia 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. Los tipos de struct de referencia tienen una serie de restricciones para asegurarse de que no se pueden promover al montón administrado, lo que incluye que no se les puede aplicar la conversión boxing, no se pueden asignar a variables de tipo Object, dynamic ni a ningún tipo de interfaz, no pueden ser campos de un tipo de referencia. y no se pueden usar en los límites de await y @no__t 3.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, inician una NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Importante

Dado que es un tipo de solo pila, Span<T> no es adecuado para muchos escenarios que requieren el almacenamiento de las referencias a los búferes del 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 a métodos asincrónicos.This is true, for example, of routines that make asynchronous method calls. Para estos escenarios, puede usar los tipos complementarios System.Memory<T> y System.ReadOnlyMemory<T>.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

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

Span @ no__t-0T > y 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. Una instancia Span<T> se usa a menudo 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. Sin embargo, a diferencia de una matriz, una instancia Span<T> puede apuntar a la memoria administrada, a la memoria nativa o a la 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> a partir de 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> a partir 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 C# usa la palabra clave stackalloc 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 en un bloque de memoria arbitrario, los métodos de la clase Span<T> y los métodos con parámetros Span<T> operan en cualquier objeto Span<T>, independientemente del tipo de memoria que 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 inicializan el intervalo y calcula la suma de sus elementos se puede cambiar en métodos de inicialización y cálculo únicos, como se muestra en el ejemplo siguiente: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(nativeSpan):N0}");
    
    Marshal.FreeHGlobal(native);

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

    InitializeSpan(stackSpan);
    Console.WriteLine($"The sum is {ComputeSum(stackSpan):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

Span @ no__t-0T > y matricesSpan<T> and arrays

Cuando contiene una matriz, Span<T> puede ajustar una matriz completa, como en los ejemplos de la sección span @ no__t-2t > and Memory .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. Dado que admite la segmentación, Span<T> también puede apuntar a cualquier intervalo contiguo dentro de la matriz.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

En el ejemplo siguiente se crea un segmento de los cinco elementos 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 dobla los valores de cada entero del segmento.Note that the code doubles the values of each integer in the slice. Como se muestra en 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

Span @ no__t-0T > y segmentosSpan<T> and slices

Span<T> incluye dos sobrecargas del método Slice que forman un segmento fuera del intervalo actual que comienza en un í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 hace posible tratar los datos en un Span<T> como un conjunto de fragmentos lógicos que se pueden procesar según sea necesario por parte 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, como los protocolos de servidor modernos suelen estar basados en texto, la manipulación de cadenas y subcadenas es especialmente importante.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. En la clase String, el método principal para extraer subcadenas es Substring.In the String class, the major method for extracting substrings is Substring. En las canalizaciones de datos que se basan en una manipulación de cadenas extensa, su uso ofrece algunas penalizaciones 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 contiene 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 copia se puede eliminar mediante Span<T> o ReadOnlySpan<T>, 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[])

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>(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.

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.

Propiedades

Empty

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

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[Int32]

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

Length

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

Métodos

Clear()

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

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)

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

Fill(T)

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

GetEnumerator()

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

GetHashCode()

Produce una excepción NotSupportedException.Throws a NotSupportedException.

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(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(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()

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

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>)

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>)

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>)

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>)

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>)

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>)

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.

Métodos de extensión

BinarySearch<T>(Span<T>, IComparable<T>)

Busca un valor en un objeto Span<T> ordenado completo, utilizando la interfaz genérica IComparable<T> especificada.Searches an entire sorted Span<T> for a value using the specified IComparable<T> generic interface.

BinarySearch<T,TComparer>(Span<T>, T, TComparer)

Busca un valor especificado en un objeto Span<T> ordenado completo, utilizando el tipo genérico TComparer especificada.Searches an entire sorted Span<T> for a specified value using the specified TComparer generic type.

BinarySearch<T,TComparable>(Span<T>, TComparable)

Busca un valor en un objeto Span<T> ordenado completo, utilizando el tipo genérico TComparable especificada.Searches an entire sorted Span<T> for a value using the specified TComparable generic type.

Contains<T>(Span<T>, T)

Indica si un valor especificado se encuentra en un intervalo.Indicates whether a specified value is found in a span. Los valores se comparan mediante IEquatable{T}.Equals(T).Values are compared using IEquatable{T}.Equals(T).

EndsWith<T>(Span<T>, ReadOnlySpan<T>)

Determina si la secuencia especificada aparece al final de un intervalo.Determines whether the specified sequence appears at the end of a span.

IndexOf<T>(Span<T>, T)

Busca el valor especificado y devuelve el índice de su primera aparición.Searches for the specified value and returns the index of its first occurrence. Los valores se comparan mediante IEquatable{T}.Equals(T).Values are compared using IEquatable{T}.Equals(T).

IndexOf<T>(Span<T>, ReadOnlySpan<T>)

Busca la secuencia especificada y devuelve el índice de su primera aparición.Searches for the specified sequence and returns the index of its first occurrence. Los valores se comparan mediante IEquatable{T}.Equals(T).Values are compared using IEquatable{T}.Equals(T).

IndexOfAny<T>(Span<T>, T, T)

Busca el primer índice de cualquiera de los valores especificados, similar a llamar a IndexOf varias veces con el operador lógico OR.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

IndexOfAny<T>(Span<T>, T, T, T)

Busca el primer índice de cualquiera de los valores especificados, similar a llamar a IndexOf varias veces con el operador lógico OR.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

IndexOfAny<T>(Span<T>, ReadOnlySpan<T>)

Busca el primer índice de cualquiera de los valores especificados, similar a llamar a IndexOf varias veces con el operador lógico OR.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

LastIndexOf<T>(Span<T>, T)

Busca el valor especificado y devuelve el índice de su última aparición.Searches for the specified value and returns the index of its last occurrence. Los valores se comparan mediante IEquatable{T}.Equals(T).Values are compared using IEquatable{T}.Equals(T).

LastIndexOf<T>(Span<T>, ReadOnlySpan<T>)

Busca la secuencia especificada y devuelve el índice de su última aparición.Searches for the specified sequence and returns the index of its last occurrence. Los valores se comparan mediante IEquatable{T}.Equals(T).Values are compared using IEquatable{T}.Equals(T).

LastIndexOfAny<T>(Span<T>, T, T)

Busca el último índice de cualquiera de los valores especificados, similar a llamar a LastIndexOf varias veces con el operador lógico OR.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

LastIndexOfAny<T>(Span<T>, T, T, T)

Busca el último índice de cualquiera de los valores especificados, similar a llamar a LastIndexOf varias veces con el operador lógico OR.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>)

Busca el último índice de cualquiera de los valores especificados, similar a llamar a LastIndexOf varias veces con el operador lógico OR.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

Overlaps<T>(Span<T>, ReadOnlySpan<T>)

Determina si un intervalo y un intervalo de solo lectura se superponen en la memoria.Determines whether a span and a read-only span overlap in memory.

Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32)

Determina si un intervalo y un intervalo de solo lectura se superponen en la memoria y genera el desplazamiento del elemento.Determines whether a span and a read-only span overlap in memory and outputs the element offset.

Reverse<T>(Span<T>)

Invierte la secuencia de los elementos de todo el intervalo.Reverses the sequence of the elements in the entire span.

SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>)

Determina el orden relativo de dos secuencias de solo lectura, comparando sus elementos mediante IComparable{T}.CompareTo(T).Determines the relative order of a span and a read-only span by comparing the elements using IComparable{T}.CompareTo(T).

SequenceEqual<T>(Span<T>, ReadOnlySpan<T>)

Determina si un intervalo y un intervalo de solo lectura son iguales comparando los elementos mediante IEquatable{T}.Equals(T).Determines whether a span and a read-only span are equal by comparing the elements using IEquatable{T}.Equals(T).

StartsWith<T>(Span<T>, ReadOnlySpan<T>)

Determina si una secuencia especificada aparece al inicio de un intervalo.Determines whether a specified sequence appears at the start of a span.

Trim<T>(Span<T>, T)

Quita todas las apariciones iniciales y finales de un elemento especificado de un intervalo.Removes all leading and trailing occurrences of a specified element from a span.

Trim<T>(Span<T>, ReadOnlySpan<T>)

Quita de un intervalo todas las apariciones iniciales y finales de un conjunto de elementos especificados en un intervalo de solo lectura.Removes all leading and trailing occurrences of a set of elements specified in a read-only span from a span.

TrimEnd<T>(Span<T>, T)

Quita todas las apariciones finales de un elemento especificado de un intervalo.Removes all trailing occurrences of a specified element from a span.

TrimEnd<T>(Span<T>, ReadOnlySpan<T>)

Quita de un intervalo todas las apariciones finales de un conjunto de elementos especificados en un intervalo de solo lectura.Removes all trailing occurrences of a set of elements specified in a read-only span from a span.

TrimStart<T>(Span<T>, T)

Quita todas las apariciones iniciales de un elemento especificado del intervalo.Removes all leading occurrences of a specified element from the span.

TrimStart<T>(Span<T>, ReadOnlySpan<T>)

Quita del intervalo todas las apariciones iniciales de un conjunto de elementos especificados en un intervalo de solo lectura.Removes all leading occurrences of a set of elements specified in a read-only span from the span.

Se aplica a