Span<T> Structure

Définition

Fournit une représentation de type sécurisé et de mémoire sécurisée d’une région contiguë de mémoire arbitraire.

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

Paramètres de type

T

Type d’éléments dans le Span<T>.

Héritage
Span<T>

Remarques

Span<T> est un struct ref qui est alloué sur la pile plutôt que sur le tas managé. Les types de struct ref ont un certain nombre de restrictions pour s’assurer qu’ils ne peuvent pas être promus vers le tas managé, y compris qu’ils ne peuvent pas être boxés, ils ne peuvent pas être affectés à des variables de type Object, dynamic ou à n’importe quel type d’interface, ils ne peuvent pas être des champs dans un type de référence et ils ne peuvent pas être utilisés entre await les yield limites. En outre, les appels à deux méthodes Equals(Object) et GetHashCode, lèvent un NotSupportedException.

Important

Étant donné qu’il s’agit d’un type de pile uniquement, Span<T> il n’est pas adapté à de nombreux scénarios qui nécessitent le stockage de références aux mémoires tampons sur le tas. C’est vrai, par exemple, des routines qui effectuent des appels de méthode asynchrones. Pour ces scénarios, vous pouvez utiliser les types complémentaires et System.ReadOnlyMemory<T> les System.Memory<T> types.

Pour les étendues qui représentent des structures immuables ou en lecture seule, utilisez System.ReadOnlySpan<T>.

Étendue<T> et mémoire

Un Span<T> représente une région contiguë de mémoire arbitraire. Une Span<T> instance est souvent utilisée pour contenir les éléments d’un tableau ou d’une partie d’un tableau. Contrairement à un tableau, toutefois, une Span<T> instance peut pointer vers la mémoire managée, la mémoire native ou la mémoire gérée sur la pile. L’exemple suivant crée un Span<Byte> tableau :

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

L’exemple suivant crée une Span<Byte> valeur de 100 octets de mémoire native :

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

L’exemple suivant utilise le mot clé stackalloc C# pour allouer 100 octets de mémoire sur la pile :

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

Étant donné qu’il Span<T> s’agit d’une abstraction sur un bloc de mémoire arbitraire, les méthodes du Span<T> type et des méthodes avec Span<T> des paramètres fonctionnent sur n’importe quel Span<T> objet, quel que soit le type de mémoire qu’il encapsule. Par exemple, chacune des sections distinctes du code qui initialisent l’étendue et calcule la somme de ses éléments peut être modifiée en méthodes d’initialisation et de calcul uniques, comme l’illustre l’exemple suivant :

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

Étendues<T> et tableaux

Lorsqu’il encapsule un tableau, Span<T> il peut encapsuler un tableau entier, comme il l’a fait dans les exemples de la section Étendue<T> et mémoire . Étant donné qu’il prend en charge la découpage, Span<T> peut également pointer vers n’importe quelle plage contiguë au sein du tableau.

L’exemple suivant crée une tranche des cinq éléments du milieu d’un tableau entier de 10 éléments. Notez que le code double les valeurs de chaque entier dans la tranche. Comme le montre la sortie, les modifications apportées par l’étendue sont reflétées dans les valeurs du tableau.

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

Étendues<T> et tranches

Span<T> inclut deux surcharges de la Slice méthode qui forment une tranche hors de l’étendue actuelle qui commence à un index spécifié. Cela permet de traiter les données dans un Span<T> ensemble de blocs logiques qui peuvent être traités selon les besoins d’un pipeline de traitement des données avec un impact minimal sur les performances. Par exemple, étant donné que les protocoles serveur modernes sont souvent basés sur du texte, la manipulation de chaînes et de sous-chaînes est particulièrement importante. Dans la String classe, la méthode principale pour l’extraction de sous-chaînes est Substring. Pour les pipelines de données qui s’appuient sur une manipulation de chaîne étendue, son utilisation offre des pénalités de performances, car elle :

  1. Crée une chaîne pour contenir la sous-chaîne.

  2. Copie un sous-ensemble des caractères de la chaîne d’origine vers la nouvelle chaîne.

