Span<T> 结构

定义

提供任意内存的连续区域的类型安全和内存安全表示形式。

generic <typename T>
public value class Span
public readonly ref struct Span<T>
[System.Runtime.InteropServices.Marshalling.NativeMarshalling(typeof(System.Runtime.InteropServices.Marshalling.SpanMarshaller<,>))]
public readonly ref struct Span<T>
type Span<'T> = struct
[<System.Runtime.InteropServices.Marshalling.NativeMarshalling(typeof(System.Runtime.InteropServices.Marshalling.SpanMarshaller<,>))>]
type Span<'T> = struct
Public Structure Span(Of T)

类型参数

T

Span<T>项的类型。

继承
Span<T>
属性

注解

Span<T> 是在堆栈而不是托管堆上分配的 ref 结构 。 Ref 结构类型有许多限制,以确保它们不能提升到托管堆,包括不能装箱、不能分配给 类型的Objectdynamic变量或任何接口类型,它们不能是引用类型中的字段,也不能跨 awaityield 边界使用。 此外,对和 两个NotSupportedException方法的 Equals(Object)GetHashCode调用会引发 。

重要

因为它是仅堆栈类型, 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

以下示例从 100 字节的本机内存中创建 Span<Byte>

// 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 关键字 (keyword) 在堆栈上分配 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 个元素整数数组的中间 5 个元素的切片。 请注意,代码会将切片中每个整数的值加倍。 如输出所示,范围所做的更改反映在数组的值中。

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. 将原始字符串中的字符子集复制到新字符串。

通过使用 Span<T>ReadOnlySpan<T>可以消除此分配和复制操作,如以下示例所示:

using System;

class Program2
{
    static void Run()
    {
        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)

围绕指定的引用创建一个长度为 1 的新 Span<T>

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) 比较各值。

ContainsAny<T>(Span<T>, T, T)

搜索 或 value1value0匹配项,如果找到 ,则true返回 。 如果未找到,则 false返回 。

ContainsAny<T>(Span<T>, T, T, T)

搜索 、 或 value2value0value1匹配项,如果找到 ,则true返回 。 如果未找到,则 false返回 。

ContainsAny<T>(Span<T>, SearchValues<T>)

搜索任何指定的 values 匹配项,如果找到,则 true 返回 。 如果未找到,则 false返回 。

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

搜索任何指定的 values 匹配项,如果找到,则 true 返回 。 如果未找到,则 false返回 。

ContainsAnyExcept<T>(Span<T>, T)

搜索指定 value以外的任何值。

ContainsAnyExcept<T>(Span<T>, T, T)

搜索 除 或 value1以外的value0任何值。

ContainsAnyExcept<T>(Span<T>, T, T, T)

搜索除 、 value1value2以外的value0任何值。

ContainsAnyExcept<T>(Span<T>, SearchValues<T>)

搜索指定 values以外的任何值。

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

搜索指定 values以外的任何值。

ContainsAnyExceptInRange<T>(Span<T>, T, T)

在 和 highInclusive之间lowInclusive搜索范围之外的任何值(包括 )。

ContainsAnyInRange<T>(Span<T>, T, T)

搜索 介于 和 highInclusive之间的lowInclusive范围内的任何值(包括 ),如果找到 ,则true返回 。 如果未找到,则 false返回 。

Count<T>(Span<T>, T)

计算指定的 value 在 中 span发生的次数。

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

计算指定的 value 在 中 span发生的次数。

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>, SearchValues<T>)

搜索任何指定值的第一个索引。

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>, SearchValues<T>)

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

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

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

IndexOfAnyExceptInRange<T>(Span<T>, T, T)

在 和 highInclusive之间lowInclusive搜索范围之外的任何值的第一个索引,包括 。

IndexOfAnyInRange<T>(Span<T>, T, T)

在 和 highInclusive之间lowInclusive搜索任何值的第一个索引,包括 。

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>, SearchValues<T>)

搜索任何指定值的最后一个索引。

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>, SearchValues<T>)

搜索指定 values值以外的任何值的最后一个索引。

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

搜索指定 values值以外的任何值的最后一个索引。

LastIndexOfAnyExceptInRange<T>(Span<T>, T, T)

搜索 和 highInclusive之间的lowInclusive范围之外的任何值的最后一个索引,包括 。

LastIndexOfAnyInRange<T>(Span<T>, T, T)

搜索 和 highInclusive之间的lowInclusive任何值的最后一个索引,包括 。

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

确定跨度和只读跨度是否在内存中重叠。

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

确定跨度和只读跨度是否在内存中重叠且输出元素偏移。

Replace<T>(Span<T>, T, T)

将所有 oldValue 项都替换为 newValue

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

基于第一个 Span<T> 中的键,使用每个键的 IComparable<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>)

从跨度中删除在只读跨度中指定的一组元素的所有前导出现次数。

适用于

另请参阅