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

Definição

Fornece uma representação fortemente tipada e de memória segura de uma região contígua da memória arbitrária.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

O tipo dos itens no Span<T>.The type of items in the Span<T>.

Herança

Comentários

Span<T> é um ref struct que é alocada na pilha em vez de no heap gerenciado.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Tipos de struct ref têm um número de restrições para garantir que eles não podem ser promovidos para o heap gerenciado, incluindo o que eles não podem ser boxed, eles não podem ser atribuídos a variáveis do tipo Object, dynamic ou para qualquer tipo de interface, eles não podem ser campos em um tipo de referência e eles não podem ser usado entre await e yield limites.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. Além disso, chamadas a dois métodos, Equals(Object) e GetHashCode, lançar um NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Importante

Porque ele é um tipo de pilha somente Span<T> é inadequado para muitos cenários que exijam armazenar referências aos buffers no heap.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Isso é verdadeiro, por exemplo, de rotinas que fazem chamadas de método assíncrono.This is true, for example, of routines that make asynchronous method calls. Para esses cenários, você pode usar o complementar System.Memory<T> e System.ReadOnlyMemory<T> tipos.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Para os intervalos que representam estruturas imutáveis ou somente leitura, use System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Alcance<T > e memóriaSpan<T> and memory

Um Span<T> representa uma região contígua da memória arbitrária.A Span<T> represents a contiguous region of arbitrary memory. Um Span<T> instância geralmente é usada para manter os elementos de uma matriz ou uma parte de uma matriz.A Span<T> instance is often used to hold the elements of an array or a portion of an array. Ao contrário de uma matriz, no entanto, um Span<T> instância pode apontar para a memória gerenciada, memória nativa, ou a memória gerenciada na pilha.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. O exemplo a seguir cria um Span<Byte> de uma 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

O exemplo a seguir cria um Span<Byte> de 100 bytes de memória 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

O exemplo a seguir usa o C# stackalloc palavra-chave para alocar 100 bytes de memória na pilha: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

Porque Span<T> é uma abstração de um bloco arbitrário de memória, métodos do Span<T> classe e métodos com Span<T> parâmetros de operam em qualquer Span<T> objeto independentemente do tipo de memória que ele 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 exemplo, cada uma das seções de código separadas que inicializar o alcance e calculam que a soma de seus elementos pode ser alterada em inicialização única e métodos de cálculo, como o exemplo a seguir ilustra: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

Alcance<T > e matrizesSpan<T> and arrays

Quando ele encapsula uma matriz Span<T> pode encapsular uma matriz inteira, como nos exemplos a Span<T > e a memória seção.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. Porque ele dá suporte a divisão, Span<T> também pode apontar para qualquer intervalo contíguo dentro da matriz.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

O exemplo a seguir cria uma fatia dos intermediárias cinco elementos de uma matriz de inteiros de 10 elementos.The following example creates a slice of the middle five elements of a 10-element integer array. Observe que o código duplica os valores de cada inteiro na fatia.Note that the code doubles the values of each integer in the slice. Como mostra a saída, as alterações feitas pela extensão são refletidas nos valores da 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

Alcance<T > e fatiasSpan<T> and slices

Span<T> inclui duas sobrecargas do Slice método que formam uma fatia fora de alcance atual que começa em um í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. Isso torna possível tratar os dados em um Span<T> como um conjunto de partes lógicas que podem ser processadas conforme o necessário pelas partes de um pipeline de processamento de dados com impacto mínimo no desempenho.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 exemplo, como protocolos de servidor moderno são geralmente baseados em texto, manipulação de cadeias de caracteres e subcadeias de caracteres é particularmente importante.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. No String , o principal método de classe para extrair subcadeias de caracteres é Substring.In the String class, the major method for extracting substrings is Substring. Para pipelines de dados que se baseiam na manipulação de cadeia de caracteres amplo, seu uso oferece alguns penalidades de desempenho, desde que ele:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Cria uma nova cadeia de caracteres para manter a subcadeia de caracteres.Creates a new string to hold the substring.

  2. Copia um subconjunto de caracteres de cadeia de caracteres original para a nova cadeia de caracteres.Copies a subset of the characters from the original string to the new string.

Esta operação de alocação e a cópia pode ser eliminada usando o Span<T> ou ReadOnlySpan<T>, como mostra o exemplo a seguir: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

Construtores

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

Cria um novo objeto Span<T> sobre a totalidade de uma 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)

Cria um objeto Span<T> com base em um número especificado de elementos T, começando em um endereço de memória especificado.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)

Cria um novo objeto Span<T> que inclui um número especificado de elementos de uma matriz, começando em um índice especificado.Creates a new Span<T> object that includes a specified number of elements of an array starting at a specified index.

Propriedades

Empty Empty Empty Empty

Retorna um objeto Span<T> vazio.Returns an empty Span<T> object.

IsEmpty IsEmpty IsEmpty IsEmpty

Retorna um valor que indica se o Span<T> atual está vazio.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]

Obtém o elemento no índice baseado em zero especificado.Gets the element at the specified zero-based index.

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

Retorna o tamanho do intervalo atual.Returns the length of the current span.

Métodos

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

Limpa o conteúdo deste objeto Span<T>.Clears the contents of this Span<T> object.

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

Copia o conteúdo deste Span<T> para um Span<T> de destino.Copies the contents of this Span<T> into a destination Span<T>.

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

Não há suporte para chamadas a esse método.Calls to this method are not supported.

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

Preenche os elementos desse intervalo com um valor especificado.Fills the elements of this span with a specified value.

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

Retorna um enumerador para este Span<T>.Returns an enumerator for this Span<T>.

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

Gera uma NotSupportedException.Throws a NotSupportedException.

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

Retorna uma referência ao elemento do Span<T> no índice zero.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 uma fatia com base no intervalo atual que começa em um í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 uma fatia com base no intervalo atual que começa em um índice especificado para um tamanho especificado.Forms a slice out of the current span starting at a specified index for a specified length.

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

Copia o conteúdo desse intervalo para uma nova matriz.Copies the contents of this span into a new array.

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

Retorna a representação de cadeia de caracteres desse objeto Span<T>.Returns the string representation of this Span<T> object.

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

Tenta copiar o Span<T> atual para um Span<T> de destino e retorna um valor que indica se a operação de cópia foi bem-sucedida.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>)

Retorna um valor que indica se dois objetos Span<T> são iguais.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 uma conversão implícita de um ArraySegment<T> em um 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 uma conversão implícita de um Span<T> em um 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 uma conversão implícita de uma matriz em um 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>)

Retorna um valor que indica se dois objetos Span<T> não são iguais.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>)

Aplica-se a