Struct BufferWriterSlim<T>

Represents stack-allocated buffer writer.

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: DotNext.Buffers

Assembly: DotNext.dll

Syntax

public ref struct BufferWriterSlim<T>

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

| Edit this page View Source

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.

| Edit this page View Source

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

| Edit this page View Source

Capacity

Gets the total amount of space within the underlying memory.

Declaration

public readonly int Capacity { get; }

Property Value

Type	Description
int

| Edit this page View Source

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

| Edit this page View Source

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.

| Edit this page View Source

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

| Edit this page View Source

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

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

Dispose()

Releases internal buffer used by this builder.

Declaration

public void Dispose()

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.

| Edit this page View Source

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.