Span<T> Struktur

Definition

Dieser enthält eine typ- und arbeitsspeichersichere Darstellung einer zusammenhängenden Region von beliebigem Arbeitsspeicher.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)

Typparameter

T

Der Typ der Elemente in der Span<T>.The type of items in the Span<T>.

Vererbung
Span<T>

Hinweise

Span<T> ist eine ref-Struktur , die auf dem Stapel und nicht auf dem verwalteten Heap zugeordnet wird.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Referenzstruktur Typen weisen eine Reihe von Einschränkungen auf, um sicherzustellen, dass Sie nicht in den verwalteten Heap herauf gestuft werden können. Sie können nicht mit einem boachtelt versehen werden, Sie können nicht Variablen vom Typ Object, dynamic oder einem beliebigen Schnittstellentyp zugewiesen werden. Sie können keine Felder in einem Verweistyp sein. und können nicht über await-und yield-Grenzen hinweg verwendet werden.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. Außerdem lösen Aufrufe von zwei Methoden, Equals(Object) und GetHashCode, eine NotSupportedException aus.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Wichtig

Da es sich um einen reinen Stapel Datentyp handelt, ist Span<T> für viele Szenarien ungeeignet, in denen Verweise auf Puffer auf dem Heap gespeichert werden müssen.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Dies gilt z. b. für Routinen, die asynchrone Methodenaufrufe durchführen.This is true, for example, of routines that make asynchronous method calls. In solchen Szenarien können Sie die Komplement System.Memory<T>-und System.ReadOnlyMemory<T>-Typen verwenden.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Verwenden Sie für spannen, die unveränderliche oder schreibgeschützte Strukturen darstellen, System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Span @ no__t-0t > und ArbeitsspeicherSpan<T> and memory

Ein Span<T> stellt einen zusammenhängenden Bereich eines beliebigen Speichers dar.A Span<T> represents a contiguous region of arbitrary memory. Eine Span<T>-Instanz wird häufig verwendet, um die Elemente eines Arrays oder eines Teils eines Arrays zu speichern.A Span<T> instance is often used to hold the elements of an array or a portion of an array. Anders als bei einem Array kann eine Span<T>-Instanz jedoch auf verwalteten Arbeitsspeicher, systemeigenen Arbeitsspeicher oder auf dem Stapel verwaltete Arbeitsspeicher verweisen.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. Im folgenden Beispiel wird eine Span<Byte> aus einem Array erstellt: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

Im folgenden Beispiel wird eine Span<Byte> aus 100 Bytes des systemeigenen Speichers erstellt: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

Im folgenden Beispiel wird das C# stackalloc -Schlüsselwort verwendet, um dem Stapel 100 Bytes Arbeitsspeicher zuzuordnen: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

Da Span<T> eine Abstraktion über einen beliebigen Speicherblock ist, werden Methoden der Span<T>-Klasse und Methoden mit Span<T>-Parametern auf jedes Span<T>-Objekt angewendet, unabhängig von der Art des verwendeten Speichers.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. Beispielsweise können alle separaten Code Abschnitte, die die Spanne initialisieren und die Summe ihrer Elemente berechnen, in einzelne Initialisierungs-und Berechnungsmethoden geändert werden, wie im folgenden Beispiel veranschaulicht: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 > und ArraysSpan<T> and arrays

Beim umschließen eines Arrays kann Span<T> ein ganzes Array umschließen, wie dies in den Beispielen im Abschnitt Span @ no__t-2T > und Memory der Fall war.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. Da das Slicing unterstützt wird, kann Span<T> auch auf einen zusammenhängenden Bereich innerhalb des Arrays zeigen.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

Im folgenden Beispiel wird ein Slice der mittleren fünf Elemente eines ganz Zahl Arrays mit 10 Elementen erstellt.The following example creates a slice of the middle five elements of a 10-element integer array. Beachten Sie, dass der Code die Werte der einzelnen ganzzahligen Werte im Slice verdoppelt.Note that the code doubles the values of each integer in the slice. Wie die Ausgabe zeigt, werden die von der Spanne vorgenommenen Änderungen in den Werten des Arrays widergespiegelt.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 > und SlicesSpan<T> and slices

Span<T> enthält zwei über Ladungen der Slice-Methode, die ein Slice aus der aktuellen Spanne bilden, das bei einem angegebenen Index beginnt.Span<T> includes two overloads of the Slice method that form a slice out of the current span that starts at a specified index. Dadurch ist es möglich, die Daten in einem Span<T> als einen Satz logischer Blöcke zu behandeln, die nach Bedarf von Teilen einer Datenverarbeitungs Pipeline mit minimalen Auswirkungen auf die Leistung verarbeitet werden können.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. Da z. b. moderne Server Protokolle häufig Text basiert sind, ist die Bearbeitung von Zeichen folgen und Teil Zeichenfolgen besonders wichtig.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. In der String-Klasse ist die Hauptmethode zum Extrahieren von Teil Zeichenfolgen Substring.In the String class, the major method for extracting substrings is Substring. Bei Daten Pipelines, die sich auf umfangreiche Zeichen folgen Manipulation stützen, bietet die Verwendung einige Leistungseinbußen, da Folgendes der Fall ist:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Erstellt eine neue Zeichenfolge, die die Teil Zeichenfolge enthalten soll.Creates a new string to hold the substring.

  2. Kopiert eine Teilmenge der Zeichen aus der ursprünglichen Zeichenfolge in die neue Zeichenfolge.Copies a subset of the characters from the original string to the new string.

