Span<T> 구조체

정의

인접한 임의의 메모리 영역에 대해 형식 및 메모리 안전 표현을 제공합니다.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> 는 관리형 힙이 아닌 스택에 할당되는 ref 구조체 입니다.Span<T> is a ref struct that is allocated on the stack rather than on the managed heap. Ref 구조체 형식을 제한 하는 수준을 올릴 수 없습니다를 넣을 수 없습니다, 형식의 변수에 할당할 수 없는 관리 되는 힙에 하도록 많은 Object, dynamic 임의의 인터페이스 형식에서 필드 일 수 없습니다 또는 참조 형식 있으며에서 사용할 수 없습니다 awaityield 경계입니다.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을 throw를 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(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

범위<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> 개체를 만듭니다.Creates a new Span<T> object over the entirety of a specified array.

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.

Span<T>(Void*, Int32)

지정된 메모리 주소에서 시작하는 지정된 T 수로부터 새로운 Span<T> 개체를 만듭니다.Creates a new Span<T> object from a specified number of T elements starting at a specified memory address.

속성

Empty

Span<T> 개체를 반환합니다.Returns an empty Span<T> object.

IsEmpty

현재 Span<T>가 비어 있는지 여부를 나타내는 값을 반환합니다.Returns a value that indicates whether the current Span<T> is empty.

Item[Int32]

지정된 인덱스(0부터 시작)에서 요소를 가져옵니다.Gets the element at the specified zero-based index.

Length

현재 범위의 길이를 설정합니다.Returns the length of the current span.

메서드

Clear()

Span<T> 개체의 콘텐츠를 지웁니다.Clears the contents of this Span<T> object.

CopyTo(Span<T>)

Span<T>의 콘텐츠를 대상 Span<T>로 복사합니다.Copies the contents of this Span<T> into a destination Span<T>.

Equals(Object)

이 메서드의 호출은 지원되지 않습니다.Calls to this method are not supported.

Fill(T)

지정된 값으로 이 범위의 요소를 채웁니다.Fills the elements of this span with a specified value.

GetEnumerator()

Span<T>에 대한 열거자를 반환합니다.Returns an enumerator for this Span<T>.

GetHashCode()

NotSupportedException를 throw합니다.Throws a NotSupportedException.

GetPinnableReference()

인덱스 0에서 Span<T>의 마지막 요소에 대한 참조를 반환합니다.Returns a reference to the element of the Span<T> at index zero.

Slice(Int32)

지정된 인덱스로 시작되는 현재 범위에서 하나의 조각을 형성합니다.Forms a slice out of the current span that begins at a specified index.

Slice(Int32, Int32)

지정된 길이 대해 지정된 인덱스에서 시작하는 현재 범위에서 벗어난 조각을 형성합니다.Forms a slice out of the current span starting at a specified index for a specified length.

ToArray()

이 범위의 콘텐츠를 새 배열로 복사합니다.Copies the contents of this span into a new array.

ToString()

Span<T> 개체의 문자열 표현을 반환합니다.Returns the string representation of this Span<T> object.

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

Span<T> 개체가 같은지 여부를 나타내는 값을 반환합니다.Returns a value that indicates whether two Span<T> objects are equal.

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

Span<T>ReadOnlySpan<T>로 변환하는 암시적 변환을 정의합니다.Defines an implicit conversion of a Span<T> to a ReadOnlySpan<T>.

Implicit(T[] to Span<T>)

배열을 Span<T>로 변환하는 암시적 변환을 정의합니다.Defines an implicit conversion of an array to a Span<T>.

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

Span<T> 개체가 같지 않은지 여부를 나타내는 값을 반환합니다.Returns a value that indicates whether two Span<T> objects are not equal.

확장 메서드

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

지정한 Span<T> 제네릭 인터페이스를 사용하여 정렬된 전체 IComparable<T>에서 값을 검색합니다.Searches an entire sorted Span<T> for a value using the specified IComparable<T> generic interface.

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

지정한 Span<T> 제네릭 형식을 사용하여 정렬된 전체 TComparer에서 지정된 값을 검색합니다.Searches an entire sorted Span<T> for a specified value using the specified TComparer generic type.

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

지정한 Span<T> 제네릭 형식을 사용하여 정렬된 전체 TComparable에서 값을 검색합니다.Searches an entire sorted Span<T> for a value using the specified TComparable generic type.

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

범위에서 지정된 값을 찾을 수 있는지를 나타냅니다.Indicates whether a specified value is found in a span. IEquatable{T}.Equals(T)를 사용하여 값을 비교합니다.Values are compared using IEquatable{T}.Equals(T).

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

지정된 시퀀스가 범위 끝에 표시되는지 여부를 확인합니다.Determines whether the specified sequence appears at the end of a span.

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

지정한 값을 검색하고 맨 처음 발생하는 인덱스를 반환합니다.Searches for the specified value and returns the index of its first occurrence. IEquatable{T}.Equals(T)를 사용하여 값을 비교합니다.Values are compared using IEquatable{T}.Equals(T).

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

지정한 시퀀스를 검색하고 맨 처음 발생하는 인덱스를 반환합니다.Searches for the specified sequence and returns the index of its first occurrence. IEquatable{T}.Equals(T)를 사용하여 값을 비교합니다.Values are compared using IEquatable{T}.Equals(T).

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

논리 OR 연산자를 사용하여 IndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 첫 번째 인덱스를 검색합니다.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

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

논리 OR 연산자를 사용하여 IndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 첫 번째 인덱스를 검색합니다.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

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

논리 OR 연산자를 사용하여 IndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 첫 번째 인덱스를 검색합니다.Searches for the first index of any of the specified values similar to calling IndexOf several times with the logical OR operator.

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

지정한 값을 검색하고 마지막으로 발생하는 인덱스를 반환합니다.Searches for the specified value and returns the index of its last occurrence. IEquatable{T}.Equals(T)를 사용하여 값을 비교합니다.Values are compared using IEquatable{T}.Equals(T).

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

지정한 시퀀스를 검색하고 마지막으로 발생하는 인덱스를 반환합니다.Searches for the specified sequence and returns the index of its last occurrence. IEquatable{T}.Equals(T)를 사용하여 값을 비교합니다.Values are compared using IEquatable{T}.Equals(T).

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

논리 OR 연산자를 사용하여 LastIndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 마지막 인덱스를 검색합니다.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

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

논리 OR 연산자를 사용하여 LastIndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 마지막 인덱스를 검색합니다.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

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

논리 OR 연산자를 사용하여 LastIndexOf를 여러 번 호출하는 것과 유사한 지정된 값의 마지막 인덱스를 검색합니다.Searches for the last index of any of the specified values similar to calling LastIndexOf several times with the logical OR operator.

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

범위와 읽기 전용 범위가 메모리에서 겹치는지 여부를 확인합니다.Determines whether a span and a read-only span overlap in memory.

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

범위와 읽기 전용 범위가 메모리에서 겹치는지 여부를 확인하고 요소 오프셋을 출력합니다.Determines whether a span and a read-only span overlap in memory and outputs the element offset.

Reverse<T>(Span<T>)

전체 범위에 있는 요소의 시퀀스를 역순으로 바꿉니다.Reverses the sequence of the elements in the entire span.

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

IComparable{T}.CompareTo(T)를 사용하여 요소를 비교하여 범위 및 읽기 전용 범위의 상대 순서를 확인합니다.Determines the relative order of a span and a read-only span by comparing the elements using IComparable{T}.CompareTo(T).

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

IEquatable{T}.Equals(T)를 사용하여 요소를 비교하여 범위 및 읽기 전용 범위가 같은지 여부를 확인합니다.Determines whether a span and a read-only span are equal by comparing the elements using IEquatable{T}.Equals(T).

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

지정된 시퀀스가 범위의 시작 부분에 표시되는지 여부를 확인합니다.Determines whether a specified sequence appears at the start of a span.

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

범위에서 지정된 요소의 선행 및 후행 발생 항목을 모두 제거합니다.Removes all leading and trailing occurrences of a specified element from a span.

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

읽기 전용 범위에 지정된 요소 집합의 선행 및 후행 발생 항목을 범위에서 모두 제거합니다.Removes all leading and trailing occurrences of a set of elements specified in a read-only span from a span.

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

범위에서 지정된 요소의 후행 발생 항목을 모두 제거합니다.Removes all trailing occurrences of a specified element from a span.

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

읽기 전용 범위에 지정된 요소 집합의 후행 발생 항목을 범위에서 모두 제거합니다.Removes all trailing occurrences of a set of elements specified in a read-only span from a span.

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

범위에서 지정된 요소의 선행 발생 항목을 모두 제거합니다.Removes all leading occurrences of a specified element from the span.

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

읽기 전용 범위에 지정된 요소 집합의 선행 발생 항목을 범위에서 모두 제거합니다.Removes all leading occurrences of a set of elements specified in a read-only span from the span.

적용 대상