Span<T> Struktura

Definicja

Udostępnia bezpieczną reprezentację typu i pamięci dla ciągłego regionu dowolnej pamięci.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)

Parametry typu

T

Typ elementów w Span<T>.The type of items in the Span<T>.

Dziedziczenie
Span<T>

Uwagi

Span<T> jest strukturą ref przydzieloną na stosie, a nie na stosie zarządzanym.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Typy struktur ref mają wiele ograniczeń, aby upewnić się, że nie można ich podwyższyć do sterty zarządzanej, w tym, że nie można ich przetworzyć, nie mogą być przypisane do zmiennych typu Object, dynamic ani do żadnego typu interfejsu, nie mogą być polami w typie odwołania i nie mogą być używane w granicach await i yield.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. Dodatkowo wywołania do dwóch metod, Equals(Object) i GetHashCode, generują NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Ważne

Ponieważ jest to typ tylko stosu, Span<T> jest nieodpowiedni dla wielu scenariuszy, które wymagają przechowywania odwołań do buforów na stercie.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Dotyczy to na przykład procedur, które powodują wywołania metod asynchronicznych.This is true, for example, of routines that make asynchronous method calls. W takich scenariuszach można używać uzupełniających System.Memory<T> i typów System.ReadOnlyMemory<T>.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Dla zakresów, które reprezentują niezmienne lub tylko do odczytu struktury, użyj System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Span<T > i pamięćSpan<T> and memory

Span<T> reprezentuje ciągły region wolnej pamięci.A Span<T> represents a contiguous region of arbitrary memory. Wystąpienie Span<T> jest często używane do przechowywania elementów tablicy lub fragmentu tablicy.A Span<T> instance is often used to hold the elements of an array or a portion of an array. W przeciwieństwie do tablicy, wystąpienie Span<T> może wskazywać na pamięć zarządzaną, pamięć natywną lub pamięć zarządzaną na stosie.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. Poniższy przykład tworzy Span<Byte> z tablicy: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

Poniższy przykład tworzy Span<Byte> z 100 bajtów pamięci natywnej: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

W poniższym przykładzie za pomocą C# słowa kluczowego stackalloc można przydzielić 100 bajtów pamięci na stosie: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

Ponieważ Span<T> jest abstrakcją dla dowolnego bloku pamięci, metody klasy Span<T> i metody z Span<T> parametry działają na dowolnym obiekcie Span<T>, niezależnie od rodzaju pamięci, która jest hermetyzowana.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. Na przykład każdą z oddzielnych sekcji kodu, które inicjują zakres i obliczania sumy jego elementów, można zmienić na pojedyncze metody inicjacji i obliczeń, jak pokazano w poniższym przykładzie: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

Zakres<T > i tablicSpan<T> and arrays

Gdy otacza tablicę, Span<T> może zawijać całą tablicę, tak jak w przykładach w <w > i w sekcji zakres.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. Ponieważ obsługuje ona dzielenie, Span<T> może również wskazywać dowolny zakres ciągły w tablicy.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

Poniższy przykład powoduje utworzenie wycinka 5 elementów w pionie 10-elementowej tablicy całkowitej.The following example creates a slice of the middle five elements of a 10-element integer array. Należy zauważyć, że kod podwaja wartości każdej liczby całkowitej w wycinku.Note that the code doubles the values of each integer in the slice. W miarę wyświetlania danych wyjściowych zmiany wprowadzone przez zakres są uwzględniane w wartościach tablicy.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

Zakres<T > i wycinkówSpan<T> and slices

Span<T> obejmuje dwa przeciążenia metody Slice, które tworzą wycink z bieżącego zakresu, który zaczyna się od określonego indeksu.Span<T> includes two overloads of the Slice method that form a slice out of the current span that starts at a specified index. Umożliwia to traktowanie danych w Span<T> jako zestaw fragmentów logicznych, które mogą być przetwarzane w razie potrzeby przez fragmenty potoku przetwarzania danych z minimalnym wpływem na wydajność.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. Na przykład, ponieważ nowoczesne protokoły serwera często są oparte na tekście, manipulowanie ciągami i podciągami jest szczególnie ważne.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. W klasie String główna Metoda wyodrębniania podciągów jest Substring.In the String class, the major method for extracting substrings is Substring. W przypadku potoków danych, które opierają się na rozdzielnym manipulowaniu ciągami, jego użycie zapewnia pewne kary wydajnościowe, ponieważ:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Tworzy nowy ciąg do przechowywania podciągu.Creates a new string to hold the substring.

  2. Kopiuje podzestaw znaków z oryginalnego ciągu do nowego ciągu.Copies a subset of the characters from the original string to the new string.

