Struct pgx::Datum

#[repr(transparent)]
pub struct Datum(_);

Datum is an abstract value that is effectively a union of all scalar types and all possible pointers in a Postgres context. That is, it is either “pass-by-value” (if the value fits into the platform’s uintptr_t) or “pass-by-reference” (if it does not).

In Rust, it is best to treat this largely as a pointer while passing it around for code that doesn’t care about what the Datum “truly is”. If for some reason it is important to manipulate the address/value without “knowing the type” of the Datum, cast to a pointer and use pointer methods.

Only create Datums from non-pointers when you know you want to pass a value, as it is erroneous for unsafe code to dereference the address of “only a value” as a pointer. It is still a “safe” operation to create such pointers: validity is asserted by dereferencing, or by creating a safe reference such as &T or &mut T. Also be aware that the validity of Datum’s Copy is premised on the same implicit issues with pointers being Copy: while any &T is live, other *mut T must not be used to write to that &T, and &mut T implies no other *mut T even exists outside an &mut T’s borrowing ancestry. It is thus of dubious soundness for Rust code to receive *mut T, create another *mut T, cast the first to &mut T, and then later try to use the second *mut T to write. It is sound for Postgres itself to pass a copied pointer as a Datum to Rust code, then later to mutate that data through its original pointer after Rust creates and releases a &mut T.

For all intents and purposes, Postgres counts as unsafe code that may be relying on you communicating pointers correctly to it. Do not play games with your database.

Implementations

impl Datum

pub fn value(self) -> usize

Assume the datum is a value and extract the bits from the memory address, interpreting them as an integer.

pub fn is_null(self) -> bool

True if the datum is equal to the null pointer.

pub fn cast_mut_ptr<T>(self) -> *mut T

Assume the datum is a pointer and cast it to point to T. It is recommended to explicitly use datum.cast_mut_ptr::<T>().

Trait Implementations

impl Clone for Datum

fn clone(&self) -> Datum

Returns a copy of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Datum

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> From<*const T> for Datum

fn from(val: *const T) -> Datum

Converts to this type from the input type.

impl<T> From<*mut T> for Datum

fn from(val: *mut T) -> Datum

Converts to this type from the input type.

impl From<bool> for Datum

fn from(val: bool) -> Datum

Converts to this type from the input type.

impl From<i16> for Datum

fn from(val: i16) -> Datum

Converts to this type from the input type.

impl From<i32> for Datum

fn from(val: i32) -> Datum

Converts to this type from the input type.

impl From<i64> for Datum

fn from(val: i64) -> Datum

Converts to this type from the input type.

impl From<i8> for Datum

fn from(val: i8) -> Datum

Converts to this type from the input type.

impl From<isize> for Datum

fn from(val: isize) -> Datum

Converts to this type from the input type.

impl From<u16> for Datum

fn from(val: u16) -> Datum

Converts to this type from the input type.

impl From<u32> for Datum

fn from(val: u32) -> Datum

Converts to this type from the input type.

impl From<u64> for Datum

fn from(val: u64) -> Datum

Converts to this type from the input type.

impl From<u8> for Datum

fn from(val: u8) -> Datum

Converts to this type from the input type.

impl From<usize> for Datum

fn from(val: usize) -> Datum

Converts to this type from the input type.

impl FromDatum for Datum

for pg_sys::Datum

unsafe fn from_polymorphic_datum(
    datum: Datum,
    is_null: bool,
    _: Oid
) -> Option<Datum>

Like from_datum for instantiating polymorphic types which require preserving the dynamic type metadata.

const GET_TYPOID: bool = false

Should a type OID be fetched when calling from_datum?

unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>where
    Self: Sized,

Safety

unsafe fn from_datum_in_memory_context(
    memory_context: PgMemoryContexts,
    datum: Datum,
    is_null: bool,
    typoid: Oid
) -> Option<Self>where
    Self: Sized,

Default implementation switched to the specified memory context and then simply calls FromDatum::from_datum(...) from within that context.

unsafe fn try_from_datum(
    datum: Datum,
    is_null: bool,
    type_oid: Oid
) -> Result<Option<Self>, TryFromDatumError>where
    Self: Sized + IntoDatum + 'static,

try_from_datum is a convenience wrapper around FromDatum::from_datum that returns a a Result instead of an Option. It’s intended to be used in situations where the caller needs to know whether the type conversion succeeded or failed.

impl IntoDatum for Datum

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

fn composite_type_oid(&self) -> Option<Oid>

fn array_type_oid() -> Oid

fn is_compatible_with(other: Oid) -> bool

Is a Datum of this type compatible with another Postgres type?

fn is_pass_by_value() -> boolwhere
    Self: 'static,

Is a Datum of this type pass by value or pass by reference?

impl<T> PartialEq<*mut T> for Datum

fn eq(&self, other: &*mut T) -> bool

This method tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Datum> for Datum

fn eq(&self, other: &Datum) -> bool

This method tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SqlTranslatable for Datum

fn argument_sql() -> Result<SqlMapping, ArgumentError>

fn return_sql() -> Result<Returns, ReturnsError>

fn type_name() -> &'static str

fn variadic() -> bool

fn optional() -> bool

fn entity() -> FunctionMetadataTypeEntity

impl TryFrom<Datum> for Date

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(d: Datum) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Datum> for Timestamp

type Error = FromTimeError

The type returned in the event of a conversion error.

fn try_from(datum: Datum) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Datum> for TimestampWithTimeZone

type Error = FromTimeError

The type returned in the event of a conversion error.

fn try_from(datum: Datum) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<NullableDatum> for Datum

type Error = ()

The type returned in the event of a conversion error.

fn try_from(nd: NullableDatum) -> Result<Datum, ()>

Performs the conversion.

impl Copy for Datum

impl StructuralPartialEq for Datum