Dieser Zuordnungs-und Kopiervorgang kann mit Span<T> oder ReadOnlySpan<T> gelöscht werden, wie im folgenden Beispiel gezeigt: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

Konstruktoren

Span<T>(T[])

Erstellt ein neues Span<T>-Objekt über das gesamte angegebene Array.Creates a new Span<T> object over the entirety of a specified array.

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

Erstellt ein neues Span<T>-Objekt, das eine angegebene Anzahl von Elementen aus einem Array enthält. Dabei wird an einem angegebenen Index begonnen.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)

Erstellt ein neues Span<T>-Objekt aus einer angegebenen Anzahl von T-Elementen. Dabei wird an der angegebenen Speicheradresse begonnen.Creates a new Span<T> object from a specified number of T elements starting at a specified memory address.

Eigenschaften

Empty

Gibt ein leeres Span<T>-Objekt zurück.Returns an empty Span<T> object.

IsEmpty

Gibt einen Wert zurück, der angibt, ob das aktuelle Span<T>-Element leer ist.Returns a value that indicates whether the current Span<T> is empty.

Item[Int32]

Ruft das Element am angegebenen nullbasierten Index ab.Gets the element at the specified zero-based index.

Length

Gibt die Länge des aktuellen Span-Elements fest.Returns the length of the current span.

Methoden

Clear()

Löscht den Inhalt dieses Span<T>-Objekts.Clears the contents of this Span<T> object.

CopyTo(Span<T>)

Kopiert die Inhalte dieses Span<T>-Elements in ein Span<T>-Zielelement.Copies the contents of this Span<T> into a destination Span<T>.

Equals(Object)

Das Aufrufen dieser Methode wird nicht unterstützt.Calls to this method are not supported.

Fill(T)

Füllt die Elemente dieses Span-Elements mit einem angegebenen Wert auf.Fills the elements of this span with a specified value.

GetEnumerator()

Gibt einen Enumerator für dieses Span<T>-Element zurück.Returns an enumerator for this Span<T>.

GetHashCode()

Löst eine NotSupportedException aus.Throws a NotSupportedException.

GetPinnableReference()

Gibt einen Verweis auf das Element von Span<T> zurück, das sich am Index 0 befindet.Returns a reference to the element of the Span<T> at index zero.

Slice(Int32)

Bildet einen Slice aus dem aktuellen Span-Element, das an einem angegebenen Index beginnt.Forms a slice out of the current span that begins at a specified index.

Slice(Int32, Int32)

Bildet einen Slice aus dem aktuellen Span-Element. Dabei wird an einem angegebenen Index für eine angegebene Länge begonnen.Forms a slice out of the current span starting at a specified index for a specified length.

ToArray()

Kopiert die Inhalte dieses Span-Elements in ein neues Array.Copies the contents of this span into a new array.

ToString()

Gibt die Zeichenfolgendarstellung dieses Span<T>-Objekts zurück.Returns the string representation of this Span<T> object.

TryCopyTo(Span<T>)

Versucht, das aktuelle Span<T>-Element in ein Span<T>-Zielelement zu kopieren und gibt einen Wert zurück, der angibt, ob der Kopiervorgang erfolgreich war.Attempts to copy the current Span<T> to a destination Span<T> and returns a value that indicates whether the copy operation succeeded.

Operatoren

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

Gibt einen Wert zurück, der angibt, ob zwei Span<T>-Objekte gleich sind.Returns a value that indicates whether two Span<T> objects are equal.

Implicit(ArraySegment<T> to Span<T>)

Definiert eine implizite Konvertierung von ArraySegment<T> in Span<T>.Defines an implicit conversion of an ArraySegment<T> to a Span<T>.

Implicit(Span<T> to ReadOnlySpan<T>)

Definiert eine implizite Konvertierung von Span<T> in ReadOnlySpan<T>.Defines an implicit conversion of a Span<T> to a ReadOnlySpan<T>.

Implicit(T[] to Span<T>)

Definiert eine implizite Konvertierung eines Arrays in Span<T>.Defines an implicit conversion of an array to a Span<T>.

Inequality(Span<T>, Span<T>)

Gibt einen Wert zurück, der angibt, ob zwei Span<T>-Objekte ungleich sind.Returns a value that indicates whether two Span<T> objects are not equal.

Erweiterungsmethoden

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