Tę operację alokacji i kopiowania można wyeliminować przy użyciu Span<T> lub ReadOnlySpan<T>, jak pokazano na poniższym przykładzie: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

Konstruktory

Span<T>(T[])

Tworzy nowy obiekt Span<T> w całości dla określonej tablicy.Creates a new Span<T> object over the entirety of a specified array.

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

Tworzy nowy obiekt Span<T>, który zawiera określoną liczbę elementów tablicy, zaczynając od określonego indeksu.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)

Tworzy nowy obiekt Span<T> na podstawie określonej liczby T elementów, zaczynając od określonego adresu pamięci.Creates a new Span<T> object from a specified number of T elements starting at a specified memory address.

Właściwości

Empty

Zwraca pusty obiekt Span<T>.Returns an empty Span<T> object.

IsEmpty

Zwraca wartość wskazującą, czy bieżący Span<T> jest pusty.Returns a value that indicates whether the current Span<T> is empty.

Item[Int32]

Pobiera element w określonym indeksie liczonym od zera.Gets the element at the specified zero-based index.

Length

Zwraca długość bieżącego zakresu.Returns the length of the current span.

Metody

Clear()

Czyści zawartość tego obiektu Span<T>.Clears the contents of this Span<T> object.

CopyTo(Span<T>)

Kopiuje zawartość tego Span<T> do Span<T>docelowej.Copies the contents of this Span<T> into a destination Span<T>.

Equals(Object)

Wywołania tej metody nie są obsługiwane.Calls to this method are not supported.

Fill(T)

Wypełnia elementy tego zakresu przy użyciu określonej wartości.Fills the elements of this span with a specified value.

GetEnumerator()

Zwraca moduł wyliczający dla tego Span<T>.Returns an enumerator for this Span<T>.

GetHashCode()

Zgłasza NotSupportedException.Throws a NotSupportedException.

GetPinnableReference()

Zwraca odwołanie do elementu Span<T> przy indeksie równym zero.Returns a reference to the element of the Span<T> at index zero.

Slice(Int32)

Tworzy wycink poza bieżącym zakresem, który rozpoczyna się od określonego indeksu.Forms a slice out of the current span that begins at a specified index.

Slice(Int32, Int32)

Tworzy wycink poza bieżącym zakresem, rozpoczynając od określonego indeksu przez określoną długość.Forms a slice out of the current span starting at a specified index for a specified length.

ToArray()

Kopiuje zawartość tego zakresu do nowej tablicy.Copies the contents of this span into a new array.

ToString()

Zwraca reprezentację ciągu tego obiektu Span<T>.Returns the string representation of this Span<T> object.

TryCopyTo(Span<T>)

Próbuje skopiować bieżącą Span<T> do Span<T> docelowej i zwraca wartość wskazującą, czy operacja kopiowania zakończyła się pomyślnie.Attempts to copy the current Span<T> to a destination Span<T> and returns a value that indicates whether the copy operation succeeded.

Operatory

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

Zwraca wartość wskazującą, czy dwa obiekty Span<T> są równe.Returns a value that indicates whether two Span<T> objects are equal.

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

Definiuje niejawną konwersję ArraySegment<T> do Span<T>.Defines an implicit conversion of an ArraySegment<T> to a Span<T>.

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

Definiuje niejawną konwersję Span<T> do ReadOnlySpan<T>.Defines an implicit conversion of a Span<T> to a ReadOnlySpan<T>.

Implicit(T[] to Span<T>)

Definiuje niejawną konwersję tablicy do Span<T>.Defines an implicit conversion of an array to a Span<T>.

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

Zwraca wartość wskazującą, czy dwa Span<T> obiekty nie są równe.Returns a value that indicates whether two Span<T> objects are not equal.

Metody rozszerzania

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

Wyszukuje w całym posortowanym Span<T> wartość przy użyciu określonego IComparable<T> generycznego interfejsu.Searches an entire sorted Span<T> for a value using the specified IComparable<T> generic interface.

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

Wyszukuje całą posortowaną Span<T> dla określonej wartości przy użyciu określonego TComparer typu ogólnego.Searches an entire sorted Span<T> for a specified value using the specified TComparer generic type.

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

