Struct pgx_pg_sys::submodules::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

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<Datum> for usize

fn from(val: Datum) -> usize

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<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<T> PartialEq<Datum> for *mut T

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 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<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