Struct plrust_trusted_pgrx::heap_tuple::PgHeapTuple
source · pub struct PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: WhoAllocated,{ /* private fields */ }
Expand description
A PgHeapTuple
is a lightweight wrapper around Postgres’ pg_sys::HeapTuple
object and a PgTupleDesc
.
In order to access the attributes within a pg_sys::HeapTuple
, the PgTupleDesc
is required
to describe its structure.
PgHeapTuple
s can be created from existing (Postgres-provided) pg_sys::HeapTuple
pointers, from
pg_sys::TriggerData
pointers, from a composite datum, or created from scratch using raw Datums.
A PgHeapTuple
can either be considered to be allocated by Postgres or by the Rust runtime. If
allocated by Postgres, it is not mutable until PgHeapTuple::into_owned
is called.
PgHeapTuple
s also describe composite types as defined by pgrx::composite_type!()
.
Implementations§
source§impl<'a> PgHeapTuple<'a, AllocatedByPostgres>
impl<'a> PgHeapTuple<'a, AllocatedByPostgres>
sourcepub unsafe fn from_heap_tuple(
tupdesc: PgTupleDesc<'a>,
heap_tuple: *mut HeapTupleData
) -> PgHeapTuple<'a, AllocatedByPostgres>
pub unsafe fn from_heap_tuple( tupdesc: PgTupleDesc<'a>, heap_tuple: *mut HeapTupleData ) -> PgHeapTuple<'a, AllocatedByPostgres>
Creates a new PgHeapTuple from a PgTupleDesc and a pg_sys::HeapTuple pointer. The returned PgHeapTuple will be considered by have been allocated by Postgres and is not mutable until PgHeapTuple::into_owned is called.
§Safety
This function is unsafe as we cannot guarantee that the pg_sys::HeapTuple pointer is valid, nor can we guaratee that the provided PgTupleDesc properly describes the structure of the heap tuple.
sourcepub unsafe fn from_trigger_data(
trigger_data: &'a TriggerData,
which_tuple: TriggerTuple
) -> Option<PgHeapTuple<'a, AllocatedByPostgres>>
pub unsafe fn from_trigger_data( trigger_data: &'a TriggerData, which_tuple: TriggerTuple ) -> Option<PgHeapTuple<'a, AllocatedByPostgres>>
Creates a new PgHeapTuple identified by the which_tuple
trigger tuple. The returned
PgHeapTuple will be considered by have been allocated by Postgres and is not mutable until
PgHeapTuple::into_owned is called.
pgrx also invents the concept of a “current” ([TriggerTuple::Current
]) tuple, which is either
the new row being inserted or the row being updated (not the new version) or deleted.
Asking for a TriggerTuple
that isn’t compatible with how the trigger was fired causes
this function to return None
. Specifically this means None
is always returned for
statement-level triggers.
§Safety
This function is unsafe as we cannot guarantee that any pointers in the trigger_data
argument are valid or that it’s being used in the context of a firing trigger, which necessitates
Postgres internal state be correct for executing a trigger.
sourcepub fn into_owned(self) -> PgHeapTuple<'a, AllocatedByRust>
pub fn into_owned(self) -> PgHeapTuple<'a, AllocatedByRust>
Consumes a [PgHeapTuple]
considered to be allocated by Postgres and transforms it into one
that is considered allocated by Rust. This is accomplished by copying the underlying pg_sys::HeapTupleData.
source§impl<'a> PgHeapTuple<'a, AllocatedByRust>
impl<'a> PgHeapTuple<'a, AllocatedByRust>
sourcepub fn new_composite_type(
type_name: &str
) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
pub fn new_composite_type( type_name: &str ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
Create a new heap tuple in the shape of a defined composite type
use pgrx::prelude::*;
Spi::run("CREATE TYPE dog AS (name text, age int);");
let mut heap_tuple = PgHeapTuple::new_composite_type("dog").unwrap();
assert_eq!(heap_tuple.get_by_name::<String>("name").unwrap(), None);
assert_eq!(heap_tuple.get_by_name::<i32>("age").unwrap(), None);
heap_tuple
.set_by_name("name", "Brandy".to_string())
.unwrap();
heap_tuple.set_by_name("age", 42).unwrap();
assert_eq!(
heap_tuple.get_by_name("name").unwrap(),
Some("Brandy".to_string())
);
assert_eq!(heap_tuple.get_by_name("age").unwrap(), Some(42i32));
pub fn new_composite_type_by_oid( typoid: Oid ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
sourcepub unsafe fn from_datums<I>(
tupdesc: PgTupleDesc<'a>,
datums: I
) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
pub unsafe fn from_datums<I>( tupdesc: PgTupleDesc<'a>, datums: I ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
Create a new PgHeapTuple from a PgTupleDesc from an iterator of Datums.
§Errors
- PgHeapTupleError::IncorrectAttributeCount if the number of items in the iterator does not match the number of attributes in the PgTupleDesc.
§Safety
This function is unsafe as we cannot guarantee the provided pg_sys::Datum
s are valid
as the specified PgTupleDesc
might expect
sourcepub unsafe fn from_composite_datum(
composite: Datum
) -> PgHeapTuple<'a, AllocatedByRust>
pub unsafe fn from_composite_datum( composite: Datum ) -> PgHeapTuple<'a, AllocatedByRust>
Creates a new PgHeapTuple from an opaque Datum that should be a “composite” type.
The Datum should be a pointer to a pg_sys::HeapTupleHeader. Typically, this will be used
in situations when working with SQL ROW(...)
constructors, or a composite SQL type such as
CREATE TYPE my_composite AS (name text, age i32);
§Safety
This function is unsafe as we cannot guarantee that the provided Datum is a valid pg_sys::HeapTupleHeader pointer.
sourcepub fn set_by_name<T>(
&mut self,
attname: &str,
value: T
) -> Result<(), TryFromDatumError>where
T: IntoDatum,
pub fn set_by_name<T>(
&mut self,
attname: &str,
value: T
) -> Result<(), TryFromDatumError>where
T: IntoDatum,
Given the name for an attribute in this PgHeapTuple, change its value.
Attribute names are case sensitive.
§Errors
- return TryFromDatumError::NoSuchAttributeName if the attribute does not exist
- return TryFromDatumError::IncompatibleTypes if the Rust type of the
value
is not compatible with the attribute’s Postgres type
sourcepub fn set_by_index<T>(
&mut self,
attno: NonZero<usize>,
value: T
) -> Result<(), TryFromDatumError>where
T: IntoDatum,
pub fn set_by_index<T>(
&mut self,
attno: NonZero<usize>,
value: T
) -> Result<(), TryFromDatumError>where
T: IntoDatum,
Given the index for an attribute in this PgHeapTuple, change its value.
Attribute numbers start at 1, not 0.
§Errors
- return TryFromDatumError::NoSuchAttributeNumber if the attribute does not exist
- return TryFromDatumError::IncompatibleTypes if the Rust type of the
value
is not compatible with the attribute’s Postgres type
source§impl<'a, AllocatedBy> PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: WhoAllocated,
impl<'a, AllocatedBy> PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: WhoAllocated,
sourcepub fn into_composite_datum(self) -> Option<Datum>
pub fn into_composite_datum(self) -> Option<Datum>
Consume this PgHeapTuple
and return a composite Datum representation, containing the tuple
data and the corresponding tuple descriptor information.
sourcepub fn into_trigger_datum(self) -> Option<Datum>
pub fn into_trigger_datum(self) -> Option<Datum>
Consume this PgHeapTuple
and return a Datum representation appropriate for returning from
a trigger function
sourcepub fn into_pg(self) -> *mut HeapTupleData
pub fn into_pg(self) -> *mut HeapTupleData
Consumes this PgHeapTuple
, returning a pointer to a pg_sys::HeapTupleData
that can
be passed to a Postgres FFI function. It’ll be freed whenever Postgres frees the MemoryContext
in which it was allocated.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of attributes in this PgHeapTuple
.
sourcepub fn attributes(
&'a self
) -> impl Iterator<Item = (NonZero<usize>, &'a FormData_pg_attribute)>
pub fn attributes( &'a self ) -> impl Iterator<Item = (NonZero<usize>, &'a FormData_pg_attribute)>
Returns an iterator over the attributes in this PgHeapTuple
.
The return value is (attribute_number: NonZeroUsize, attribute_info: &pg_sys::FormData_pg_attribute)
.
sourcepub fn get_attribute_by_index(
&'a self,
index: NonZero<usize>
) -> Option<&'a FormData_pg_attribute>
pub fn get_attribute_by_index( &'a self, index: NonZero<usize> ) -> Option<&'a FormData_pg_attribute>
Get the attribute information for the specified attribute number.
Returns None
if the attribute number is out of bounds.
sourcepub fn get_attribute_by_name(
&'a self,
name: &str
) -> Option<(NonZero<usize>, &'a FormData_pg_attribute)>
pub fn get_attribute_by_name( &'a self, name: &str ) -> Option<(NonZero<usize>, &'a FormData_pg_attribute)>
Get the attribute information for the specified attribute, by name.
Returns None
if the attribute name is not found.
sourcepub fn get_by_name<T>(
&self,
attname: &str
) -> Result<Option<T>, TryFromDatumError>
pub fn get_by_name<T>( &self, attname: &str ) -> Result<Option<T>, TryFromDatumError>
Retrieve the value of the specified attribute, by name.
Attribute names are case-insensitive.
§Errors
- return
TryFromDatumError::NoSuchAttributeName
if the attribute does not exist - return
TryFromDatumError::IncompatibleTypes
if the Rust type of thevalue
is not compatible with the attribute’s Postgres type
sourcepub fn get_by_index<T>(
&self,
attno: NonZero<usize>
) -> Result<Option<T>, TryFromDatumError>
pub fn get_by_index<T>( &self, attno: NonZero<usize> ) -> Result<Option<T>, TryFromDatumError>
Retrieve the value of the specified attribute, by index.
Attribute numbers start at 1, not 0.
§Errors
- return
TryFromDatumError::NoSuchAttributeNumber
if the attribute does not exist - return
TryFromDatumError::IncompatibleTypes
if the Rust type of thevalue
is not compatible with the attribute’s Postgres type
Trait Implementations§
source§impl<'a> FromDatum for PgHeapTuple<'a, AllocatedByRust>
impl<'a> FromDatum for PgHeapTuple<'a, AllocatedByRust>
source§unsafe fn from_polymorphic_datum(
composite: Datum,
is_null: bool,
_oid: Oid
) -> Option<PgHeapTuple<'a, AllocatedByRust>>
unsafe fn from_polymorphic_datum( composite: Datum, is_null: bool, _oid: Oid ) -> Option<PgHeapTuple<'a, AllocatedByRust>>
from_datum
for instantiating polymorphic types
which require preserving the dynamic type metadata. Read moresource§unsafe fn from_datum_in_memory_context(
memory_context: PgMemoryContexts,
composite: Datum,
is_null: bool,
_oid: Oid
) -> Option<PgHeapTuple<'a, AllocatedByRust>>
unsafe fn from_datum_in_memory_context( memory_context: PgMemoryContexts, composite: Datum, is_null: bool, _oid: Oid ) -> Option<PgHeapTuple<'a, AllocatedByRust>>
FromDatum::from_datum(...)
from within that context. Read moresource§const GET_TYPOID: bool = false
const GET_TYPOID: bool = false
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,
source§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>
try_from_datum
that switches to the given context to convert from Datumsource§impl<'a, AllocatedBy> IntoDatum for PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: WhoAllocated,
impl<'a, AllocatedBy> IntoDatum for PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: WhoAllocated,
source§impl SqlTranslatable for PgHeapTuple<'static, AllocatedByPostgres>
impl SqlTranslatable for PgHeapTuple<'static, AllocatedByPostgres>
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 SqlTranslatable for PgHeapTuple<'static, AllocatedByRust>
impl SqlTranslatable for PgHeapTuple<'static, AllocatedByRust>
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
Auto Trait Implementations§
impl<'a, AllocatedBy> RefUnwindSafe for PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: RefUnwindSafe,
impl<'a, AllocatedBy> !Send for PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy> !Sync for PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy> Unpin for PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: Unpin,
impl<'a, AllocatedBy> UnwindSafe for PgHeapTuple<'a, AllocatedBy>where
AllocatedBy: UnwindSafe,
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
source§impl<T> FmtForward for T
impl<T> FmtForward for T
source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self
to use its Display
implementation when
Debug
-formatted.source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
source§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,
self
and passes that borrow into the pipe function. Read moresource§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,
self
and passes that borrow into the pipe function. Read moresource§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
source§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
source§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
self
, then passes self.as_ref()
into the pipe function.source§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
self
, then passes self.as_mut()
into the pipe
function.source§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
self
, then passes self.deref()
into the pipe function.source§impl<T> Tap for T
impl<T> Tap for T
source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B>
of a value. Read moresource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B>
of a value. Read moresource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R>
view of a value. Read moresource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R>
view of a value. Read moresource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow()
only in debug builds, and is erased in release
builds.source§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
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref()
only in debug builds, and is erased in release
builds.source§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
.tap_ref_mut()
only in debug builds, and is erased in release
builds.source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref()
only in debug builds, and is erased in release
builds.