Span<T> Estrutura
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Fornece uma representação segura de memória e de tipo de uma região contígua de memória arbitrária.
generic <typename T>
public value class Span
[System.Runtime.InteropServices.Marshalling.NativeMarshalling(typeof(System.Runtime.InteropServices.Marshalling.SpanMarshaller<,>))]
public readonly ref struct Span<T>
public readonly ref struct Span<T>
[<System.Runtime.InteropServices.Marshalling.NativeMarshalling(typeof(System.Runtime.InteropServices.Marshalling.SpanMarshaller<,>))>]
type Span<'T> = struct
type Span<'T> = struct
Public Structure Span(Of T)
Parâmetros de tipo
- T
O tipo de itens no Span<T>.
- Herança
- Atributos
Comentários
O tipo Span<T> é um ref struct e é alocado na pilha, em vez de no heap gerenciado. Os tipos de struct de ref têm algumas restrições para garantir que eles não possam ser promovidos ao heap gerenciado, incluindo que eles não podem ser:
- Em caixa.
- Atribuído a variáveis do tipo Object ou
dynamic, ou a qualquer erro de digitação de interface. - Campos em um tipo de referência.
- Usado entre limites e
awaitlimitesyield.
Além disso, as chamadas para os dois métodos Equals(Object) e GetHashCode lançam um NotSupportedException.
Importante
Como Span<T> é um tipo restrito a pilha, ele não é adequado para muitos cenários que exigem o armazenamento de referências a buffers no heap. Isso é verdadeiro, por exemplo, para rotinas que fazem chamadas de método assíncronas. Para esses cenários, você pode usar os tipos complementares System.Memory<T> e System.ReadOnlyMemory<T>.
Para intervalos que representam estruturas imutáveis ou somente leitura, use System.ReadOnlySpan<T>.
Memória
A Span<T> representa uma região contígua de memória arbitrária. Uma Span<T> instância é frequentemente usada para manter os elementos de uma matriz ou uma parte de uma matriz. Ao contrário de uma matriz, no entanto, uma Span<T> instância pode apontar para memória gerenciada, memória nativa ou memória gerenciada na pilha. O exemplo a seguir cria um Span<Byte> a partir de uma matriz:
// 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
// Create a span over an array.
let array = Array.zeroCreate<byte> 100
let arraySpan = Span<byte> array
let mutable data = 0uy
for i = 0 to arraySpan.Length - 1 do
arraySpan[i] <- data
data <- data + 1uy
let mutable arraySum = 0
for value in array do
arraySum <- arraySum + int value
printfn $"The sum is {arraySum}"
// Output: The sum is 4950
O exemplo a seguir cria um Span<Byte> de 100 bytes de memória nativa:
// 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
// Create a span from native memory.
let native = Marshal.AllocHGlobal 100
let nativeSpan = Span<byte>(native.ToPointer(), 100)
let mutable data = 0uy
for i = 0 to nativeSpan.Length - 1 do
nativeSpan[i] <- data
data <- data + 1uy
let mutable nativeSum = 0
for value in nativeSpan do
nativeSum <- nativeSum + int value
printfn $"The sum is {nativeSum}"
Marshal.FreeHGlobal native
// Output: The sum is 4950
O exemplo a seguir usa a palavra-chave stackalloc do C# para alocar 100 bytes de memória na pilha:
// 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
// Create a span on the stack.
let mutable data = 0uy
let stackSpan =
let p = NativeInterop.NativePtr.stackalloc<byte> 100 |> NativeInterop.NativePtr.toVoidPtr
Span<byte>(p, 100)
for i = 0 to stackSpan.Length - 1 do
stackSpan[i] <- data
data <- data + 1uy
let mutable stackSum = 0
for value in stackSpan do
stackSum <- stackSum + int value
printfn $"The sum is {stackSum}"
// Output: The sum is 4950
Como Span<T> é uma abstração sobre um bloco arbitrário de memória, métodos do tipo Span<T> e métodos com parâmetros Span<T> operam sobre qualquer objeto Span<T>, independentemente da espécie de memória que ele encapsula. Por exemplo, cada uma das seções separadas de código que inicializam o intervalo e calculam a soma de seus elementos pode ser refatorada em métodos de inicialização e cálculo únicos, como ilustra o exemplo a seguir:
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
open System
open System.Runtime.InteropServices
open FSharp.NativeInterop
// Package FSharp.NativeInterop.NativePtr.stackalloc for reuse.
let inline stackalloc<'a when 'a: unmanaged> length : Span<'a> =
let voidPointer = NativePtr.stackalloc<'a> length |> NativePtr.toVoidPtr
Span<'a>(voidPointer, length)
let initializeSpan (span: Span<byte>) =
let mutable value = 0uy
for i = 0 to span.Length - 1 do
span[i] <- value
value <- value + 1uy
let computeSum (span: Span<byte>) =
let mutable sum = 0
for value in span do
sum <- sum + int value
sum
let workWithSpans () =
// Create a span over an array.
let array = Array.zeroCreate<byte> 100
let arraySpan = Span<byte> array
initializeSpan arraySpan
printfn $"The sum is {computeSum arraySpan:N0}"
// Create an array from native memory.
let native = Marshal.AllocHGlobal 100
let nativeSpan = Span<byte>(native.ToPointer(), 100)
initializeSpan nativeSpan
printfn $"The sum is {computeSum nativeSpan:N0}"
Marshal.FreeHGlobal native
// Create a span on the stack.
let stackSpan = stackalloc 100
initializeSpan stackSpan
printfn $"The sum is {computeSum stackSpan:N0}"
// The example displays the following output:
// The sum is 4,950
// The sum is 4,950
// The sum is 4,950
Matrizes
Quando ele encapsula uma matriz, Span<T> pode encapsular uma matriz inteira, como fez nos exemplos na seção Memória . Como ele dá suporte ao fatiamento, Span<T> também pode apontar para qualquer intervalo contíguo dentro da matriz.
O exemplo a seguir cria uma fatia dos cinco elementos intermediários de uma matriz inteira de 10 elementos. Observe que o código dobra os valores de cada inteiro no segmento. Como mostra a saída, as alterações feitas pelo intervalo são refletidas nos valores da matriz.
using System;
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
module Program
open System
[<EntryPoint>]
let main _ =
let array = [| 2; 4; 6; 8; 10; 12; 14; 16; 18; 20 |]
let slice = Span<int>(array, 2, 5)
for i = 0 to slice.Length - 1 do
slice[i] <- slice[i] * 2
// Examine the original array values.
for value in array do
printf $"{value} "
printfn ""
0
// The example displays the following output:
// 2 4 12 16 20 24 28 16 18 20
Segmentos
Span<T> inclui duas sobrecargas do método Slice que formam um subsegmento do intervalo atual que começa em um índice especificado. Isso possibilita tratar os dados em um conjunto de partes lógicas em um Span<T> que podem ser processadas conforme necessário por diferentes partes de um pipeline de processamento de dados, com impacto mínimo sobre o desempenho. Por exemplo, como os protocolos de servidor modernos geralmente são baseados em texto, a manipulação de cadeias de caracteres e subcadeias de caracteres é particularmente importante. Na classe String, o principal método para extrair substrings é Substring. Para pipelines de dados que dependem de manipulação extensiva de strings, o seu uso oferece alguns impactos no desempenho, pois:
- Cria uma nova string para armazenar a substring.
- Copia um subconjunto dos caracteres da cadeia de caracteres original para a nova cadeia de caracteres.
Essa operação de alocação e cópia pode ser eliminada usando Span<T> ou ReadOnlySpan<T>, conforme o exemplo a seguir mostra:
using System;
class Program2
{
static void Run()
{
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
module Program2
open System
let getContentLength (span: ReadOnlySpan<char>) =
let slice = span.Slice 16
Int32.Parse slice
let contentLength = "Content-Length: 132"
let length = getContentLength (contentLength.ToCharArray())
printfn $"Content length: {length}"
// Output:
// Content length: 132
Construtores
| Nome | Description |
|---|---|
| Span<T>(T) |
Cria um novo Span<T> comprimento 1 em torno da referência especificada. |
| Span<T>(T[], Int32, Int32) |
Cria um novo Span<T> objeto que inclui um número especificado de elementos de uma matriz começando em um índice especificado. |
| Span<T>(T[]) |
Cria um novo Span<T> objeto em toda a matriz especificada. |
| Span<T>(Void*, Int32) |
Cria um novo Span<T> objeto a partir de um número especificado de |
Propriedades
| Nome | Description |
|---|---|
| Empty |
Retorna um objeto vazio Span<T> . |
| IsEmpty |
Retorna um valor que indica se a corrente Span<T> está vazia. |
| Item[Int32] |
Obtém o elemento no índice de base zero especificado. |
| Length |
Retorna o comprimento do intervalo atual. |
Métodos
| Nome | Description |
|---|---|
| Clear() |
Limpa o conteúdo deste Span<T> objeto. |
| CopyTo(Span<T>) | |
| Equals(Object) |
Obsoleto.
Obsoleto.
Não há suporte para chamadas para esse método. |
| Fill(T) |
Preenche os elementos desse intervalo com um valor especificado. |
| GetEnumerator() |
Retorna um enumerador para isso Span<T>. |
| GetHashCode() |
Obsoleto.
Lança NotSupportedException. |
| GetPinnableReference() |
Retorna uma referência a um objeto do tipo T que pode ser usado para fixação. Esse método destina-se a dar suporte a compiladores .NET e não se destina a ser chamado pelo código do usuário. |
| Slice(Int32, Int32) |
Forma uma fatia do intervalo atual começando em um índice especificado para um comprimento especificado. |
| Slice(Int32) |
Forma uma fatia do intervalo atual que começa em um índice especificado. |
| ToArray() |
Copia o conteúdo desse intervalo em uma nova matriz. |
| ToString() |
Retorna a representação de cadeia de caracteres deste Span<T> objeto. |
| TryCopyTo(Span<T>) |
Tenta copiar a corrente Span<T> para um destino Span<T> e retorna um valor que indica se a operação de cópia foi bem-sucedida. |
Operadores
| Nome | Description |
|---|---|
| Equality(Span<T>, Span<T>) |
Retorna um valor que indica se dois Span<T> objetos são iguais. |
| Implicit(ArraySegment<T> to Span<T>) |
Define uma conversão implícita de um ArraySegment<T> em um Span<T>. |
| Implicit(Span<T> to ReadOnlySpan<T>) |
Define uma conversão implícita de um Span<T> em um ReadOnlySpan<T>. |
| Implicit(T[] to Span<T>) |
Define uma conversão implícita de uma matriz em um Span<T>. |
| Inequality(Span<T>, Span<T>) |
Retorna um valor que indica se dois Span<T> objetos não são iguais. |
Métodos de Extensão
| Nome | Description |
|---|---|
| BinarySearch<T,TComparable>(Span<T>, TComparable) |
Pesquisa um valor inteiro classificado Span<T> usando o tipo genérico especificado |
| BinarySearch<T,TComparer>(Span<T>, T, TComparer) |
Pesquisa uma classificação Span<T> inteira para um valor especificado usando o tipo genérico especificado |
| BinarySearch<T>(Span<T>, IComparable<T>) |
Pesquisa um valor inteiro classificado Span<T> usando a interface genérica especificada IComparable<T> . |
| CommonPrefixLength<T>(Span<T>, ReadOnlySpan<T>, IEqualityComparer<T>) |
Localiza o comprimento de qualquer prefixo comum compartilhado entre |
| CommonPrefixLength<T>(Span<T>, ReadOnlySpan<T>) |
Localiza o comprimento de qualquer prefixo comum compartilhado entre |
| Contains<T>(Span<T>, T) |
Indica se um valor especificado é encontrado em um intervalo. |
| ContainsAny<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa uma ocorrência de qualquer um dos especificados |
| ContainsAny<T>(Span<T>, SearchValues<T>) |
Pesquisa uma ocorrência de qualquer um dos especificados |
| ContainsAny<T>(Span<T>, T, T, T) |
Pesquisa uma ocorrência de |
| ContainsAny<T>(Span<T>, T, T) |
Pesquisa uma ocorrência de |
| ContainsAnyExcept<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa o intervalo especificado para qualquer valor diferente do especificado |
| ContainsAnyExcept<T>(Span<T>, SearchValues<T>) |
Pesquisa o intervalo especificado para qualquer valor diferente do especificado |
| ContainsAnyExcept<T>(Span<T>, T, T, T) |
Pesquisa qualquer valor diferente |
| ContainsAnyExcept<T>(Span<T>, T, T) |
Pesquisa o intervalo especificado para qualquer valor diferente |
| ContainsAnyExcept<T>(Span<T>, T) |
Pesquisa o intervalo especificado para qualquer valor diferente do especificado |
| ContainsAnyExceptInRange<T>(Span<T>, T, T) |
Pesquisa qualquer valor fora do intervalo entre |
| ContainsAnyInRange<T>(Span<T>, T, T) |
Pesquisa qualquer valor no intervalo entre |
| Count<T>(Span<T>, ReadOnlySpan<T>) |
Conta o número de vezes que o especificado |
| Count<T>(Span<T>, T) |
Conta o número de vezes que o especificado |
| EndsWith<T>(Span<T>, ReadOnlySpan<T>) |
Determina se a sequência especificada aparece no final de um intervalo. |
| IndexOf<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa a sequência especificada e retorna o índice de sua primeira ocorrência. |
| IndexOf<T>(Span<T>, T) |
Pesquisa o valor especificado e retorna o índice de sua primeira ocorrência. |
| IndexOfAny<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa o primeiro índice de qualquer um dos valores especificados. |
| IndexOfAny<T>(Span<T>, SearchValues<T>) |
Pesquisa o primeiro índice de qualquer um dos valores especificados. |
| IndexOfAny<T>(Span<T>, T, T, T) |
Pesquisa o primeiro índice de qualquer um dos valores especificados. |
| IndexOfAny<T>(Span<T>, T, T) |
Pesquisa o primeiro índice de qualquer um dos valores especificados. |
| IndexOfAnyExcept<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa o primeiro índice de qualquer valor diferente do especificado |
| IndexOfAnyExcept<T>(Span<T>, SearchValues<T>) |
Pesquisa o primeiro índice de qualquer valor diferente do especificado |
| IndexOfAnyExcept<T>(Span<T>, T, T, T) |
Pesquisa o primeiro índice de qualquer valor diferente |
| IndexOfAnyExcept<T>(Span<T>, T, T) |
Pesquisa o primeiro índice de qualquer valor diferente dos dois valores especificados. |
| IndexOfAnyExcept<T>(Span<T>, T) |
Pesquisa o primeiro índice de qualquer valor diferente do especificado |
| IndexOfAnyExceptInRange<T>(Span<T>, T, T) |
Pesquisa o primeiro índice de qualquer valor fora do intervalo entre |
| IndexOfAnyInRange<T>(Span<T>, T, T) |
Pesquisa o primeiro índice de qualquer valor no intervalo entre |
| LastIndexOf<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa a sequência especificada e retorna o índice de sua última ocorrência. |
| LastIndexOf<T>(Span<T>, T) |
Pesquisa o valor especificado e retorna o índice de sua última ocorrência. |
| LastIndexOfAny<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa o último índice de qualquer um dos valores especificados. |
| LastIndexOfAny<T>(Span<T>, SearchValues<T>) |
Pesquisa o último índice de qualquer um dos valores especificados. |
| LastIndexOfAny<T>(Span<T>, T, T, T) |
Pesquisa o último índice de qualquer um dos valores especificados. |
| LastIndexOfAny<T>(Span<T>, T, T) |
Pesquisa o último índice de qualquer um dos valores especificados. |
| LastIndexOfAnyExcept<T>(Span<T>, ReadOnlySpan<T>) |
Pesquisa o último índice de qualquer valor diferente do especificado |
| LastIndexOfAnyExcept<T>(Span<T>, SearchValues<T>) |
Pesquisa o último índice de qualquer valor diferente do especificado |
| LastIndexOfAnyExcept<T>(Span<T>, T, T, T) |
Pesquisa o último índice de qualquer valor diferente do especificado |
| LastIndexOfAnyExcept<T>(Span<T>, T, T) |
Pesquisa o último índice de qualquer valor diferente do especificado |
| LastIndexOfAnyExcept<T>(Span<T>, T) |
Pesquisa o último índice de qualquer valor diferente do especificado |
| LastIndexOfAnyExceptInRange<T>(Span<T>, T, T) |
Pesquisa o último índice de qualquer valor fora do intervalo entre |
| LastIndexOfAnyInRange<T>(Span<T>, T, T) |
Pesquisa o último índice de qualquer valor no intervalo entre |
| Overlaps<T>(Span<T>, ReadOnlySpan<T>, Int32) |
Determina se um intervalo e um intervalo somente leitura se sobrepõem na memória e geram o deslocamento do elemento. |
| Overlaps<T>(Span<T>, ReadOnlySpan<T>) |
Determina se um intervalo e um intervalo somente leitura se sobrepõem na memória. |
| Replace<T>(Span<T>, T, T, IEqualityComparer<T>) |
Substitui todas as ocorrências de |
| Replace<T>(Span<T>, T, T) |
Substitui todas as ocorrências de |
| ReplaceAny<T>(Span<T>, SearchValues<T>, T) |
Substitui em |
| ReplaceAnyExcept<T>(Span<T>, SearchValues<T>, T) |
Substitui em |
| Reverse<T>(Span<T>) |
Inverte a sequência dos elementos em todo o intervalo. |
| SequenceCompareTo<T>(Span<T>, ReadOnlySpan<T>) |
Determina a ordem relativa de um intervalo e um intervalo somente leitura comparando os elementos usando IComparable{T}. CompareTo(T). |
| SequenceEqual<T>(Span<T>, ReadOnlySpan<T>, IEqualityComparer<T>) |
Determina se duas sequências são iguais comparando os elementos usando um IEqualityComparer<T>. |
| SequenceEqual<T>(Span<T>, ReadOnlySpan<T>) |
Determina se um intervalo e um intervalo somente leitura são iguais comparando os elementos usando IEquatable{T}. Equals(T). |
| Sort<T,TComparer>(Span<T>, TComparer) |
Classifica os elementos no todo Span<T> usando o |
| Sort<T>(Span<T>, Comparison<T>) |
Classifica os elementos no todo Span<T> usando o especificado Comparison<T>. |
| Sort<T>(Span<T>) |
Classifica os elementos no todo Span<T> usando a IComparable<T> implementação de cada elemento do Span<T>. |
| Sort<TKey,TValue,TComparer>(Span<TKey>, Span<TValue>, TComparer) |
Classifica um par de intervalos (um contendo as chaves e o outro que contém os itens correspondentes) com base nas chaves no primeiro Span<T> usando o comparador especificado. |
| Sort<TKey,TValue>(Span<TKey>, Span<TValue>, Comparison<TKey>) |
Classifica um par de intervalos (um contendo as chaves e o outro que contém os itens correspondentes) com base nas chaves no primeiro Span<T> usando a comparação especificada. |
| Sort<TKey,TValue>(Span<TKey>, Span<TValue>) |
Classifica um par de intervalos (um contendo as chaves e o outro que contém os itens correspondentes) com base nas chaves no primeiro Span<T> usando a IComparable<T> implementação de cada chave. |
| StartsWith<T>(Span<T>, ReadOnlySpan<T>) |
Determina se uma sequência especificada aparece no início de um intervalo. |
| ToImmutableArray<T>(Span<T>) |
Converte o intervalo em uma matriz imutável. |
| Trim<T>(Span<T>, ReadOnlySpan<T>) |
Remove todas as ocorrências à esquerda e à direita de um conjunto de elementos especificado em um intervalo somente leitura de um intervalo. |
| Trim<T>(Span<T>, T) |
Remove todas as ocorrências à esquerda e à direita de um elemento especificado de um intervalo. |
| TrimEnd<T>(Span<T>, ReadOnlySpan<T>) |
Remove todas as ocorrências à direita de um conjunto de elementos especificado em um intervalo somente leitura de um intervalo. |
| TrimEnd<T>(Span<T>, T) |
Remove todas as ocorrências à direita de um elemento especificado de um intervalo. |
| TrimStart<T>(Span<T>, ReadOnlySpan<T>) |
Remove todas as ocorrências principais de um conjunto de elementos especificado em um intervalo somente leitura do intervalo. |
| TrimStart<T>(Span<T>, T) |
Remove todas as ocorrências principais de um elemento especificado do intervalo. |