Span<T> 結構

定義

提供任意記憶體連續區域的型別安全與記憶體安全標記法。

generic <typename T>
public value class Span
public readonly ref struct Span<T>
type Span<'T> = struct
Public Structure Span(Of T)

類型參數

T

中的 Span<T> 專案類型。

繼承
Span<T>

備註

Span<T> 是在堆疊上配置的 ref 結構 ,而不是在 Managed 堆積上配置。 Ref 結構類型有一些限制,可確保它們無法升階至 Managed 堆積,包括無法進行 Boxed、無法指派給類型的 Object 變數, dynamic 或指派給任何介面類別型的變數,它們不能是參考型別中的欄位,也無法跨 awaityield 界限使用。 此外,呼叫兩種方法 Equals(Object)GetHashCode 會擲回 NotSupportedException

重要

因為它是僅限堆疊的類型, Span<T> 因此不適用於許多需要儲存堆積上緩衝區參考的案例。 例如,這是進行非同步方法呼叫的常式。 針對這類案例,您可以使用互補 System.Memory<T>System.ReadOnlyMemory<T> 型別。

對於代表不可變或唯讀結構的範圍,請使用 System.ReadOnlySpan<T>

範圍 <T> 和記憶體

Span<T>表示任意記憶體的連續區域。 Span<T>實例通常用於保存陣列或陣列一部分的專案。 不過,不同于陣列, Span<T> 實例可以指向堆疊上受控記憶體、原生記憶體或記憶體。 下列範例會 Span<Byte> 從陣列建立 :

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

下列範例會 Span<Byte> 從 100 個位元組的原生記憶體建立 :

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

下列範例會使用 C# stackalloc 關鍵字在堆疊上配置 100 個位元組的記憶體:

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

由於 Span<T> 是任意記憶體區塊的抽象概念,因此不論其封裝的記憶體種類為何, Span<T> 具有 Span<T> 參數的方法和方法都會在任何物件上 Span<T> 運作。 例如,初始化範圍並計算其元素總和的每個個別區段都可以變更為單一初始化和計算方法,如下列範例所示:

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

範圍 <T> 和陣列

包裝陣列時, Span<T> 可以包裝整個陣列,如同 Span <T> 和 memory 區段中的範例所示。 因為它支援切割, Span<T> 所以也可以指向陣列內的任何連續範圍。

下列範例會建立 10 個元素整數陣列中間五個元素的配量。 請注意,程式碼會將配量中每個整數的值加倍。 如輸出所示,範圍所做的變更會反映在陣列的值中。

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

範圍 <T> 和配量

Span<T> 包含方法的 Slice 兩個多載,這些多載會形成從指定索引開始的目前範圍配量。 這可讓您將 中的資料 Span<T> 視為一組邏輯區塊,這些區塊可由資料處理管線的一部分視需要處理,而效能影響最小。 例如,由於新式伺服器通訊協定通常是以文字為基礎的,因此字串和子字串的操作特別重要。 在 類別中 String ,擷取子字串 Substring 的主要方法是 。 對於依賴大量字串操作的資料管線,其用法會提供一些效能負面影響,因為它:

  1. 建立新的字串來保存子字串。

  2. 將原始字串中的字元子集複製到新的字串。

您可以使用 或 ReadOnlySpan<T>Span<T> 消除此配置和複製作業,如下列範例所示:

using System;

