Class SparseBufferWriter<T>

Represents builder of the sparse memory buffer.

Inheritance
object
Disposable
SparseBufferWriter<T>
SequenceBuilder<T>
Implements
Inherited Members
Namespace: DotNext.Buffers
Assembly: DotNext.dll
Syntax
public class SparseBufferWriter<T> : Disposable, IGrowableBuffer<T>, IReadOnlySpanConsumer<T>, ISupplier<ReadOnlyMemory<T>, CancellationToken, ValueTask>, IFunctional<Func<ReadOnlyMemory<T>, CancellationToken, ValueTask>>, IDisposable, IResettable, ISupplier<ReadOnlySequence<T>>, IFunctional<Func<ReadOnlySequence<T>>>, IEnumerable<ReadOnlyMemory<T>>, IEnumerable, IBufferWriter<T>
Type Parameters
Name Description
T

The type of the elements in the memory.
Remarks

All members of IBufferWriter<T> are explicitly implemented because their usage can produce holes in the sparse buffer. To avoid holes, use public members only.

Constructors

| Edit this page View Source

SparseBufferWriter()

Initializes a new builder which uses Shared as a default allocator of buffers.

Declaration
public SparseBufferWriter()
| Edit this page View Source

SparseBufferWriter(MemoryPool<T>)

Initializes a new builder with automatically selected chunk size.

Declaration
public SparseBufferWriter(MemoryPool<T> pool)
Parameters
Type Name Description
MemoryPool<T> pool

Memory pool used to allocate memory chunks.
| Edit this page View Source

SparseBufferWriter(int, SparseBufferGrowth, MemoryAllocator<T>?)

Initializes a new builder with the specified size of memory block.

Declaration
public SparseBufferWriter(int chunkSize, SparseBufferGrowth growth = SparseBufferGrowth.None, MemoryAllocator<T>? allocator = null)
Parameters
Type Name Description
int chunkSize

The size of the memory block representing single segment within sequence.
SparseBufferGrowth growth

Specifies how the memory should be allocated for each subsequent chunk in this buffer.
MemoryAllocator<T> allocator

The allocator used to rent the segments.
Exceptions
Type Condition
ArgumentOutOfRangeException

chunkSize is less than or equal to zero.

Properties

| Edit this page View Source

End

Gets the current write position within the buffer.

Declaration
public SequencePosition End { get; }
Property Value
Type Description
SequencePosition
Remarks

Position within the buffer can be used later to retrieve the portion of data placed to the buffer. However, the call of Clear() method invalidates any position object. The value of this property remains unchanged between invocations of read-only operations.

See Also
| Edit this page View Source

IsSingleSegment

Gets a value indicating that this buffer consists of a single segment.

Declaration
public bool IsSingleSegment { get; }
Property Value
Type Description
bool
| Edit this page View Source

Start

Gets the position of the first chunk of data within the buffer.

Declaration
public SequencePosition Start { get; }
Property Value
Type Description
SequencePosition
| Edit this page View Source

WrittenCount

Gets the number of written elements.

Declaration
public long WrittenCount { get; }
Property Value
Type Description
long
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.

Methods

| Edit this page View Source

Add(T)

Adds a single item to the buffer.

Declaration
public void Add(T item)
Parameters
Type Name Description
T item

The item to add.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

Clear()

Clears internal buffers so this builder can be reused.

Declaration
public void Clear()
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

CopyTo(Span<T>)

Copies the contents of this builder to the specified memory block.

Declaration
public int CopyTo(Span<T> output)
Parameters
Type Name Description
Span<T> output

The memory block to be modified.
Returns
Type Description
int

The actual number of copied elements.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

CopyTo(scoped Span<T>, scoped ref SequencePosition)

Copies the elements from this buffer to the destination location, starting at the specified position, and advances the position.

Declaration
public int CopyTo(scoped Span<T> output, scoped ref SequencePosition position)
Parameters
Type Name Description
Span<T> output

The destination block of memory.
SequencePosition position

The position within this buffer.
Returns
Type Description
int

The number of copied elements.
Exceptions
Type Condition
ObjectDisposedException

The buffer has been disposed.
| Edit this page View Source

CopyTo<TArg>(ReadOnlySpanAction<T, TArg>, TArg)

Passes the contents of this builder to the callback.

Declaration
public void CopyTo<TArg>(ReadOnlySpanAction<T, TArg> writer, TArg arg)
Parameters
Type Name Description
ReadOnlySpanAction<T, TArg> writer

The callback used to accept memory segments representing the contents of this builder.
TArg arg

The argument to be passed to the callback.
Type Parameters
Name Description
TArg

The type of the argument to tbe passed to the callback.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

CopyTo<TConsumer>(TConsumer)

Passes the contents of this builder to the consumer.

Declaration
public void CopyTo<TConsumer>(TConsumer consumer) where TConsumer : notnull, IReadOnlySpanConsumer<T>
Parameters
Type Name Description
TConsumer consumer

The consumer of this buffer.
Type Parameters
Name Description
TConsumer

The type of the consumer.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

CopyTo<TConsumer>(TConsumer, SequencePosition)

Passes the elements from this buffer to the specified consumer, starting at the specified position.

Declaration
public void CopyTo<TConsumer>(TConsumer consumer, SequencePosition start) where TConsumer : notnull, IReadOnlySpanConsumer<T>
Parameters
Type Name Description
TConsumer consumer

The consumer to be called multiple times to process the chunk of data.
SequencePosition start

The start position within this buffer.
Type Parameters
Name Description
TConsumer

The type of the consumer.
Exceptions
Type Condition
ObjectDisposedException

The buffer has been disposed.
| Edit this page View Source

CopyTo<TConsumer>(TConsumer, scoped ref SequencePosition, long)

Passes the elements from this buffer to the specified consumer, starting at the specified position, and advances the position.

Declaration
public long CopyTo<TConsumer>(TConsumer consumer, scoped ref SequencePosition position, long count) where TConsumer : notnull, IReadOnlySpanConsumer<T>
Parameters
Type Name Description
TConsumer consumer

The consumer to be called multiple times to process the chunk of data.
SequencePosition position

The position within this buffer.
long count

The number of elements to read.
Returns
Type Description
long

The actual number of copied elements.
Type Parameters
Name Description
TConsumer

The type of the consumer.
Exceptions
Type Condition
ArgumentOutOfRangeException

count is less than zero.
ObjectDisposedException

The buffer has been disposed.
| Edit this page View Source

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true if called from Dispose(); false if called from finalizer ~Disposable().
Overrides
| Edit this page View Source

GetEnumerator()

Gets enumerator over memory segments.

Declaration
public SparseBufferWriter<T>.Enumerator GetEnumerator()
Returns
Type Description
SparseBufferWriter<T>.Enumerator

The enumerator over memory segments.
Exceptions
Type Condition
ObjectDisposedException

The buffer has been disposed.
| Edit this page View Source

GetPosition(long, SequencePosition)

Returns a position at an offset from the specified position within this buffer.

Declaration
public SequencePosition GetPosition(long offset, SequencePosition origin = default)
Parameters
Type Name Description
long offset

The offset from the specified origin position.
SequencePosition origin

A position from which to initiate the offset.
Returns
Type Description
SequencePosition

The position at offset from origin.
Exceptions
Type Condition
ArgumentOutOfRangeException

offset is negative or greater than the number of available elements starting from origin.
| Edit this page View Source

Read(ref SequencePosition, long)

Reads the data from this buffer, and advances the position to the specified number of elements.

Declaration
public ReadOnlySequence<T> Read(ref SequencePosition position, long count)
Parameters
Type Name Description
SequencePosition position

The start position within this buffer.
long count

The number of elements to read.
Returns
Type Description
ReadOnlySequence<T>

A collection of memory chunks containing the requested number of elements.
Exceptions
Type Condition
ArgumentOutOfRangeException

count is less than zero.
InvalidOperationException

The end of the buffer has reached but count is larger than the number of available elements.
ObjectDisposedException

The buffer has been disposed.
| Edit this page View Source

ToString()

Returns the textual representation of this buffer.

Declaration
public override string ToString()
Returns
Type Description
string

The textual representation of this buffer.
Overrides
| Edit this page View Source

TryGetWrittenContent(out ReadOnlyMemory<T>)

Attempts to get the underlying buffer if it is presented by a single segment.

Declaration
public bool TryGetWrittenContent(out ReadOnlyMemory<T> segment)
Parameters
Type Name Description
ReadOnlyMemory<T> segment

The single segment representing written content.
Returns
Type Description
bool

true if this buffer is represented by a single segment; otherwise, false.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

Write(in ReadOnlySequence<T>, bool)

Writes a sequence of memory blocks to this builder.

Declaration
public void Write(in ReadOnlySequence<T> sequence, bool copyMemory = true)
Parameters
Type Name Description
ReadOnlySequence<T> sequence

A sequence of memory blocks.
bool copyMemory

true to copy the content of the input buffer; false to import memory blocks.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

Write(ReadOnlyMemory<T>, bool)

Writes the block of memory to this builder.

Declaration
public void Write(ReadOnlyMemory<T> input, bool copyMemory = true)
Parameters
Type Name Description
ReadOnlyMemory<T> input

The memory block to be written to this builder.
bool copyMemory

true to copy the content of the input buffer; false to import the memory block.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.
| Edit this page View Source

Write(ReadOnlySpan<T>)

Writes the block of memory to this builder.

Declaration
public void Write(ReadOnlySpan<T> input)
Parameters
Type Name Description
ReadOnlySpan<T> input

The memory block to be written to this builder.
Exceptions
Type Condition
ObjectDisposedException

The builder has been disposed.

Implements

Extension Methods

See Also