pub struct Datum(/* private fields */);Expand description
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§
source§impl Datum
impl Datum
sourcepub fn value(self) -> usize
pub fn value(self) -> usize
Assume the datum is a value and extract the bits from the memory address, interpreting them as an integer.
sourcepub fn cast_mut_ptr<T>(self) -> *mut T
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§
source§impl FromDatum for Datum
impl FromDatum for Datum
for pg_sys::Datum
source§unsafe fn from_polymorphic_datum(
datum: Datum,
is_null: bool,
_: Oid
) -> Option<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. Read moresource§const GET_TYPOID: bool = false
const GET_TYPOID: bool = false
Should a type OID be fetched when calling
from_datum?source§unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>where
Self: Sized,
unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>where
Self: Sized,
Safety Read more
source§unsafe fn from_datum_in_memory_context(
memory_context: PgMemoryContexts,
datum: Datum,
is_null: bool,
typoid: Oid
) -> Option<Self>where
Self: Sized,
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. Read moresource§unsafe fn try_from_datum(
datum: Datum,
is_null: bool,
type_oid: Oid
) -> Result<Option<Self>, TryFromDatumError>
unsafe fn try_from_datum( datum: Datum, is_null: bool, type_oid: Oid ) -> Result<Option<Self>, TryFromDatumError>
try_from_datum is a convenience wrapper around FromDatum::from_datum that returns a
a Result around an Option, as a Datum can be null. It’s intended to be used in
situations where the caller needs to know whether the type conversion succeeded or failed. Read moresource§unsafe fn try_from_datum_in_memory_context(
memory_context: PgMemoryContexts,
datum: Datum,
is_null: bool,
type_oid: Oid
) -> Result<Option<Self>, TryFromDatumError>
unsafe fn try_from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, type_oid: Oid ) -> Result<Option<Self>, TryFromDatumError>
A version of
try_from_datum that switches to the given context to convert from Datumsource§impl<T> PartialEq<*mut T> for Datum
impl<T> PartialEq<*mut T> for Datum
source§impl PartialEq for Datum
impl PartialEq for Datum
source§impl SqlTranslatable for Datum
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
source§impl TryFrom<Datum> for BuiltinOid
impl TryFrom<Datum> for BuiltinOid
§type Error = NotBuiltinOid
type Error = NotBuiltinOid
The type returned in the event of a conversion error.
source§fn try_from(datum: Datum) -> Result<BuiltinOid, NotBuiltinOid>
fn try_from(datum: Datum) -> Result<BuiltinOid, NotBuiltinOid>
Performs the conversion.
source§impl TryFrom<Datum> for TimestampWithTimeZone
impl TryFrom<Datum> for TimestampWithTimeZone
source§impl TryFrom<NullableDatum> for Datum
impl TryFrom<NullableDatum> for Datum
impl Copy for Datum
impl StructuralPartialEq for Datum
Auto Trait Implementations§
impl RefUnwindSafe for Datum
impl !Send for Datum
impl !Sync for Datum
impl Unpin for Datum
impl UnwindSafe for Datum
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> Conv for T
impl<T> Conv for T
§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
Causes
self to use its Binary implementation when Debug-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
Causes
self to use its Display implementation when
Debug-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
Causes
self to use its LowerExp implementation when
Debug-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
Causes
self to use its LowerHex implementation when
Debug-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
Causes
self to use its Octal implementation when Debug-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
Causes
self to use its Pointer implementation when
Debug-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
Causes
self to use its UpperExp implementation when
Debug-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
Causes
self to use its UpperHex implementation when
Debug-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
Formats each item in a sequence. Read more
§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
Pipes by value. This is generally the method you want to use. Read more
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
Borrows
self and passes that borrow into the pipe function. Read more§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
Mutably borrows
self and passes that borrow into the pipe function. Read more§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
Borrows
self, then passes self.as_ref() into the pipe function.§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
Mutably borrows
self, then passes self.as_mut() into the pipe
function.§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
Borrows
self, then passes self.deref() into the pipe function.§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Immutable access to the
Borrow<B> of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
Mutable access to the
BorrowMut<B> of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
Immutable access to the
AsRef<R> view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
Mutable access to the
AsMut<R> view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Immutable access to the
Deref::Target of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Mutable access to the
Deref::Target of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
Calls
.tap() only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
Calls
.tap_mut() only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
Calls
.tap_borrow() only in debug builds, and is erased in release
builds.§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
Calls
.tap_borrow_mut() only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
Calls
.tap_ref() only in debug builds, and is erased in release
builds.§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
Calls
.tap_ref_mut() only in debug builds, and is erased in release
builds.§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
Calls
.tap_deref() only in debug builds, and is erased in release
builds.