Span<T> Estrutura

Definição

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
Span<T>
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 await limitesyield.

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:

  1. Cria uma nova string para armazenar a substring.
  2. 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 T elementos começando em um endereço de memória especificado.

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

Copia o conteúdo disso Span<T> em um destino 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 TComparable .

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

Pesquisa uma classificação Span<T> inteira para um valor especificado usando o tipo genérico especificado TComparer .

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 span e other.

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

Localiza o comprimento de qualquer prefixo comum compartilhado entre span e other.

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 values e retorna true se encontrado. Se não for encontrado, retornará false.

ContainsAny<T>(Span<T>, SearchValues<T>)

Pesquisa uma ocorrência de qualquer um dos especificados values e retorna true se encontrado. Se não for encontrado, retornará false.

ContainsAny<T>(Span<T>, T, T, T)

Pesquisa uma ocorrência de value0, value1ou value2 no intervalo especificado.

ContainsAny<T>(Span<T>, T, T)

Pesquisa uma ocorrência de value0 ou value1e retorna true se encontrado. Se não for encontrado, retornará false.

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

Pesquisa o intervalo especificado para qualquer valor diferente do especificado values.

ContainsAnyExcept<T>(Span<T>, SearchValues<T>)

Pesquisa o intervalo especificado para qualquer valor diferente do especificado values.

ContainsAnyExcept<T>(Span<T>, T, T, T)

Pesquisa qualquer valor diferente value0de , value1ou value2.

ContainsAnyExcept<T>(Span<T>, T, T)

Pesquisa o intervalo especificado para qualquer valor diferente value0 ou value1.

ContainsAnyExcept<T>(Span<T>, T)

Pesquisa o intervalo especificado para qualquer valor diferente do especificado value.

ContainsAnyExceptInRange<T>(Span<T>, T, T)

Pesquisa qualquer valor fora do intervalo entre lowInclusive e highInclusive, inclusive.

ContainsAnyInRange<T>(Span<T>, T, T)

Pesquisa qualquer valor no intervalo entre lowInclusive e highInclusive, inclusive, e retorna true se encontrado. Se não for encontrado, retornará false.

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

Conta o número de vezes que o especificado value ocorre no span.

Count<T>(Span<T>, T)

Conta o número de vezes que o especificado value ocorre no span.

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

IndexOfAnyExcept<T>(Span<T>, SearchValues<T>)

Pesquisa o primeiro índice de qualquer valor diferente do especificado values.

IndexOfAnyExcept<T>(Span<T>, T, T, T)

Pesquisa o primeiro índice de qualquer valor diferente value0de , value1ou value2.

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

IndexOfAnyExceptInRange<T>(Span<T>, T, T)

Pesquisa o primeiro índice de qualquer valor fora do intervalo entre lowInclusive e highInclusive, inclusive.

IndexOfAnyInRange<T>(Span<T>, T, T)

Pesquisa o primeiro índice de qualquer valor no intervalo entre lowInclusive e highInclusive, inclusive.

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

LastIndexOfAnyExcept<T>(Span<T>, SearchValues<T>)

Pesquisa o último índice de qualquer valor diferente do especificado values.

LastIndexOfAnyExcept<T>(Span<T>, T, T, T)

Pesquisa o último índice de qualquer valor diferente do especificado value0, value1ou value2.

LastIndexOfAnyExcept<T>(Span<T>, T, T)

Pesquisa o último índice de qualquer valor diferente do especificado value0 ou value1.

LastIndexOfAnyExcept<T>(Span<T>, T)

Pesquisa o último índice de qualquer valor diferente do especificado value.

LastIndexOfAnyExceptInRange<T>(Span<T>, T, T)

Pesquisa o último índice de qualquer valor fora do intervalo entre lowInclusive e highInclusive, inclusive.

LastIndexOfAnyInRange<T>(Span<T>, T, T)

Pesquisa o último índice de qualquer valor no intervalo entre lowInclusive e highInclusive, inclusive.

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 oldValue por newValue.

Replace<T>(Span<T>, T, T)

Substitui todas as ocorrências de oldValue por newValue.

ReplaceAny<T>(Span<T>, SearchValues<T>, T)

Substitui em span todas as ocorrências de qualquer um dos elementos values por newValue.

ReplaceAnyExcept<T>(Span<T>, SearchValues<T>, T)

Substitui em span todos os elementos, exceto aqueles em values, por newValue.

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

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.

Aplica-se a

Confira também