Span<T> 结构
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
提供任意内存的连续区域的类型安全和内存安全表示形式。
generic <typename T>
public value class Spanpublic 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> = structPublic Structure Span(Of T)类型参数
- T
中 Span<T>项的类型。
- 继承
- 属性
注解
Span<T> 是在堆栈而不是托管堆上分配的 ref 结构 。 Ref 结构类型有许多限制，以确保它们不能提升到托管堆，包括不能装箱、不能分配给 类型的Objectdynamic变量或任何接口类型，它们不能是引用类型中的字段，也不能跨 await 和 yield 边界使用。 此外，对和 两个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的主要方法是 。 对于依赖于大量字符串操作的数据管道，其使用会产生一些性能损失，因为它：
创建一个新字符串来保存子字符串。
将原始字符串中的字符子集复制到新字符串。
通过使用 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) |
从指定数量的 |
属性
| Empty |
返回空的 Span<T> 对象。 |
| IsEmpty |
返回一个值，该值指示当前的 Span<T> 是否为空。 |
| Item[Int32] |
获取指定基于零的索引处的元素。 |
| Length |
返回当前范围的长度。 |
方法
| Clear() |
清除此 Span<T> 对象的内容。 |
| CopyTo(Span<T>) | |
| Equals(Object) |
已过时。
已过时。
不支持对此方法的调用。 |
| Fill(T) |
用指定的值填充此范围的元素。 |
| GetEnumerator() |
返回用于此 Span<T> 的枚举器。 |
| GetHashCode() |
已过时。
|
| GetPinnableReference() |
返回对 T 类型的对象的引用，该对象可用于固定。 此方法旨在支持 .NET 编译器，而不是由用户代码调用。 |
| Slice(Int32) |
从指定索引处开始的当前范围外形成切片。 |
| Slice(Int32, Int32) |
从指定长度的指定索引处开始，在当前范围外形成切片。 |
| ToArray() |
将此范围的内容复制到新数组中。 |
| ToString() |
返回此 Span<T> 对象的字符串表示形式。 |
| TryCopyTo(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> 对象是否不相等。 |