PgItemPointer
Namespace: Ankus
Assembly: Ankus.Runtime.dll
Represents PostgreSQL’s physical tuple location, tid, as exact block and offset numbers.
public readonly struct PgItemPointer : IComparable<PgItemPointer>, IEquatable<PgItemPointer>An invalid offset is distinct from SQL NULL. This managed value is not a native ItemPointerData layout. Tuple locations can change when PostgreSQL moves or rewrites a row; they are not permanent row identifiers.
Implements: IComparable<PgItemPointer>, IEquatable<PgItemPointer>
Constructors
Section titled “Constructors”PgItemPointer(uint, ushort)
Section titled “PgItemPointer(uint, ushort)”Represents PostgreSQL’s physical tuple location, tid, as exact block and offset numbers.
public PgItemPointer(uint BlockNumber, ushort OffsetNumber)Parameters:
BlockNumber — uint
The raw unsigned block number.
OffsetNumber — ushort
The raw unsigned offset number, including zero and native special values.
An invalid offset is distinct from SQL NULL. This managed value is not a native ItemPointerData layout. Tuple locations can change when PostgreSQL moves or rewrites a row; they are not permanent row identifiers.
Properties
Section titled “Properties”BlockNumber
Section titled “BlockNumber”The raw unsigned block number.
public uint BlockNumber { get; init; }Value: uint
IndicatesMovedPartitions
Section titled “IndicatesMovedPartitions”Gets whether this value is the native moved-partition marker.
public bool IndicatesMovedPartitions { get; }Value: bool
Invalid
Section titled “Invalid”Gets PostgreSQL’s invalid item pointer, with the maximum block number and offset zero.
public static PgItemPointer Invalid { get; }Value: PgItemPointer
IsValid
Section titled “IsValid”Gets whether the offset is nonzero, matching PostgreSQL’s item-pointer validity check.
public bool IsValid { get; }Value: bool
MovedPartitions
Section titled “MovedPartitions”Gets PostgreSQL’s marker for a tuple moved to another partition.
public static PgItemPointer MovedPartitions { get; }Value: PgItemPointer
OffsetNumber
Section titled “OffsetNumber”The raw unsigned offset number, including zero and native special values.
public ushort OffsetNumber { get; init; }Value: ushort
Methods
Section titled “Methods”CompareTo(PgItemPointer)
Section titled “CompareTo(PgItemPointer)”Compares unsigned blocks followed by unsigned offsets, including invalid values, as PostgreSQL’s tid operators do.
public int CompareTo(PgItemPointer other)Parameters:
other — PgItemPointer
The other location.
Returns: int
A negative value, zero, or a positive value according to the ordering.
Deconstruct(out uint, out ushort)
Section titled “Deconstruct(out uint, out ushort)”public void Deconstruct(out uint BlockNumber, out ushort OffsetNumber)Parameters:
BlockNumber — uint
OffsetNumber — ushort
Decrement()
Section titled “Decrement()”Retreats the raw 48-bit location, borrowing from the block and saturating at zero.
public PgItemPointer Decrement()Returns: PgItemPointer
The preceding location, which may have offset zero.
Equals(PgItemPointer)
Section titled “Equals(PgItemPointer)”public bool Equals(PgItemPointer other)Parameters:
other — PgItemPointer
Returns: bool
Equals(object)
Section titled “Equals(object)”public override bool Equals(object obj)Parameters:
obj — object
Returns: bool
FromIndexKey(long)
Section titled “FromIndexKey(long)”Decodes a nonnegative 48-bit PostgreSQL index key without losing bits.
public static PgItemPointer FromIndexKey(long value)Parameters:
value — long
The dense index key; a zero offset is preserved.
Returns: PgItemPointer
The exact item pointer.
Exceptions:
- ArgumentOutOfRangeException: The key is negative or exceeds 48 bits.
FromIndexKeyTruncating(long)
Section titled “FromIndexKeyTruncating(long)”Decodes the low 48 bits of a PostgreSQL index key, explicitly matching itemptr_decode’s truncation.
public static PgItemPointer FromIndexKeyTruncating(long value)Parameters:
value — long
The raw dense representation.
Returns: PgItemPointer
The selected block and offset bits.
FromUInt64(ulong)
Section titled “FromUInt64(ulong)”Decodes the pgrx representation without discarding any nonzero bits.
public static PgItemPointer FromUInt64(ulong value)Parameters:
value — ulong
The sparse representation with bits 16–31 zero.
Returns: PgItemPointer
The exact item pointer.
Exceptions:
- ArgumentOutOfRangeException: An unused bit is nonzero.
FromUInt64Truncating(ulong)
Section titled “FromUInt64Truncating(ulong)”Decodes the pgrx representation while explicitly discarding bits 16–31, matching its raw helper.
public static PgItemPointer FromUInt64Truncating(ulong value)Parameters:
value — ulong
The raw sparse representation.
Returns: PgItemPointer
The selected block and offset bits.
GetBlockNumber()
Section titled “GetBlockNumber()”Reads the block number after requiring a nonzero offset.
public uint GetBlockNumber()Returns: uint
The block number.
Exceptions:
- InvalidOperationException: The item pointer has offset zero.
GetHashCode()
Section titled “GetHashCode()”public override int GetHashCode()Returns: int
GetOffsetNumber()
Section titled “GetOffsetNumber()”Reads the offset number after requiring a nonzero offset.
public ushort GetOffsetNumber()Returns: ushort
The offset number.
Exceptions:
- InvalidOperationException: The item pointer has offset zero.
Increment()
Section titled “Increment()”Advances the raw 48-bit location, carrying into the block and saturating at the maximum value.
public PgItemPointer Increment()Returns: PgItemPointer
The next location, which may have offset zero.
ToIndexKey()
Section titled “ToIndexKey()”Packs a valid item pointer into PostgreSQL’s dense index key, with the block shifted by 16 bits.
public long ToIndexKey()Returns: long
The nonnegative 48-bit key used by PostgreSQL’s itemptr_encode.
Exceptions:
- InvalidOperationException: The item pointer has offset zero.
ToString()
Section titled “ToString()”Formats both raw fields as PostgreSQL’s invariant (block,offset) text.
public override string ToString()Returns: string
The tuple-location text.
ToUInt64()
Section titled “ToUInt64()”Packs the block into bits 32–63 and the offset into bits 0–15, matching pgrx’s item_pointer_to_u64.
public ulong ToUInt64()Returns: ulong
The sparse pgrx encoding, including for invalid item pointers.
Operators
Section titled “Operators”operator ==(PgItemPointer, PgItemPointer)
Section titled “operator ==(PgItemPointer, PgItemPointer)”public static bool operator ==(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool
operator >(PgItemPointer, PgItemPointer)
Section titled “operator >(PgItemPointer, PgItemPointer)”Compares two locations in reverse PostgreSQL tuple order.
public static bool operator >(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool
operator >=(PgItemPointer, PgItemPointer)
Section titled “operator >=(PgItemPointer, PgItemPointer)”Compares two locations in reverse PostgreSQL tuple order, including equality.
public static bool operator >=(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool
operator !=(PgItemPointer, PgItemPointer)
Section titled “operator !=(PgItemPointer, PgItemPointer)”public static bool operator !=(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool
operator <(PgItemPointer, PgItemPointer)
Section titled “operator <(PgItemPointer, PgItemPointer)”Compares two locations in PostgreSQL tuple order.
public static bool operator <(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool
operator <=(PgItemPointer, PgItemPointer)
Section titled “operator <=(PgItemPointer, PgItemPointer)”Compares two locations in PostgreSQL tuple order, including equality.
public static bool operator <=(PgItemPointer left, PgItemPointer right)Parameters:
left — PgItemPointer
right — PgItemPointer
Returns: bool