Durchsucht ein ganzes sortiertes Span<T> mithilfe der angegebenen generischen IComparable<T>-Schnittstelle nach einem Wert.Searches an entire sorted Span<T> for a value using the specified IComparable<T> generic interface.

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

Durchsucht ein ganzes sortiertes Span<T> mithilfe des angegebenen generischen TComparer-Typs nach einem angegebenen Wert.Searches an entire sorted Span<T> for a specified value using the specified TComparer generic type.

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

Durchsucht ein ganzes sortiertes Span<T> mithilfe des angegebenen generischen TComparable-Typs nach einem Wert.Searches an entire sorted Span<T> for a value using the specified TComparable generic type.

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

Gibt an, ob ein angegebener Wert in einer Spanne gefunden wird.Indicates whether a specified value is found in a span. Werte werden mit „IEquatable{T}.Equals(T)“ verglichen.Values are compared using IEquatable{T}.Equals(T).

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

Bestimmt, ob die angegebene Sequenz am Ende einer Spanne angezeigt wird.Determines whether the specified sequence appears at the end of a span.

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

Sucht nach dem angegebenen Wert und gibt den Index des ersten Vorkommens zurück.Searches for the specified value and returns the index of its first occurrence. Werte werden mit „IEquatable{T}.Equals(T)“ verglichen.Values are compared using IEquatable{T}.Equals(T).

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

Sucht nach der angegebenen Sequenz und gibt den Index des ersten Vorkommens zurück.Searches for the specified sequence and returns the index of its first occurrence. Werte werden mit „IEquatable{T}.Equals(T)“ verglichen.Values are compared using IEquatable{T}.Equals(T).

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

Sucht nach dem ersten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von IndexOf mit dem logischen OR-Operator (ODER).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)

Sucht nach dem ersten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von IndexOf mit dem logischen OR-Operator (ODER).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>)

Sucht nach dem ersten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von IndexOf mit dem logischen OR-Operator (ODER).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)

Sucht nach dem angegebenen Wert und gibt den Index des letzten Vorkommens zurück.Searches for the specified value and returns the index of its last occurrence. Werte werden mit „IEquatable{T}.Equals(T)“ verglichen.Values are compared using IEquatable{T}.Equals(T).

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

Sucht nach der angegebenen Sequenz und gibt den Index des letzten Vorkommens zurück.Searches for the specified sequence and returns the index of its last occurrence. Werte werden mit „IEquatable{T}.Equals(T)“ verglichen.Values are compared using IEquatable{T}.Equals(T).

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

Sucht nach dem letzten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von LastIndexOf mit dem logischen OR-Operator (ODER).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)

Sucht nach dem letzten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von LastIndexOf mit dem logischen OR-Operator (ODER).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>)

Sucht nach dem letzten Index eines der angegebenen Werte, ähnlich dem mehrmaligen Aufruf von LastIndexOf mit dem logischen OR-Operator (ODER).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>)

Bestimmt, ob sich eine Spanne und eine schreibgeschützte Spanne im Speicher überlappen.Determines whether a span and a read-only span overlap in memory.

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

Bestimmt, ob sich eine Spanne und eine schreibgeschützte Spanne im Speicher überlappen, und gibt den Elementoffset aus.Determines whether a span and a read-only span overlap in memory and outputs the element offset.

Reverse<T>(Span<T>)

Kehrt die Reihenfolge der Elemente in der gesamten Spanne um.Reverses the sequence of the elements in the entire span.

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

Bestimmt die relative Reihenfolge von einer Spanne und einer schreibgeschützten Spanne durch Vergleichen der Elemente mit „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>)

Bestimmt, ob eine Spanne und eine schreibgeschützte Spanne identisch sind, indem die Elemente mit „IEquatable{T}.Equals(T)“ verglichen werden.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>)

Bestimmt, ob eine angegebene Sequenz am Anfang einer Spanne angezeigt wird.Determines whether a specified sequence appears at the start of a span.

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

Entfernt alle führenden und nachfolgenden Vorkommen eines angegebenen Elements aus einer Spanne.Removes all leading and trailing occurrences of a specified element from a span.

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

Entfernt alle führenden und nachfolgenden Vorkommen einer Reihe von Elementen, die in einer schreibgeschützten Spanne angegeben sind, aus einer Spanne.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)

Entfernt alle nachfolgenden Vorkommen eines angegebenen Elements aus einer Spanne.Removes all trailing occurrences of a specified element from a span.

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

Entfernt alle nachfolgenden Vorkommen einer Reihe von Elementen, die in einer schreibgeschützten Spanne angegeben sind, aus einer Spanne.Removes all trailing occurrences of a set of elements specified in a read-only span from a span.

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

Entfernt alle führenden Vorkommen eines bestimmten Elements aus der Spanne.Removes all leading occurrences of a specified element from the span.

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

Entfernt alle führenden Vorkommen einer Reihe von Elementen, die in einer schreibgeschützten Spanne angegeben sind, aus der Spanne.Removes all leading occurrences of a set of elements specified in a read-only span from the span.

Gilt für: