Struct BufferWriterSlim<T>

Represents stack-allocated buffer writer.

Implements

IGrowableBuffer<T>

IBufferWriter<T>

IConsumer<ReadOnlySpan<T>>

ISupplier<ReadOnlyMemory<T>, CancellationToken, ValueTask>

IFunctional

IDisposable

IResettable

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: DotNext.Buffers

Assembly: DotNext.dll

Syntax

public ref struct BufferWriterSlim<T> : IGrowableBuffer<T>, IBufferWriter<T>, IConsumer<ReadOnlySpan<T>>, ISupplier<ReadOnlyMemory<T>, CancellationToken, ValueTask>, IFunctional, IDisposable, IResettable

Type Parameters

Name	Description
T	The type of the elements in the memory.

Remarks

This type is similar to PoolingArrayBufferWriter<T> and PoolingBufferWriter<T> classes but it tries to avoid on-heap allocation. Moreover, it can use pre-allocated stack memory as a initial buffer used for writing. If builder requires more space then pooled memory used.

Constructors

BufferWriterSlim()

Initializes a new buffer writer.

Declaration

public BufferWriterSlim()

BufferWriterSlim(int, MemoryAllocator<T>?)

Initializes growable buffer.

Declaration

public BufferWriterSlim(int initialCapacity, MemoryAllocator<T>? allocator = null)

Parameters

Type	Name	Description
int	initialCapacity	The initial capacity of the internal buffer.
MemoryAllocator<T>	allocator	The memory allocator used to rent the memory blocks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	initialCapacity is less than zero.

BufferWriterSlim(Span<T>, MemoryAllocator<T>?)

Initializes growable buffer.

Declaration

public BufferWriterSlim(Span<T> buffer, MemoryAllocator<T>? allocator = null)

Parameters

Type	Name	Description
Span<T>	buffer	Pre-allocated buffer used by this builder.
MemoryAllocator<T>	allocator	The memory allocator used to rent the memory blocks.

Remarks

The builder created with this constructor is growable. However, additional memory will not be requested using allocator while buffer space is sufficient. If allocator is null then Shared is used for memory pooling.

Properties

Capacity

Gets the total amount of space within the underlying memory.

Declaration

public readonly int Capacity { get; }

Property Value

Type	Description
int

FreeCapacity

Gets the amount of space available that can still be written into without forcing the underlying buffer to grow.

Declaration

public readonly int FreeCapacity { get; }

Property Value

Type	Description
int

this[int]

Gets the element at the specified zero-based index within this builder.

Declaration

public readonly ref T this[int index] { get; }

Parameters

Type	Name	Description
int	index	Zero-based index of the element.

Property Value

Type	Description
T	The element at the specified index.

Exceptions

Type	Condition
ArgumentOutOfRangeException	index is less than zero or greater than or equal to WrittenCount.

WrittenCount

Gets the amount of data written to the underlying memory so far.

Declaration

public int WrittenCount { readonly get; set; }

Property Value

Type	Description
int

WrittenSpan

Gets span over constructed memory block.

Declaration

public readonly ReadOnlySpan<T> WrittenSpan { get; }

Property Value

Type	Description
ReadOnlySpan<T>	The constructed memory block.

Methods

Add()

Adds single element and returns a reference to it.

Declaration

public ref T Add()

Returns

Type	Description
T	The reference to the added element.

Exceptions

Type	Condition
InsufficientMemoryException	Pre-allocated initial buffer size is not enough to place extra element.

Add(T)

Adds single element to this builder.

Declaration

public void Add(T item)

Parameters

Type	Name	Description
T	item	The item to be added.

Exceptions

Type	Condition
InsufficientMemoryException	Pre-allocated initial buffer size is not enough to place item to it and this builder is not growable.

AddAll(IEnumerable<T>)

Writes a collection of elements.

Declaration

public void AddAll(IEnumerable<T> collection)

Parameters

Type	Name	Description
IEnumerable<T>	collection	A collection of elements.

Exceptions

Type	Condition
ArgumentNullException	collection is null.

Advance(int)

Notifies this writer that count of data items were written.

Declaration

public void Advance(int count)

Parameters

Type	Name	Description
int	count	The number of data items written to the underlying buffer.

Exceptions

Type	Condition
ArgumentOutOfRangeException	count is less than zero.
InvalidOperationException	Attempts to advance past the end of the underlying buffer.
ObjectDisposedException	This writer has been disposed.

Clear(bool)

Clears the data written to the underlying buffer.

Declaration

public void Clear(bool reuseBuffer = false)

Parameters

Type	Name	Description
bool	reuseBuffer	true to reuse the internal buffer; false to destroy the internal buffer.

DetachOrCopyBuffer()

Detaches or copies the underlying buffer with written content from this writer.

Declaration

public MemoryOwner<T> DetachOrCopyBuffer()

Returns

Type	Description
MemoryOwner<T>	Detached or copied buffer.

Dispose()

Releases internal buffer used by this builder.

Declaration

public void Dispose()

GetSpan(int)

Returns the memory to write to that is at least the requested size.

Declaration

public Span<T> GetSpan(int sizeHint = 0)

Parameters

Type	Name	Description
int	sizeHint	The minimum length of the returned memory.

Returns

Type	Description
Span<T>	The memory block of at least the size sizeHint.

Exceptions

Type	Condition
OutOfMemoryException	The requested buffer size is not available.

Rewind(int)

Moves the writer back the specified number of items.

Declaration

public void Rewind(int count)

Parameters

Type	Name	Description
int	count	The number of items.

Exceptions

Type	Condition
ArgumentOutOfRangeException	count is less than zero or greater than WrittenCount.

ToString()

Converts this buffer to the string.

Declaration

public override readonly string ToString()

Returns

Type	Description
string	The textual representation of this object.

Overrides

ValueType.ToString()

Remarks

If T is char then this method returns constructed string instance.

TryDetachBuffer(out MemoryOwner<T>)

Detaches the underlying buffer with written content from this writer.

Declaration

public bool TryDetachBuffer(out MemoryOwner<T> owner)

Parameters

Type	Name	Description
MemoryOwner<T>	owner	The buffer owner.

Returns

Type	Description
bool	true if the written content is in rented buffer because initial buffer overflows; false if the written content is in preallocated buffer.

TryPeek(out T)

Gets the last added item.

Declaration

public readonly bool TryPeek(out T item)

Parameters

Type	Name	Description
T	item	The last added item.

Returns

Type	Description
bool	true if this buffer is not empty; otherwise, false.

TryPop(scoped Span<T>)

Attempts to remove a sequence of last added items.

Declaration

public bool TryPop(scoped Span<T> output)

Parameters

Type	Name	Description
Span<T>	output	The buffer to receive last added items.

Returns

Type	Description
bool	true if items are removed successfully; otherwise, false.

TryPop(out T)

Attempts to remove the last added item.

Declaration

public bool TryPop(out T item)

Parameters

Type	Name	Description
T	item	The removed item.

Returns

Type	Description
bool	true if the item is removed successfully; otherwise, false.

Write(scoped ReadOnlySpan<T>)

Writes elements to this buffer.

Declaration

public void Write(scoped ReadOnlySpan<T> input)

Parameters

Type	Name	Description
ReadOnlySpan<T>	input	The span of elements to be written.

Exceptions

Type	Condition
InsufficientMemoryException	Pre-allocated initial buffer size is not enough to place input elements to it and this builder is not growable.
OverflowException	The size of the internal buffer becomes greater than MaxValue.

Operators

operator +=(IEnumerable<T>)

Writes a collection of elements.

Declaration

public void operator +=(IEnumerable<T> collection)

Parameters

Type	Name	Description
IEnumerable<T>	collection	A collection of elements.

Exceptions

Type	Condition
ArgumentNullException	collection is null.

operator +=(scoped ReadOnlySpan<T>)

Writes elements to this buffer.

Declaration

public void operator +=(scoped ReadOnlySpan<T> input)

Parameters

Type	Name	Description
ReadOnlySpan<T>	input	The span of elements to be written.

Exceptions

Type	Condition
InsufficientMemoryException	Pre-allocated initial buffer size is not enough to place input elements to it and this builder is not growable.
OverflowException	The size of the internal buffer becomes greater than MaxValue.

operator +=(T)

Adds single element to this builder.

Declaration

public void operator +=(T item)

Parameters

Type	Name	Description
T	item	The item to be added.

Exceptions

Type	Condition
InsufficientMemoryException	Pre-allocated initial buffer size is not enough to place item to it and this builder is not growable.

Implements

IGrowableBuffer<T>

IBufferWriter<T>

IConsumer<T>

ISupplier<T1, T2, TResult>

IFunctional

IDisposable

IResettable

Extension Methods

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

Enumerator.Skip<TEnumerator, T>(ref TEnumerator, int)

See Also

PoolingArrayBufferWriter<T>

PoolingBufferWriter<T>

SparseBufferWriter<T>