Cette opération d’allocation et de copie peut être éliminée à l’aide Span<T> de l’un ou ReadOnlySpan<T>l’autre, comme l’illustre l’exemple suivant :

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

Constructeurs

Span<T>(T[])

Crée un objet Span<T> sur l’intégralité d’un tableau spécifié.

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

Crée un objet Span<T> qui inclut un nombre spécifié d’élément à partir d’un tableau commençant à l’index spécifié.

Span<T>(Void*, Int32)

Crée un objet Span<T> à partir d’un nombre spécifié d’éléments T commençant à une adresse mémoire spécifiée.

Propriétés

Empty

Retourne un objet Span<T> vide.

IsEmpty

Retourne une valeur qui indique si le Span<T> actuel est vide.

Item[Int32]

Obtient l’élément au niveau de l’index de base zéro spécifié.

Length

Retourne la longueur de l’étendue actuelle.

Méthodes

Clear()

Efface le contenu de cet objet Span<T>.

CopyTo(Span<T>)

Copie le contenu de ce Span<T> dans un Span<T> de destination.

Equals(Object)
Obsolète.
Obsolète.

Les appels à cette méthode ne sont pas pris en charge.

Fill(T)

Remplit les éléments de cette étendue avec une valeur spécifiée.

GetEnumerator()

Retourne un énumérateur pour ce Span<T>.

GetHashCode()
Obsolète.

Lève un NotSupportedException.

GetPinnableReference()

Retourne une référence à un objet de type T qui peut être utilisé pour l’épinglage.

Cette méthode est destinée à prendre en charge les compilateurs .NET et n’est pas destinée à être appelée par le code utilisateur.

Slice(Int32)

Constitue une section en dehors de l’étendue actuelle qui commence à l’index spécifié.

Slice(Int32, Int32)

Constitue une section en dehors de l’étendue actuelle qui commence à un index spécifié pour une longueur spécifiée.

ToArray()

Copie le contenu de cette étendue dans un nouveau tableau.

ToString()

Retourne la représentation sous forme de chaîne de cet objet Span<T>.

TryCopyTo(Span<T>)

Tente de copier le Span<T> actuel vers un Span<T> de destination et retourne une valeur qui indique si l’opération de copie a réussi.

Opérateurs

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

Retourne une valeur qui indique si deux objets Span<T> sont égaux.

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

Définit une conversion implicite d’un ArraySegment<T> en Span<T>.

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

Définit une conversion implicite d’un Span<T> en ReadOnlySpan<T>.

Implicit(T[] to Span<T>)

Définit une conversion implicite d’un tableau en Span<T>.

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

Retourne une valeur qui indique si deux objets Span<T> ne sont pas égaux.

Méthodes d’extension

ToImmutableArray<T>(Span<T>)

Convertit l’étendue en tableau immuable.

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

Recherche une valeur dans une Span<T> entière triée en utilisant l’interface générique IComparable<T> spécifiée.

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

Recherche une valeur spécifiée dans une Span<T> entière triée en utilisant le type générique TComparer spécifié.

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

Recherche une valeur dans une Span<T> entière triée en utilisant le type générique TComparable spécifié.

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

Recherche la longueur d’un préfixe commun partagé entre span et other.

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

Recherche la longueur d’un préfixe commun partagé entre span et other.

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

Indique si une valeur spécifiée est trouvée dans une étendue. Les valeurs sont comparées en utilisant IEquatable{T}.Equals(T).

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

Détermine si la séquence spécifiée apparaît à la fin d’une étendue.

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

Recherche la valeur spécifiée et retourne l’index de sa première occurrence. Les valeurs sont comparées en utilisant IEquatable{T}.Equals(T).

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

Recherche la séquence spécifiée et retourne l’index de sa première occurrence. Les valeurs sont comparées en utilisant IEquatable{T}.Equals(T).

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

