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

Определение

Предоставляет типобезопасную и безопасную для памяти реализацию непрерывной области произвольной памяти.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)

Параметры типа

T

Тип элементов в Span<T>.The type of items in the Span<T>.

Наследование

Комментарии

Span<T>структура ссылки , расположенной в стеке, а не в управляемой куче.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Ref struct типы имеют ряд ограничений, чтобы убедиться, что они не преобразуется управляемой куче, включая, что они не могут быть упакованы, они не могут быть назначены переменным типа Object, dynamic или любой другой тип интерфейса, они не могут быть поля в ссылочный тип и их нельзя сравнивать await и 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. Кроме того, вызовы два метода Equals(Object) и GetHashCode, исключение NotSupportedException.In addition, calls to two methods, Equals(Object) and GetHashCode, throw a NotSupportedException.

Важно!

Так как он является типом только для стека Span<T> не подходит для многих сценариев, требующих хранения ссылки на буферы в куче.Because it is a stack-only type, Span<T> is unsuitable for many scenarios that require storing references to buffers on the heap. Это верно, к примеру, подпрограмм, которые выполняют вызовы асинхронного метода.This is true, for example, of routines that make asynchronous method calls. В таких случаях можно использовать дополнительный System.Memory<T> и System.ReadOnlyMemory<T> типов.For such scenarios, you can use the complementary System.Memory<T> and System.ReadOnlyMemory<T> types.

Для диапазонов, которые представляют структуры неизменное или только для чтения, используйте System.ReadOnlySpan<T>.For spans that represent immutable or read-only structures, use System.ReadOnlySpan<T>.

Диапазон<T > и памятиSpan<T> and memory

Объект Span<T> представляет непрерывную область произвольной памяти.A Span<T> represents a contiguous region of arbitrary memory. Объект Span<T> экземпляр часто используется для хранения элементов в массиве или в части массива.A Span<T> instance is often used to hold the elements of an array or a portion of an array. В отличие от массива, однако Span<T> экземпляр может указывать на управляемую память, внутренней памяти или управляемых памяти в стеке.Unlike an array, however, a Span<T> instance can point to managed memory, native memory, or memory managed on the stack. В следующем примере создается Span<Byte> из массива: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

В следующем примере создается Span<Byte> из 100 байт внутренней памяти: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

В следующем примере используется C# stackalloc ключевых слов для выделения 100 байт памяти в стеке: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

Так как Span<T> — это абстракция над произвольный блок памяти, методы Span<T> классов и методов с Span<T> параметры работают с любой Span<T> объекта независимо от типа памяти, содержащейся в нем.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. Например каждый из отдельных разделов кода, инициализирующие диапазон и вычислять сумму его элементов можно изменить в одиночной инициализации и методы расчетов, как в примере ниже показаны: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

Диапазон<T > и массивыSpan<T> and arrays

При его переносе в массиве, Span<T> можно заключить весь массив, как и в примерах в диапазон<T > и памяти раздел.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. Так как он поддерживает Создание срезов, Span<T> также может указывать любой непрерывный диапазон в массиве.Because it supports slicing, Span<T> can also point to any contiguous range within the array.

В следующем примере создается срез средних пять элементов целое число 10 элементов массива.The following example creates a slice of the middle five elements of a 10-element integer array. Обратите внимание на то, что код удваивает значения каждого целого числа в срез.Note that the code doubles the values of each integer in the slice. Как показывает вывод, изменения, внесенные в диапазоне, отражаются в значения массива.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

Диапазон<T > и срезыSpan<T> and slices

Span<T> включает в себя две перегрузки Slice метод этой формы среза вне текущей области, который начинается с указанного индекса.Span<T> includes two overloads of the Slice method that form a slice out of the current span that starts at a specified index. Это позволяет обрабатывать данные в Span<T> как набор логические фрагменты, которые могут обрабатываться при необходимости частями конвейер обработки данных без ущерба для производительности.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. Например так как современные серверные протоколы часто являются текстовыми, работы со строками и подстроки особенно важна.For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. В String класса, основной метод для извлечения подстроки является Substring.In the String class, the major method for extracting substrings is Substring. Для конвейеры данных, которые используют обширные строками его использование предлагает некоторые снижения производительности, так как оно:For data pipelines that rely on extensive string manipulation, its use offers some performance penalties, since it:

  1. Создает новую строку для хранения подстроки.Creates a new string to hold the substring.

  2. Копирует определенное подмножество символов из исходной строки в новой строке.Copies a subset of the characters from the original string to the new string.

Эта операция выделения и копирования, можно устранить с помощью Span<T> или ReadOnlySpan<T>, как показано в следующем примере: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

Конструкторы

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

Создает новый объект Span<T> по всему указанному массиву.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)

Создает объект Span<T> из указанного числа элементов T, начиная с заданного адреса памяти.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)

Создает новый объект Span<T>, который включает указанное число элементов массива, начиная с указанного индекса.Creates a new Span<T> object that includes a specified number of elements of an array starting at a specified index.

Свойства

Empty Empty Empty Empty

Возвращает пустой объект Span<T>.Returns an empty Span<T> object.

IsEmpty IsEmpty IsEmpty IsEmpty

Возвращает значение, указывающее, пуст ли текущий объект Span<T>.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]

Возвращает элемент по указанному индексу, начинающемуся с нуля.Gets the element at the specified zero-based index.

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

Возвращает длину текущего диапазона.Returns the length of the current span.

Методы

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

Удаляет содержимое этого объекта Span<T>.Clears the contents of this Span<T> object.

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

Копирует содержимое этого объекта Span<T> в назначение Span<T>.Copies the contents of this Span<T> into a destination Span<T>.

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

Вызов этого метода не поддерживается.Calls to this method are not supported.

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

Заполняет элементы диапазона заданным значением.Fills the elements of this span with a specified value.

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

Возвращает перечислитель для коллекции Span<T>.Returns an enumerator for this Span<T>.

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

Создает исключение NotSupportedException.Throws a NotSupportedException.

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

Возвращает ссылку на элемент Span<T> при нулевом индексе.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)

Формирует срез вне текущего диапазона, который начинается с указанного индекса.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)

Формирует срез вне текущей области, начиная с указанного индекса до указанной длины.Forms a slice out of the current span starting at a specified index for a specified length.

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

Копирует содержимое этого диапазона в новый массив.Copies the contents of this span into a new array.

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

Возвращает строковое представление конкретного объекта Span<T>.Returns the string representation of this Span<T> object.

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

Пытается скопировать текущий Span<T> в назначение Span<T> и возвращает значение, указывающее, успешно ли выполнена операция копирования.Attempts to copy the current Span<T> to a destination Span<T> and returns a value that indicates whether the copy operation succeeded.

Операторы

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

Возвращает значение, указывающее, равны ли два объекта Span<T>.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>)

Определяет неявное преобразование ArraySegment<T> в 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>)

Определяет неявное преобразование Span<T> в 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>)

Определяет неявное преобразование массива в 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>)

Возвращает значение, указывающее, являются ли два объекта Span<T> неравными.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>)

Применяется к