PgArrayView<T>

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Reads a borrowed PostgreSQL array through a checked scalar element conversion.

public sealed class PgArrayView<T> : IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable, IDisposable

Type parameters:

T

A supported scalar representation, nullable when value-type cells can be SQL NULL.

The array retains its native storage, dimensions, lower bounds and exact type identity. Elements are converted on access using PgDatum.Read<T>; ordinary values are copied, while borrowed text and bytea elements retain the source lifetime. Dispose such elements when finished. Disposing an enumerator releases only its cursor, not its returned elements. Nonnullable value types reject arrays containing SQL NULL during construction. Indexed lookup is O(1) for fixed-size native elements stored without a NULL bitmap, and O(n) otherwise; enumeration visits the array in one linear pass and converts each cell once. Native access expires with this view, its source owner or its source callback. Copied metadata remains readable after expiry. Construct this view from a checked PgDatum, or request it through PgDatum.Read, SPI scalar helpers or PgFunctions. Raw reads borrow their source lifetime; scalar SPI and function results use callback-owned snapshots. Whole-array SQL NULL returns a null view after checking the declared element identity. Present parameters transport the original datum without requiring an element writer. Generated scalar, SETOF, TABLE and aggregate signatures use the concrete element’s SQL array type. Scalar inputs expire with their callback; retained inputs receive independent snapshots. Returns preserve the original datum and must match the declared native array identity.

Inheritance: object

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

Constructors

PgArrayView(PgDatum)

Borrows a present array after validating its element identity, including empty and all-NULL arrays.

public PgArrayView(PgDatum value)

Parameters:

value — PgDatum

The checked source datum, whose owner must remain alive.

Exceptions:

• ArgumentException: The array datum is SQL NULL.
• NotSupportedException: T has no readable scalar conversion.
• InvalidCastException: A nonnullable value type cannot represent a NULL cell.
• PgException: The PostgreSQL element type does not match T.

Properties

Count

Gets the total number of cells, including SQL NULL cells.

public int Count { get; }

Value: int

Datum

Gets the checked flat datum under this view’s native lifetime.

public PgDatum Datum { get; }

Value: PgDatum

ElementTypeOid

Gets the exact element OID, including domain, enum and composite identities.

public uint ElementTypeOid { get; }

Value: uint

HasNulls

Gets whether the array contains a SQL NULL cell.

public bool HasNulls { get; }

Value: bool

this[int]

Converts a cell at a zero-based row-major index using PostgreSQL’s native array lookup.

public T this[int index] { get; }

Parameters:

index — int

The flat index, independent of PostgreSQL lower bounds.

Value: T

The copied value or checked borrowed element.

Lengths

Gets the copied dimension lengths.

public ReadOnlySpan<int> Lengths { get; }

Value: ReadOnlySpan<int>

LowerBounds

Gets the copied PostgreSQL lower bounds.

public ReadOnlySpan<int> LowerBounds { get; }

Value: ReadOnlySpan<int>

Rank

Gets the number of dimensions; empty arrays have rank zero.

public int Rank { get; }

Value: int

TypeOid

Gets the original array type OID, including a domain over an array.

public uint TypeOid { get; }

Value: uint

Methods

DangerousGetNullBitmap()

Borrows the array’s native SQL NULL bitmap, with the lifetime rules of DangerousGetNullBitmap().

public ReadOnlySpan<byte> DangerousGetNullBitmap()

Returns: ReadOnlySpan<byte>

One bit per element, least significant bit first, set for a present value; empty without a bitmap.

Dispose()

Releases private native storage and invalidates this view and its borrowed elements.

public void Dispose()

GetEnumerator()

Creates an independent native cursor that converts each cell once in row-major order.

public IEnumerator<T> GetEnumerator()

Returns: IEnumerator<T>

An enumerator which must be disposed after use.

GetValue(params ReadOnlySpan<int>)

Converts a cell using one PostgreSQL subscript per dimension.

public T GetValue(params ReadOnlySpan<int> subscripts)

Parameters:

subscripts — ReadOnlySpan<int>

The native subscripts, including negative or non-one lower bounds.

Returns: T

The copied value or checked borrowed element.