PgArrayView

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Borrows a PostgreSQL array and its raw elements under a checked native lifetime.

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

Flat arrays retain their original storage. PostgreSQL may flatten compressed, external or expanded storage into a private child context. Direct scalar input views expire and are cleaned up at callback exit; retained set and aggregate inputs use independent snapshots. Dispose explicitly created views while their backend is active. Copy Datum or a cell to another memory context before its source expires when an independent lifetime is needed. Copied type and shape metadata remain readable after disposal; native access does not. Resetting only the source context also expires all views and cells, even when private child contexts survive. Indexed access is O(1) for fixed-size elements stored without a NULL bitmap, and O(n) otherwise; enumeration visits the elements in one linear pass.

Inheritance: object

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

Constructors

PgArrayView(PgDatum)

Borrows a present array without copying its flat elements or rechecking domain constraints.

public PgArrayView(PgDatum value)

Parameters:

value — PgDatum

The array datum whose owner must remain alive for the view’s lifetime.

Properties

Count

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

public int Count { get; }

Value: int

Datum

Gets the checked flat datum, valid until this view or its source owner expires.

public PgDatum Datum { get; }

Value: PgDatum

ElementTypeOid

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

public uint ElementTypeOid { get; }

Value: uint

HasNulls

Gets whether at least one cell is SQL NULL.

public bool HasNulls { get; }

Value: bool

this[int]

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

public PgDatum this[int index] { get; }

Parameters:

index — int

The flat index, independent of PostgreSQL lower bounds.

Value: PgDatum

A typed datum whose NULL flag is independent of its native bits.

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, as pgrx’s RawArray::nulls does.

public ReadOnlySpan<byte> DangerousGetNullBitmap()

Returns: ReadOnlySpan<byte>

One bit per element in row-major order, least significant bit first, where a set bit marks a present value; empty when the array stores no bitmap.

PostgreSQL stores a bitmap only when the array was built with SQL NULL elements. Lifetime checks occur when acquiring the span; stop using it before any backend call, owner expiry, callback exit or thread change. Copy the bytes to managed storage when they must outlive this native borrow.

DangerousGetSpan<T>()

Borrows a contiguous, read-only native span from an array without SQL NULL elements.

public ReadOnlySpan<T> DangerousGetSpan<T>() where T : unmanaged

Type parameters:

T

Exactly sbyte, short, int, long, float or double.

Returns: ReadOnlySpan<T>

The original row-major payload, independent of native dimension lower bounds.

Exceptions:

• NotSupportedException: T has no supported native scalar layout.
• PgException: The element type is incompatible or a cell is SQL NULL.

The element’s PostgreSQL base type must match T, including for empty arrays. Domains retain their original identity and are not reassigned through constraints. Lifetime checks occur when acquiring the span. Do not use it after disposing the view, resetting or deleting its source, leaving its callback, switching threads or making another backend call. Copy the span to managed storage first when longer retention is needed. UUID arrays require DangerousGetUuidBytes because Guid has a different memory layout.

DangerousGetUuidBytes()

Borrows the contiguous network-order bytes of an array without SQL NULL UUID elements.

public ReadOnlySpan<byte> DangerousGetUuidBytes()

Returns: ReadOnlySpan<byte>

Exactly sixteen bytes per UUID in row-major order.

Exceptions:

• PgException: The elements are not UUIDs or a cell is SQL NULL.

Each sixteen-byte segment can be read with new Guid(segment, bigEndian: true). Do not reinterpret this storage as Guid values. Lifetime checks occur when acquiring the span; stop using it before any backend call, owner expiry, callback exit or thread change. Copy the bytes to managed storage when they must outlive this native borrow.

Dispose()

Releases private flattening and cursor storage and invalidates this view and all borrowed cells.

public void Dispose()

GetEnumerator()

Creates an independent native cursor for a linear pass over the borrowed cells.

public IEnumerator<PgDatum> GetEnumerator()

Returns: IEnumerator<PgDatum>

An enumerator that should be disposed after use; escaped cells retain the view’s lifetime.

GetValue(params ReadOnlySpan<int>)

Borrows a cell using one PostgreSQL subscript per dimension.

public PgDatum GetValue(params ReadOnlySpan<int> subscripts)

Parameters:

subscripts — ReadOnlySpan<int>

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

Returns: PgDatum

The cell under this view’s lifetime.