Class Sequence<T>

Namespace

Nerdbank.Streams

Assembly

Nerdbank.Streams.dll

Manages a sequence of elements, readily castable as a ReadOnlySequence<T>.

public class Sequence<T> : IBufferWriter<T>, IDisposable

Type Parameters

T

The type of element stored by the sequence.

Inheritance

object

Sequence<T>

Implements

IBufferWriter<T>

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BufferWriterExtensions.Write<T>(IBufferWriter<T>, ReadOnlySequence<T>)

Remarks

Instance members are not thread-safe.

Constructors

Sequence()

Initializes a new instance of the Sequence<T> class that uses a private ArrayPool<T> for recycling arrays.

public Sequence()

Sequence(ArrayPool<T>)

Initializes a new instance of the Sequence<T> class.

public Sequence(ArrayPool<T> arrayPool)

Parameters

arrayPool ArrayPool<T>

The pool to use for recycling backing arrays.

Sequence(MemoryPool<T>)

Initializes a new instance of the Sequence<T> class.

public Sequence(MemoryPool<T> memoryPool)

Parameters

memoryPool MemoryPool<T>

The pool to use for recycling backing arrays.

Properties

AsReadOnlySequence

Gets this sequence expressed as a ReadOnlySequence<T>.

public ReadOnlySequence<T> AsReadOnlySequence { get; }

Property Value

ReadOnlySequence<T>

A read only sequence representing the data in this object.

AutoIncreaseMinimumSpanLength

Gets or sets a value indicating whether the MinimumSpanLength should be intelligently increased as the length of the sequence grows.

public bool AutoIncreaseMinimumSpanLength { get; set; }

Property Value

bool

Remarks

This can help prevent long sequences made up of many very small arrays.

Length

Gets the length of the sequence.

public long Length { get; }

Property Value

long

MinimumSpanLength

Gets or sets the minimum length for any array allocated as a segment in the sequence. Any non-positive value allows the pool to determine the length of the array.

public int MinimumSpanLength { get; set; }

Property Value

int

The default value is 0.

Remarks

Each time GetSpan(int) or GetMemory(int) is called, previously allocated memory is used if it is large enough to satisfy the length demand. If new memory must be allocated, the argument to one of these methods typically dictate the length of array to allocate. When the caller uses very small values (just enough for its immediate need) but the high level scenario can predict that a large amount of memory will be ultimately required, it can be advisable to set this property to a value such that just a few larger arrays are allocated instead of many small ones.

The MemoryPool<T> in use may itself have a minimum array length as well, in which case the higher of the two minimums dictate the minimum array size that will be allocated.

If AutoIncreaseMinimumSpanLength is true, this value may be automatically increased as the length of a sequence grows.

Methods

Advance(int)

Advances the sequence to include the specified number of elements initialized into memory returned by a prior call to GetMemory(int).

public void Advance(int count)

Parameters

count int

The number of elements written into memory.

AdvanceTo(SequencePosition)

Removes all elements from the sequence from its beginning to the specified position, considering that data to have been fully processed.

public void AdvanceTo(SequencePosition position)

Parameters

position SequencePosition

The position of the first element that has not yet been processed. This is typically End after reading all elements from that instance.

Append(ReadOnlyMemory<T>)

Adds an existing memory location to this sequence without copying.

public void Append(ReadOnlyMemory<T> memory)

Parameters

memory ReadOnlyMemory<T>

The memory to add.

Remarks

This may leave significant slack space in a previously allocated block if calls to Append(ReadOnlyMemory<T>) follow calls to GetMemory(int) or GetSpan(int).

GetMemory(int)

Gets writable memory that can be initialized and added to the sequence via a subsequent call to Advance(int).

public Memory<T> GetMemory(int sizeHint)

Parameters

sizeHint int

The size of the memory required, or 0 to just get a convenient (non-empty) buffer.

Returns

Memory<T>

The requested memory.

GetSpan(int)

Gets writable memory that can be initialized and added to the sequence via a subsequent call to Advance(int).

public Span<T> GetSpan(int sizeHint)

Parameters

sizeHint int

The size of the memory required, or 0 to just get a convenient (non-empty) buffer.

Returns

Span<T>

The requested memory.

Reset()

Clears the entire sequence and recycles associated memory into pools. This invalidates any ReadOnlySequence<T> previously produced by this instance.

public void Reset()

Operators

implicit operator ReadOnlySequence<T>(Sequence<T>?)

Expresses this sequence as a ReadOnlySequence<T>.

public static implicit operator ReadOnlySequence<T>(Sequence<T>? sequence)

Parameters

sequence Sequence<T>

The sequence to convert.

Returns

ReadOnlySequence<T>