PgDatum

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Retains a PostgreSQL datum, its exact type OID, and its SQL NULL flag under a checked memory-context lifetime.

public sealed class PgDatum

Raw SPI results own their native storage. Copy a value into another context to keep it beyond result disposal. Reading an ordinary managed type returns an independent copy; polymorphic wrappers share this datum’s lifetime. Native reads, output formatting, and copies access existing storage without reapplying domain constraints. Explicit parameter and result assignments still validate those constraints; selected converters and output functions retain their own behavior. Native access requires the owning backend thread.

Inheritance: object

Methods

CopyTo(PgMemoryContext)

Copies the native value into a specified context, independently of this datum’s current owner.

public PgDatum CopyTo(PgMemoryContext context)

Parameters:

context — PgMemoryContext

The destination context whose reset or deletion ends the new value’s lifetime.

Returns: PgDatum

The copied datum with its exact type and NULL state.

Create(SpiParameter, PgMemoryContext)

Converts a typed value to a datum of its declared PostgreSQL type, allocated in the destination context. A domain’s constraints apply as they do to an assignment, including to SQL NULL.

public static PgDatum Create(SpiParameter value, PgMemoryContext context)

Parameters:

value — SpiParameter

The typed value, which can be a typed SQL NULL.

context — PgMemoryContext

The destination context whose reset or deletion ends the datum’s lifetime.

Returns: PgDatum

The converted datum.

Create<T>(T, PgMemoryContext)

Converts a managed value to a datum of its PostgreSQL type, allocated in the destination context, as pgrx’s IntoDatum does. The value’s type selects the PostgreSQL type, as for Create<T>(T), including a PgDatumTypeAttribute mapping. A null value gives SQL NULL of that type.

public static PgDatum Create<T>(T value, PgMemoryContext context)

Type parameters:

T

The managed type, which selects the PostgreSQL type when the value is null.

Parameters:

value — T

The value.

context — PgMemoryContext

The destination context whose reset or deletion ends the datum’s lifetime.

Returns: PgDatum

The converted datum.

DangerousCreate(nuint, uint, PgMemoryContext, bool)

Borrows a caller-supplied native Datum word using an explicit context lifetime anchor.

[NativeUnsafeAccess]
public static PgDatum DangerousCreate(nuint bits, uint typeOid, PgMemoryContext context, bool isNull = false)

Parameters:

bits — nuint

A correctly represented by-value Datum or a valid by-reference address.

typeOid — uint

The exact PostgreSQL type OID.

context — PgMemoryContext

The lifetime anchor; it is not inferred to own the supplied address.

isNull — bool

Whether the datum is SQL NULL.

Returns: PgDatum

A checked lifetime handle for the supplied datum.

The caller must prove the representation matches the type and that referenced storage remains valid until the anchor resets or is deleted. The handle cannot detect an earlier free of that storage.

DangerousGetBits()

Returns the native Datum word after checking its memory owner and backend thread.

public nuint DangerousGetBits()

Returns: nuint

The raw bits, which may represent a value or a native address according to the type.

This does not extend native storage lifetime. Check IsNull separately before interpreting the bits.

Read<T>()

Reads a supported managed type with the ordinary SPI checks, or invokes registered scalar or array element readers.

public T Read<T>()

Type parameters:

T

The desired managed type.

Returns: T

An independent managed value, or a polymorphic wrapper sharing this datum’s lifetime.

Registered datum readers require the exact current mapped type and a live owner, including for SQL NULL. Their user-supplied conversion must return independent managed data for a present value. Mapped array elements use a temporary native owner that ends after conversion; this source datum remains owned by its original context. PgArrayView<T> instead retains this source lifetime and converts only accessed cells. It validates element identity even for whole-array SQL NULL, which returns a null view. Dispose the view while the source backend remains active.

Read<T>(Func<PgDatum, T>)

Converts this datum using an explicit converter without runtime code generation or reflection.

public T Read<T>(Func<PgDatum, T> converter)

Type parameters:

T

The converter’s managed result type.

Parameters:

converter — Func<PgDatum, T>

The converter, which must copy any data that will outlive this datum.

Returns: T

The converter’s result.

ToPostgresString()

Uses the type’s PostgreSQL output function and copies its text into a managed string.

public string? ToPostgresString()

Returns: string

The server-formatted value, or null for SQL NULL.

Properties

IsNull

Gets whether this value is SQL NULL. A zero Datum word alone does not indicate SQL NULL.

public bool IsNull { get; }

Value: bool

TypeOid

Gets the declared PostgreSQL type OID, including domain identity and typed NULLs.

public uint TypeOid { get; }

Value: uint