Recherche le premier index de l’une des valeurs spécifiées similaires à l’appel d’IndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le premier index de l’une des valeurs spécifiées similaires à l’appel d’IndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le premier index de l’une des valeurs spécifiées similaires à l’appel d’IndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le premier index de n’importe quelle valeur autre que celle spécifiée value.

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

Recherche le premier index d’une valeur autre que celle spécifiée value0 ou value1.

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

Recherche le premier index d’une valeur autre que le value0, value1ou value2.

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

Recherche le premier index de n’importe quelle valeur autre que celle spécifiée values.

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

Recherche la valeur spécifiée et retourne l’index de sa dernière occurrence. Les valeurs sont comparées en utilisant IEquatable{T}.Equals(T).

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

Recherche la séquence spécifiée et retourne l’index de sa dernière occurrence. Les valeurs sont comparées en utilisant IEquatable{T}.Equals(T).

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

Recherche le dernier index de l’une des valeurs spécifiées similaires à l’appel de LastIndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le dernier index de l’une des valeurs spécifiées similaires à l’appel de LastIndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le dernier index de l’une des valeurs spécifiées similaires à l’appel de LastIndexOf plusieurs fois avec l’opérateur OR logique.

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

Recherche le dernier index de n’importe quelle valeur autre que celle spécifiée value.

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

Recherche le dernier index de n’importe quelle valeur autre que celle spécifiée value0 ou value1.

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

Recherche le dernier index de n’importe quelle valeur autre que le value0, ou value1value2.

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

Recherche le dernier index de n’importe quelle valeur autre que celle spécifiée values.

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

Détermine si une étendue et une étendue en lecture seule se chevauchent dans la mémoire.

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

Détermine si une étendue et une étendue en lecture seule se chevauchent dans la mémoire et génère le décalage des éléments.

Reverse<T>(Span<T>)

Inverse la séquence des éléments dans l’intégralité de l’étendue.

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

Détermine l’ordre relatif d’une étendue et d’une étendue en lecture seule en comparant les éléments avec IComparable{T}.CompareTo(T).

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

Détermine si une étendue et une étendue en lecture seule sont égales en comparant les éléments avec IEquatable{T}.Equals(T).

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

Détermine si deux séquences sont égales en comparant les éléments à l’aide d’un IEqualityComparer<T>.

Sort<T>(Span<T>)

Trie les éléments dans l’ensemble Span<T> à l’aide de l’implémentation IComparable<T> de chaque élément du Span<T>.

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

Trie les éléments dans l'ensemble de Span<T> à l'aide du Comparison<T> spécifié.

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

Trie les éléments dans l’ensemble de Span<T> à l’aide de TComparer.

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

Trie une paire d’étendues (l’une contenant les clés et l’autre contenant les éléments correspondants) en fonction des clés du premier Span<T> à l’aide de l’implémentation IComparable<T>de chaque clé.

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

Trie une paire d’étendues (une contenant les clés et l’autre contenant les éléments correspondants) en fonction des clés dans la première Span<T> à l’aide de la comparaison spécifiée.

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

Trie une paire d’étendues (une contenant les clés et l’autre contenant les éléments correspondants) en fonction des clés dans la première Span<T> à l’aide du comparateur spécifié.

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

Détermine si une séquence spécifiée apparaît au début d’une étendue.

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

Supprime d’une étendue toutes les occurrences de début et de fin d’un élément spécifié.

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

Supprime d’une étendue toutes les occurrences de début et de fin d’un jeu d’éléments spécifié dans une étendue en lecture seule.

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

Supprime d’une étendue toutes les occurrences de fin d’un élément spécifié.

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

Supprime d’une étendue toutes les occurrences de fin d’un jeu d’éléments spécifié dans une étendue en lecture seule.

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

Supprime de l’étendue toutes les occurrences de début d’un élément spécifié.

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

Supprime d’une étendue toutes les occurrences de début d’un jeu d’éléments spécifié dans une étendue en lecture seule.

S’applique à

Voir aussi