Struct pgx::datum::PgVarlena

pub struct PgVarlena<T> where
    T: Copy + Sized,  { /* fields omitted */ }

Wraps a Postgres varlena *, presenting it as if it's a Rust type of a fixed size.

The wrapped varlena * is behind a Rust alloc::borrow:Cow which ensures that in the common-use case of creating a PgVarlena from a Postgres-provided Datum, it's not possible to scribble on that Postgres-allocated memory.

Generally, PgVarlena is meant to be used in conjunction with pgx's PostgresType derive macro to provide transparent mapping of fixed-size Rust types as Postgres datums.

Example

use pgx::*;
use std::ffi::CStr;
use std::str::FromStr;

pg_module_magic!();

#[derive(Copy, Clone, PostgresType)]
#[pgvarlena_inoutfuncs]
struct MyType {
   a: f32,
   b: f32,
   c: i64
}

impl PgVarlenaInOutFuncs for MyType {
    fn input(input: &std::ffi::CStr) -> PgVarlena<Self> {
        let mut iter = input.to_str().unwrap().split(',');
        let (a, b, c) = (iter.next(), iter.next(), iter.next());

        let mut result = PgVarlena::<MyType>::new();
        result.a = f32::from_str(a.unwrap()).expect("a is not a valid f32");
        result.b = f32::from_str(b.unwrap()).expect("b is not a valid f32");
        result.c = i64::from_str(c.unwrap()).expect("c is not a valid i64");

        result
    }

    fn output(&self, buffer: &mut StringInfo) {
        buffer.push_str(&format!("{},{},{}", self.a, self.b, self.c));
    }
}

#[pg_extern]
fn do_a_thing(mut input: PgVarlena<MyType>) -> PgVarlena<MyType> {
    input.c += 99;  // performs a copy-on-write
    input
}

Implementations

impl<T> PgVarlena<T> where
    T: Copy + Sized, 

pub fn new() -> Self

Create a new PgVarlena representing a Rust type. The backing varlena is allocated by Postgres and initially zero'd (using pg_sys::palloc0). Unless .into_pg() is called, the Postgres-allocated memory will follow Rust's drop semantics.

Example

use pgx::PgVarlena;
#[derive(Copy, Clone)]
struct MyType {
   a: f32,
   b: f32,
   c: i64
}

let mut v = PgVarlena::<MyType>::new();
v.a = 42.0;
v.b = 0.424242;
v.c = 42;

pub unsafe fn from_datum(datum: Datum) -> Self

Construct a PgVarlena from a known-to-be-non-null pg_sys::Datum. As FromDatum for PgVarlena<T> where T: Copy + Sized is already implemented, it is unlikely that this function will need to be called directly.

The provided datum is automatically detoasted and the returned PgVarlena will either be considered borrowed or owned based on if detoasting actually needed to allocate memory. If it didn't, then we're borrowed, otherwise we're owned.

Safety

This function is considered unsafe as it cannot guarantee the provided pg_sys::Datum is a valid *mut pg_sys::varlena.

pub fn into_pg(mut self: Self) -> *mut varlena

Use when you need to pass the backing *mut pg_sys::varlena to a Postgres function.

This method is also used by the IntoDatum for PgVarlena<T> where T: Copy + Sized implementation.

Trait Implementations

impl<T> AsMut<T> for PgVarlena<T> where
    T: Copy + Sized, 

Does a copy-on-write if the backing varlena pointer is borrowed

pub fn as_mut(&mut self) -> &mut T

Performs the conversion.

impl<T> AsRef<T> for PgVarlena<T> where
    T: Copy + Sized, 

pub fn as_ref(&self) -> &T

Performs the conversion.

impl<T> Deref for PgVarlena<T> where
    T: Copy + Sized, 

type Target = T

The resulting type after dereferencing.

pub fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for PgVarlena<T> where
    T: Copy + Sized, 

pub fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T> Drop for PgVarlena<T> where
    T: Copy + Sized, 

pg_sys::pfree a PgVarlena if we allocated it, instead of Postgres

pub fn drop(&mut self)

Executes the destructor for this type.

impl<T> FromDatum for PgVarlena<T> where
    T: Copy + Sized, 

pub unsafe fn from_datum(
    datum: Datum,
    is_null: bool,
    _typoid: u32
) -> Option<Self>

Safety

pub unsafe fn from_datum_in_memory_context(
    mut memory_context: PgMemoryContexts,
    datum: usize,
    is_null: bool,
    _typoid: u32
) -> Option<Self>

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

impl<T> Into<Option<usize>> for PgVarlena<T> where
    T: Copy + Sized, 

pub fn into(self) -> Option<Datum>

Performs the conversion.

impl<T> IntoDatum for PgVarlena<T> where
    T: Copy + Sized, 

pub fn into_datum(self) -> Option<Datum>

pub fn type_oid() -> Oid

pub fn array_type_oid() -> Oid