Class ValueBuffer<T>

Namespace

BelNytheraSeiche.TrieDictionary

Assembly

BelNytheraSeiche.TrieDictionary.dll

Represents a buffer for value types, implemented using a list of array chunks.

public sealed class ValueBuffer<T> : ICollection<T>, IEnumerable<T>, IEnumerable where T : struct

Type Parameters

T

The type of element, which must be a struct.

Inheritance

object

ValueBuffer<T>

Implements

ICollection<T>

IEnumerable<T>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class is designed to manage large collections of value types without allocating on the Large Object Heap (LOH). It achieves this by storing elements in a series of smaller array "chunks". The size of these chunks, specified by ElementsPerChunk, must be a power of 2.

Constructors

ValueBuffer(int, bool)

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

public ValueBuffer(int elementsPerChunk, bool extendAutomatically = false)

Parameters

elementsPerChunk int

The size of each internal array chunk. This value must be a power of 2.

extendAutomatically bool

A value indicating whether to automatically extend the buffer's capacity when an out-of-bounds index is accessed.

Exceptions

ArgumentOutOfRangeException

elementsPerChunk is not positive.

ArgumentException

elementsPerChunk is not a power of 2.

Properties

Capacity

Gets the total number of elements that can be stored across all currently allocated chunks.

public int Capacity { get; }

Property Value

int

Count

Gets the number of elements contained in the ValueBuffer<T>. This property is an implementation for the ICollection<T> interface and is an alias for the Used property.

public int Count { get; }

Property Value

int

ElementsPerChunk

Gets the size of each internal array chunk.

public int ElementsPerChunk { get; }

Property Value

int

ExtendAutomatically

Gets a value indicating whether the buffer will automatically allocate new chunks when an index outside the current capacity is accessed.

public bool ExtendAutomatically { get; }

Property Value

bool

IsReadOnly

Gets a value indicating whether the ValueBuffer<T> is read-only.

public bool IsReadOnly { get; }

Property Value

bool

this[int]

Gets or sets the element at the specified index.

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

Parameters

index int

The zero-based index of the element to get or set.

Property Value

T

A reference to the element at the specified index.

Remarks

Accessing an index greater than or equal to the current Used count will update the count to index + 1. If ExtendAutomatically is true, accessing an index beyond the current Capacity will allocate new chunks.

Exceptions

ArgumentOutOfRangeException

Thrown if index is negative, or if index is greater than or equal to Capacity and ExtendAutomatically is false.

NumberOfChunks

Gets the number of internal array chunks that are currently allocated.

public int NumberOfChunks { get; }

Property Value

int

Used

Gets the number of elements that are considered to be in use within the buffer. This value is updated when an element is written to an index greater than the current used count.

public int Used { get; }

Property Value

int

Methods

Add(T)

Adds an element to the end of the ValueBuffer<T>.

public void Add(T value)

Parameters

value T

The element to add.

AppendChunkDirectly(T[])

Appends a pre-allocated array chunk directly to the internal list of buffers, increasing the capacity.

public void AppendChunkDirectly(T[] chunk)

Parameters

chunk T[]

The array to append. Its length must be exactly equal to ElementsPerChunk.

Remarks

This is an advanced optimization method that avoids an array allocation and copy by using a caller-provided array.

Exceptions

ArgumentNullException

chunk is null.

ArgumentException

The length of chunk is not equal to ElementsPerChunk.

Clear()

Removes all elements from the ValueBuffer<T> and releases all internal array chunks.

public void Clear()

Contains(T)

Determines whether the ValueBuffer<T> contains a specific value.

public bool Contains(T item)

Parameters

item T

The object to locate in the ValueBuffer<T>.

Returns

bool

true if item is found in the ValueBuffer<T>; otherwise, false.

CopyTo(T[], int)

Copies the elements of the ValueBuffer<T> to an Array, starting at a particular Array index.

public void CopyTo(T[] array, int arrayIndex)

Parameters

array T[]

The one-dimensional Array that is the destination of the elements copied from ValueBuffer<T>.

arrayIndex int

The zero-based index in array at which copying begins.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of elements in the source buffer is greater than the available space from arrayIndex to the end of the destination array.

EnumerateChunks()

Returns an enumerable collection of the internal array chunks.

public IEnumerable<T[]> EnumerateChunks()

Returns

IEnumerable<T[]>

An IEnumerable<T> (T is an array) that allows iteration over the raw internal buffers.

Remarks

This method is intended for advanced scenarios where direct read-only access to the underlying chunks is required.

ExtendCapacity(int)

Ensures that the capacity of this buffer is at least the specified value.

public int ExtendCapacity(int minCapacity)

Parameters

minCapacity int

The minimum required capacity.

Returns

int

The new capacity of the buffer, which will be a multiple of ElementsPerChunk.

Exceptions

ArgumentOutOfRangeException

minCapacity is negative.

Fill(T, int, int)

Fills a range of elements in the buffer with a specified value.

public void Fill(T value, int index, int count)

Parameters

value T

The value to assign to each element in the range.

index int

The zero-based starting index of the range to fill.

count int

The number of elements in the range to fill.

Exceptions

ArgumentOutOfRangeException

index or count is negative.

ArgumentException

The sum of index and count is greater than the buffer's capacity and ExtendAutomatically is false.

GetEnumerator()

Returns an enumerator that iterates through the used elements in the buffer.

public IEnumerator<T> GetEnumerator()

Returns

IEnumerator<T>

An enumerator for the ValueBuffer<T>.

Remove(T)

Finds the first occurrence of an item and replaces it with the default value of type T.

public bool Remove(T item)

Parameters

item T

The item to locate and replace.

Returns

bool

true if the item was found and replaced; otherwise, false.

Remarks

This method does not actually remove the element in a way that would shift subsequent elements. It only overwrites the found element with default(T). The Count and Used properties are not changed by this operation.

SetUsedDirectly(int, bool)

Directly sets the number of used elements and optionally shrinks the buffer's capacity.

public void SetUsedDirectly(int used, bool shrinkAutomatically = false)

Parameters

used int

The new count of used elements. This value must be between 0 and Capacity.

shrinkAutomatically bool

If true, deallocates unused array chunks from the end of the buffer to fit the new used count.

Remarks

This is an advanced method and should be used with caution. Setting an incorrect value can lead to an inconsistent state or data corruption.

Exceptions

ArgumentOutOfRangeException

used is negative or greater than Capacity.

ToArray()

Copies the used elements from the ValueBuffer<T> to a new, single contiguous array.

public T[] ToArray()

Returns

T[]

A new array containing the elements from the buffer.