Struct PgVarlena

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

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 std::str::FromStr;

use pgx::prelude::*;

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

impl PgVarlenaInOutFuncs for MyType {
    fn input(input: &core::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 pgx::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::prelude::*;

#[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(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

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

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<T> for PgVarlena<T>

where T: Copy + Sized,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Default for PgVarlena<T>

where T: Default + Copy,

fn default() -> Self

Returns the “default value” for a type.

impl<T> Deref for PgVarlena<T>

where T: Copy + Sized,

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<T> DerefMut for PgVarlena<T>

where T: Copy + Sized,

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<PgVarlena<T>> for Option<Datum>

where T: Copy + Sized,

fn from(val: PgVarlena<T>) -> Self

Converts to this type from the input type.

impl<T> FromDatum for PgVarlena<T>

where T: Copy + Sized,

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

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

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

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

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 try_from_datum( datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

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.

unsafe fn try_from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

A version of try_from_datum that switches to the given context to convert from Datum

impl<T> IntoDatum for PgVarlena<T>

where T: Copy + Sized,

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?

impl<T> SqlTranslatable for PgVarlena<T>

where T: SqlTranslatable + Copy,

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