PgList<T>

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Provides a checked mutable collection over PostgreSQL’s typed native List container.

public sealed class PgList<T> : IList<T>, ICollection<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable, IDisposable where T : unmanaged

Type parameters:

T

Exactly int, uint (OID), PgTransactionId, or nint (opaque pointer).

A default instance is backend-independent NIL until its first allocating mutation. Bound lists require the owning backend callback and expire when their context resets. Disposal releases owned containers, never pointer elements. There is no native finalizer. Safe reads copy cells; unsafe pointers can become invalid after mutation or context cleanup.

Inheritance: object

Implements: IList<T>, ICollection<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable, IDisposable

Constructors

PgList()

Creates an unbound NIL list without accessing PostgreSQL or allocating native storage.

public PgList()

Methods

Add(T)

Appends one cell, binding an unbound NIL list to the current context as needed.

public void Add(T item)

Parameters:

item — T

The cell value.

AddRange(ReadOnlySpan<T>)

Appends an independent copy of all source values in one guarded native mutation.

public void AddRange(ReadOnlySpan<T> values)

Parameters:

values — ReadOnlySpan<T>

The values to append.

Clear()

Frees the container and cell storage and restores NIL, retaining the context binding.

public void Clear()

Clone(PgMemoryContext?)

Creates an independent native container with copied cell values in the selected context.

public PgList<T> Clone(PgMemoryContext? context = null)

Parameters:

context — PgMemoryContext

The new owner, or null for the current context.

Returns: PgList<T>

An owned copy; pointer pointees are shared and never cloned or freed.

Contains(T)

Tests for an exactly equal cell value.

public bool Contains(T item)

Parameters:

item — T

The cell to find.

Returns: bool

Whether a matching cell exists.

CopyTo(Span<T>, int)

Copies an exact native cell range into caller-owned managed storage.

public void CopyTo(Span<T> destination, int sourceIndex = 0)

Parameters:

destination — Span<T>

The destination span; its length selects the number of cells.

sourceIndex — int

The first source cell.

CopyTo(T[], int)

Copies the entire list into a managed array starting at the requested destination index.

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

Parameters:

array — T[]

The destination array.

arrayIndex — int

The first destination index.

DangerousDetach()

Consumes this wrapper and returns the native container without releasing its storage.

public void* DangerousDetach()

Returns: void*

The current List pointer, including null for NIL.

Native context ownership is unchanged. A borrowed transfer does not acquire release rights.

Dispose()

Releases an owned container or closes a borrowed wrapper; repeated disposal is harmless.

public void Dispose()

Drain(int, int)

Copies and removes a range immediately, repairing the native tail before returning.

public T[] Drain(int index, int count)

Parameters:

index — int

The first cell to remove.

count — int

The number of cells to remove, including zero.

Returns: T[]

An independent array of removed values in their original order.

The mutation completes before enumeration of the result; abandoning that enumeration cannot leave a partially drained container. Emptying the list releases its storage.

GetConsumingEnumerator()

Consumes this wrapper and gives an enumerator its ownership and lifetime obligations.

public IEnumerator<T> GetConsumingEnumerator()

Returns: IEnumerator<T>

An enumerator that disposes its list at the end or on early disposal.

The caller must dispose the returned enumerator, including when it is never advanced. Owned containers are freed; borrowed containers remain with their native owner. This wrapper becomes unusable immediately after successful transfer.

GetEnumerator()

Enumerates copied cells while checking wrapper mutation, disposal and context lifetime.

public IEnumerator<T> GetEnumerator()

Returns: IEnumerator<T>

A borrowed enumerator; disposing it leaves this list intact.

IndexOf(T)

Finds the first cell with the same exact value using ordinary managed equality.

public int IndexOf(T item)

Parameters:

item — T

The value to find.

Returns: int

The first matching index, or minus one.

Insert(int, T)

Inserts one cell at an existing index or at the end.

public void Insert(int index, T item)

Parameters:

index — int

The zero-based insertion index, from zero through Count.

item — T

The cell to insert.

Remove(T)

Removes the first matching cell without freeing pointer elements.

public bool Remove(T item)

Parameters:

item — T

The value to remove.

Returns: bool

Whether a cell was removed.

RemoveAt(int)

Removes one cell and shifts the remaining tail, restoring NIL when emptied.

public void RemoveAt(int index)

Parameters:

index — int

The zero-based index to remove.

ToArray()

Copies every cell into an independent managed array.

public T[] ToArray()

Returns: T[]

The exact ordered cell values.

TryAdd(T)

Appends one cell only if a nonempty list already has spare capacity, without allocating native storage.

public bool TryAdd(T item)

Parameters:

item — T

The cell to append.

Returns: bool

False for NIL or full capacity; true after appending.

TryGet(int, out T)

Attempts to read a cell without treating an out-of-range index as an exception.

public bool TryGet(int index, out T value)

Parameters:

index — int

The zero-based index.

value — T

The exact cell on success, otherwise default.

Returns: bool

Whether the checked list contains this index.

TryGetFirst(out T)

Attempts to read the first cell, preserving a zero pointer or value as a successful result.

public bool TryGetFirst(out T value)

Parameters:

value — T

The first cell, otherwise default.

Returns: bool

Whether the list is nonempty.

TryGetLast(out T)

Attempts to read the final cell.

public bool TryGetLast(out T value)

Parameters:

value — T

The final cell, otherwise default.

Returns: bool

Whether the list is nonempty.

TryPop(out T)

Removes and returns the final cell, freeing the container when it becomes NIL.

public bool TryPop(out T value)

Parameters:

value — T

The removed cell, otherwise default.

Returns: bool

Whether one cell was removed.

TryReserve(int)

Ensures room for additional cells on a nonempty list, allocating in its original owner if necessary.

public bool TryReserve(int additionalCount)

Parameters:

additionalCount — int

The number of cells beyond the current length.

Returns: bool

False for NIL, otherwise true. Allocation errors still throw.

Properties

Capacity

Gets the current native cell capacity, or zero for NIL.

public int Capacity { get; }

Value: int

Count

Gets the current number of cells after checking the list’s lifetime.

public int Count { get; }

Value: int

IsEmpty

Gets whether the checked list is NIL.

public bool IsEmpty { get; }

Value: bool

IsReadOnly

Gets false because this collection supports mutation.

public bool IsReadOnly { get; }

Value: bool

this[int]

Gets or replaces one cell without changing its type, length or ownership.

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

Parameters:

index — int

The zero-based cell index.

Value: T

The exact cell value.

LifetimeContext

Gets the checked native owner, or null for an unbound NIL list.

public PgMemoryContext? LifetimeContext { get; }

Value: PgMemoryContext