Trait BorrowDatum

pub unsafe trait BorrowDatum {
    const PASS: PassBy;

    // Required method
    unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>;

    // Provided methods
    unsafe fn point_from_align4(ptr: NonNull<u32>) -> NonNull<Self> { ... }
    unsafe fn borrow_unchecked<'dat>(ptr: NonNull<u8>) -> &'dat Self { ... }
}

Types which can be “borrowed from” [&Datum<'_>] via simple cast, deref, or slicing

Safety

Despite its pleasant-sounding name, this implements a fairly low-level detail. It exists to allow other code to use that nice-sounding BorrowDatum bound. Outside of the pgrx library, it is probably incorrect to call and rely on this: instead use convenience functions like Datum::borrow_as.

Its behavior is trusted for ABI details, and it should not be implemented if any doubt exists of whether the type would be suitable for passing via Postgres.

Required Associated Constants

const PASS: PassBy

The “native” passing convention for this type.

• PassBy::Value implies mem::size_of<T>() <= mem::size_of::<Datum>().
• PassBy::Ref means the pointee will occupy at least 1 byte for variable-sized types.

Note that this means a zero-sized type is inappropriate for BorrowDatum.

Required Methods

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

Cast a pointer to this blob of bytes to a pointer to this type.

This is not a simple ptr.cast() because it may be unsizing, which may require reading varlena headers. For all fixed-size types, ptr.cast() should be correct.

Safety

• This must be correctly invoked for the pointee type, as it may deref and read one or more bytes in its implementation in order to read the inline metadata and unsize the type.
• This must be invoked with a pointee initialized for the dynamically specified length.

For Implementers

Reading the first byte pointed to is permitted if T::PASS = PassBy::Ref, assuming you are implementing a varlena type. As the other dynamic length type, CStr also does this. This function

• must NOT mutate the pointee
• must point to the entire datum’s length (size_of_val must not lose bytes)

Do not attempt to handle pass-by-value versus pass-by-ref in this fn’s body! A caller may be in a context where all types are handled by-reference, for instance.

Provided Methods

unsafe fn point_from_align4(ptr: NonNull<u32>) -> NonNull<Self>

Cast a pointer to aligned varlena headers to this type

This version allows you to assume the pointer is aligned to, and readable for, 4 bytes. This optimization is not required. When in doubt, avoid implementing it, and rely on your point_from implementation alone.

Safety

• This must be correctly invoked for the pointee type, as it may deref.
• This must be 4-byte aligned!

unsafe fn borrow_unchecked<'dat>(ptr: NonNull<u8>) -> &'dat Self

Optimization for borrowing the referent

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl BorrowDatum for bool

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for f32

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for f64

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for i8

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for i16

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for i32

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for i64

const PASS: PassBy

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

impl BorrowDatum for CStr

It is rare to pass CStr via Datums, but not unheard of

const PASS: PassBy = PassBy::Ref

unsafe fn point_from(ptr: NonNull<u8>) -> NonNull<Self>

unsafe fn borrow_unchecked<'dat>(ptr: NonNull<u8>) -> &'dat Self

Implementors

impl BorrowDatum for Oid

const PASS: PassBy

impl BorrowDatum for Point

const PASS: PassBy

impl BorrowDatum for Date

const PASS: PassBy

impl BorrowDatum for Time

const PASS: PassBy

impl BorrowDatum for Timestamp

const PASS: PassBy

impl BorrowDatum for TimestampWithTimeZone

const PASS: PassBy