Wyszukuje w całym posortowanym Span<T> wartość przy użyciu określonego TComparable typu ogólnego.Searches an entire sorted Span<T> for a value using the specified TComparable generic type.

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

Wskazuje, czy określona wartość jest znaleziona w zakresie.Indicates whether a specified value is found in a span. Wartości są porównywane przy użyciu IEquatable {T}. Equals (T).Values are compared using IEquatable{T}.Equals(T).

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

Określa, czy określona sekwencja pojawia się na końcu zakresu.Determines whether the specified sequence appears at the end of a span.

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

Wyszukuje określoną wartość i zwraca indeks pierwszego wystąpienia.Searches for the specified value and returns the index of its first occurrence. Wartości są porównywane przy użyciu IEquatable {T}. Equals (T).Values are compared using IEquatable{T}.Equals(T).

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

Wyszukuje określoną sekwencję i zwraca indeks pierwszego wystąpienia.Searches for the specified sequence and returns the index of its first occurrence. Wartości są porównywane przy użyciu IEquatable {T}. Equals (T).Values are compared using IEquatable{T}.Equals(T).

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

Wyszukuje pierwszy indeks wszelkich określonych wartości podobne do wywoływania IndexOf kilka razy przy użyciu operatora logicznego OR.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)

Wyszukuje pierwszy indeks wszelkich określonych wartości podobne do wywoływania IndexOf kilka razy przy użyciu operatora logicznego OR.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>)

Wyszukuje pierwszy indeks wszelkich określonych wartości podobne do wywoływania IndexOf kilka razy przy użyciu operatora logicznego OR.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)

Wyszukuje określoną wartość i zwraca indeks ostatniego wystąpienia.Searches for the specified value and returns the index of its last occurrence. Wartości są porównywane przy użyciu IEquatable {T}. Equals (T).Values are compared using IEquatable{T}.Equals(T).

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

Wyszukuje określoną sekwencję i zwraca indeks ostatniego wystąpienia.Searches for the specified sequence and returns the index of its last occurrence. Wartości są porównywane przy użyciu IEquatable {T}. Equals (T).Values are compared using IEquatable{T}.Equals(T).

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

Wyszukuje ostatni indeks wszelkich określonych wartości podobnie do wywoływania LastIndexOf kilka razy przy użyciu operatora logicznego OR.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)

Wyszukuje ostatni indeks wszelkich określonych wartości podobnie do wywoływania LastIndexOf kilka razy przy użyciu operatora logicznego OR.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>)

Wyszukuje ostatni indeks wszelkich określonych wartości podobnie do wywoływania LastIndexOf kilka razy przy użyciu operatora logicznego OR.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>)

Określa, czy zakres i zakres tylko do odczytu nakładają się na pamięć.Determines whether a span and a read-only span overlap in memory.

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

Określa, czy zakres i zakres tylko do odczytu nakładają się na pamięć i wyprowadzają przesunięcie elementu.Determines whether a span and a read-only span overlap in memory and outputs the element offset.

Reverse<T>(Span<T>)

Odwraca sekwencję elementów w całym zakresie.Reverses the sequence of the elements in the entire span.

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

Określa względną kolejność zakresu i przedział tylko do odczytu, porównując elementy przy użyciu elementu 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>)

Określa, czy zakres i zakres tylko do odczytu są równe, porównując elementy przy użyciu IEquatable {T}. Equals (T).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>)

Określa, czy określona sekwencja pojawia się na początku zakresu.Determines whether a specified sequence appears at the start of a span.

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

Usuwa wszystkie wystąpienia wiodące i końcowe określonego elementu z zakresu.Removes all leading and trailing occurrences of a specified element from a span.

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

Usuwa wszystkie wystąpienia wiodące i końcowe zestawu elementów określonych w zakresie tylko do odczytu z zakresu.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)

Usuwa wszystkie końcowe wystąpienia określonego elementu z zakresu.Removes all trailing occurrences of a specified element from a span.

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

Usuwa wszystkie końcowe wystąpienia zestawu elementów określone w zakresie tylko do odczytu z zakresu.Removes all trailing occurrences of a set of elements specified in a read-only span from a span.

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

Usuwa wszystkie wiodące wystąpienia określonego elementu z zakresu.Removes all leading occurrences of a specified element from the span.

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

Usuwa wszystkie wiodące wystąpienia zestawu elementów określonego w zakresie tylko do odczytu z zakresu.Removes all leading occurrences of a set of elements specified in a read-only span from the span.

Dotyczy