class Program2
{
    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
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

建構函式

Span<T>(T[])

在整個指定的陣列上建立新的 Span<T> 物件。

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

建立新的 Span<T> 物件,其中包含起始於指定索引之陣列的指定項目數。

Span<T>(Void*, Int32)

透過指定的 T 元素數目建立新 Span<T> 物件,從指定的記憶體位址開始。

屬性

Empty

傳回空的 Span<T> 物件。

IsEmpty

傳回值,指出目前的 Span<T> 是否為空白。

Item[Int32]

取得位於指定索引的元素,該索引以零起始。

Length

傳回目前範圍的長度。

方法

Clear()

清除這個 Span<T> 物件的內容。

CopyTo(Span<T>)

將這個 Span<T> 的內容複製到目的地 Span<T>

Equals(Object)
已過時。
已過時。

不支援呼叫這個方法。

Fill(T)

以指定的值填入這個範圍的項目。

GetEnumerator()

傳回這個 Span<T> 的列舉值。

GetHashCode()
已過時。

擲回 NotSupportedException

GetPinnableReference()

傳回 T 類型物件的參考,該物件可用於釘選。

這個方法旨在支援 .NET 編譯器,並非由使用者程式碼呼叫。

Slice(Int32)

從起始於指定索引的目前範圍形成配量。

Slice(Int32, Int32)

從起始於指定索引之指定長度的目前範圍形成配量。

ToArray()

將這個範圍的內容複製到新的陣列。

ToString()

傳回此 Span<T> 物件的字串表示。

TryCopyTo(Span<T>)

嘗試將目前的 Span<T> 複製到目的地 Span<T>,並傳回值,指出複製作業是否成功。

運算子

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

傳回值,指出兩個 Span<T> 物件是否相等。

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

定義從 ArraySegment<T>Span<T> 的隱含轉換。

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

定義從 Span<T>ReadOnlySpan<T> 的隱含轉換。

Implicit(T[] to Span<T>)

定義從陣列到 Span<T> 的隱含轉換。

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

傳回值,指出兩個 Span<T> 物件是否不相等。

擴充方法

ToImmutableArray<T>(Span<T>)

將範圍轉換為不可變的陣列。

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

使用指定的 IComparable<T> 泛型介面,在整個已排序的 Span<T> 中搜尋值。

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

使用指定的 TComparer 泛型型別,在整個已排序的 Span<T> 中搜尋指定的值。

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

使用指定的 TComparable 泛型型別,在整個已排序的 Span<T> 中搜尋值。

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

尋找 與 other 之間共用之任何通用前置詞的 span 長度。

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

尋找 與 other 之間共用之任何通用前置詞的 span 長度。

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

指出是否在範圍中找到指定的值。 值是使用 IEquatable{T}.Equals(T) 來進行比較。

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

判斷所指定序列是否出現在範圍的結尾。

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

搜尋指定的值,並傳回第一個出現位置的索引。 值是使用 IEquatable{T}.Equals(T) 來進行比較。

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

搜尋指定的序列,並傳回第一個出現位置的索引。 值是使用 IEquatable{T}.Equals(T) 來進行比較。

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

搜尋任何指定值的第一個索引,類似於使用邏輯 OR 運算子呼叫 IndexOf 多次。

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

搜尋任何指定值的第一個索引,類似於使用邏輯 OR 運算子呼叫 IndexOf 多次。

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

搜尋任何指定值的第一個索引,類似於使用邏輯 OR 運算子呼叫 IndexOf 多次。

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

搜尋指定 以外的任何值 value 的第一個索引。

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

搜尋指定 value0value1 以外的任何值的第一個索引。

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

搜尋指定 value0value1value2 以外的任何值的第一個索引。

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

搜尋指定 以外的任何值 values 的第一個索引。

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

搜尋指定的值,並傳回最後一個出現位置的索引。 值是使用 IEquatable{T}.Equals(T) 來進行比較。

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

搜尋指定的序列,並傳回最後一個出現位置的索引。 值是使用 IEquatable{T}.Equals(T) 來進行比較。

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

搜尋任何指定值的最後一個索引,類似於使用邏輯 OR 運算子呼叫 LastIndexOf 多次。

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

搜尋任何指定值的最後一個索引,類似於使用邏輯 OR 運算子呼叫 LastIndexOf 多次。

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

搜尋任何指定值的最後一個索引,類似於使用邏輯 OR 運算子呼叫 LastIndexOf 多次。

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

搜尋指定 以外的任何值的最後一 value 個索引。

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

搜尋指定 value0value1 以外的任何值的最後一個索引。

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

搜尋指定 value0value1value2 以外的任何值的最後一個索引。

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

搜尋指定 以外的任何值的最後一 values 個索引。

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

判斷一個範圍和一個唯讀範圍在記憶體中是否重疊。

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

判斷一個範圍和一個唯讀範圍在記憶體中是否重疊,並輸出元素位移。

Reverse<T>(Span<T>)

反轉整個範圍中的元素順序。

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

使用 IComparable{T}.CompareTo(T) 來比較元素,判斷一個範圍和一個唯讀範圍的相對順序。

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

使用 IEquatable{T}.Equals(T) 來比較元素,判斷一個範圍和一個唯讀範圍是否相等。

SequenceEqual<T>(Span<T>, ReadOnlySpan<T>, IEqualityComparer<T>)

使用 比較專案,判斷兩個 IEqualityComparer<T> 序列是否相等。

Sort<T>(Span<T>)

使用 IComparable<T> 的每個 專案實作,排序整個 Span<T> 中的 Span<T> 專案。

Sort<T>(Span<T>, Comparison<T>)

使用指定的 Comparison<T> 來排序在整個 Span<T> 中的項目。

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

使用 TComparer 來排序整個 Span<T> 中的項目。

Sort<TKey,TValue>(Span<TKey>, Span<TValue>)

使用每個索引鍵的 IComparable<T> 實作,根據第一個 Span<T> 中的索引鍵,排序一對範圍 (其中一個範圍包含索引鍵,另一個範圍包含對應的項目)。

Sort<TKey,TValue>(Span<TKey>, Span<TValue>, Comparison<TKey>)

使用指定的比較,根據第一個 Span<T> 中的索引鍵來排序一對範圍 (其中一個範圍包含索引鍵,另一個範圍包含對應的項目)。

Sort<TKey,TValue,TComparer>(Span<TKey>, Span<TValue>, TComparer)

使用指定的比較子,根據第一個 Span<T> 中的索引鍵來排序一對範圍 (其中一個範圍包含索引鍵,另一個範圍包含對應的項目)。

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

判斷所指定序列是否出現在範圍的開頭。

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

從範圍中移除所有開頭和尾端指定元素項目。

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

從範圍中移除唯讀範圍中指定的所有開頭和尾端元素集項目。

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

從範圍中移除所有尾端指定元素項目。

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

從範圍中移除唯讀範圍中指定的所有尾端元素集項目。

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

從範圍中移除所有開頭指定元素項目。

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

從範圍中移除唯讀範圍中指定的所有開頭元素集項目。

適用於

另請參閱