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

Definizione

Fornisce una rappresentazione indipendente dai tipi e dalla memoria di una regione contigua di 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)

Parametri di tipo

T

Il tipo di elementi nel Span<T>.The type of items in the Span<T>.

Ereditarietà

Commenti

Span<T> è un uno struct di riferimento che viene allocata nello stack anziché nell'heap gestito.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. I tipi struct ref hanno un numero di restrizioni per garantire che non può essere promosso nell'heap gestito, tra cui che essi non possono essere boxed, non possono essere assegnate a variabili di tipo Object, dynamic o a qualsiasi tipo di interfaccia, non possono essere i campi in un tipo di riferimento e non possono essere usati tra await e yield limiti.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. Inoltre, le chiamate a due metodi, Equals(Object) e GetHashCode, generano un NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Importante

Perché è un tipo di stack-only, Span<T> non è adatta per molti scenari che richiedono l'archiviazione di riferimenti ai buffer nell'heap.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Ciò vale, ad esempio, le routine che effettuano chiamate ai metodi asincroni.This is true, for example, of routines that make asynchronous method calls. Per questi scenari, è possibile usare il complementari System.Memory<T> e System.ReadOnlyMemory<T> tipi.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Per gli intervalli che rappresentano le strutture non modificabile o di sola lettura, usare System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Intervallo<T > e la memoriaSpan<T> and memory

Oggetto Span<T> rappresenta una regione contigua di memoria arbitraria.A Span<T> represents a contiguous region of arbitrary memory. Oggetto Span<T> istanza viene spesso usata per contenere gli elementi di una matrice o una parte di una matrice.A Span<T> instance is often used to hold the elements of an array or a portion of an array. A differenza di una matrice, tuttavia, un Span<T> istanza può fare riferimento alla memoria gestita, della memoria nativa, o la memoria gestita su stack.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. L'esempio seguente crea un Span<Byte> da una matrice: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

L'esempio seguente crea un Span<Byte> da 100 byte della 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

L'esempio seguente usa il C# stackalloc (parola chiave) da allocare 100 byte di memoria nello stack: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

In quanto Span<T> è un'astrazione su un blocco di memoria, i metodi di arbitrario il Span<T> classi e metodi con Span<T> parametri operano su qualsiasi Span<T> oggetto indipendentemente dal tipo di memoria incapsula.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. Ad esempio, ognuna delle sezioni separate del codice che inizializzano l'intervallo e calcolare che la somma dei relativi elementi può essere modificata nell'inizializzazione singola e metodi di calcolo, come illustrato nell'esempio seguente viene illustrato: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

Intervallo<T > e matriciSpan<T> and arrays

Quando esegue il wrapping di una matrice Span<T> può eseguire il wrapping di un'intera matrice, come accadeva negli esempi del Span<T > e della memoria sezione.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. Poiché supporta il sezionamento, Span<T> può puntare anche a qualsiasi intervallo contiguo all'interno della matrice.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

L'esempio seguente crea una sezione dei intermedi cinque elementi di una matrice di interi di 10 elementi.The following example creates a slice of the middle five elements of a 10-element integer array. Si noti che il codice raddoppia i valori di ogni intero nella sezione.Note that the code doubles the values of each integer in the slice. Come illustrato nell'output, le modifiche apportate dall'intervallo di vengono riflesse nei valori della matrice.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

Intervallo<T > e sulle sezioniSpan<T> and slices

Span<T> include due overload del Slice metodo che formano una sezione all'esterno di intervallo corrente che inizia in corrispondenza dell'indice specificato.Span<T> includes two overloads of the Slice method that form a slice out of the current span that starts at a specified index. Questo rende possibile trattare i dati in un Span<T> come un set di parti logiche che possono essere elaborati in base alle esigenze per parti di una pipeline di elaborazione dei dati con impatto minimo sulle prestazioni.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. Ad esempio, poiché i protocolli server moderni sono spesso basati su testo, la manipolazione delle stringhe e le sottostringhe è particolarmente importante.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. Nel String classe, il metodo principale per l'estrazione delle sottostringhe è Substring.In the String class, the major method for extracting substrings is Substring. Per le pipeline di dati che si basano su Modifica di stringhe estesa, l'uso offre alcuni effetti negativi sulle prestazioni, perché:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Crea una nuova stringa per contenere la sottostringa.Creates a new string to hold the substring.

  2. Copia un subset di caratteri dalla stringa originale per la nuova stringa.Copies a subset of the characters from the original string to the new string.

Questa operazione di allocazione e la copia può essere eliminata usando Span<T> o ReadOnlySpan<T>, come illustrato nell'esempio seguente: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

Costruttori

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

Crea un nuovo oggetto Span<T> sull'intera matrice specificata.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 nuovo oggetto Span<T> da un numero specificato di elementi T partire da un indirizzo di memoria specificato.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 nuovo oggetto Span<T> che include un numero specificato di elementi di una matrice che iniziano in un indice specificato.Creates a new Span<T> object that includes a specified number of elements of an array starting at a specified index.

Proprietà

Empty Empty Empty Empty

Restituisce un oggetto Span<T> vuoto.Returns an empty Span<T> object.

IsEmpty IsEmpty IsEmpty IsEmpty

Restituisce un valore che indica se l'oggetto Span<T> corrente è vuoto.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]

Ottiene l'elemento in corrispondenza dell'indice in base zero.Gets the element at the specified zero-based index.

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

Restituisce la lunghezza dell'intervallo corrente.Returns the length of the current span.

Metodi

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

Cancella il contenuto di questo oggetto Span<T>.Clears the contents of this Span<T> object.

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

Copia il contenuto di questo Span<T> in una destinazione Span<T>.Copies the contents of this Span<T> into a destination Span<T>.

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

Le chiamate a questo metodo non sono supportate.Calls to this method are not supported.

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

Inserisce un valore specificato negli elementi di questo intervallo.Fills the elements of this span with a specified value.

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

Restituisce un enumeratore per questo Span<T>.Returns an enumerator for this Span<T>.

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

Genera un oggetto NotSupportedException.Throws a NotSupportedException.

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

Restituisce un riferimento all'elemento di Span<T> in corrispondenza dell'indice 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)

Crea una sezione dall'intervallo corrente che inizia in corrispondenza di un indice specificato.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)

Crea una sezione dall'intervallo corrente che inizia in corrispondenza di un indice specificato per una lunghezza specificata.Forms a slice out of the current span starting at a specified index for a specified length.

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

Copia il contenuto di questo intervallo in una nuova matrice.Copies the contents of this span into a new array.

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

Restituisce la rappresentazione di stringa dell'oggetto Span<T>.Returns the string representation of this Span<T> object.

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

Tenta di copiare l'oggetto Span<T> corrente in un Span<T> di destinazione e restituisce un valore che indica se l'operazione di copia ha avuto esito positivo.Attempts to copy the current Span<T> to a destination Span<T> and returns a value that indicates whether the copy operation succeeded.

Operatori

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

Restituisce un valore che indica se due oggetti Span<T> sono uguali.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>)

Definisce una conversione implicita di un ArraySegment<T> in un 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>)

Definisce una conversione implicita di un oggetto Span<T> in un oggetto 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>)

Definisce una conversione implicita di una matrice in 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>)

Restituisce un valore che indica se due oggetti Span<T> non sono uguali.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>)

Si applica a