Struct Array

pub struct Array<'mcx, T> { /* private fields */ }

An array of some type (eg. TEXT[], int[])

While conceptually similar to a Vec<T>, arrays are lazy.

Using a Vec<T> here means each element of the passed array will be eagerly fetched and converted into a Rust type:

use pgrx::prelude::*;

#[pg_extern]
fn with_vec(elems: Vec<String>) {
    // Elements all already converted.
    for elem in elems {
        todo!()
    }
}

Using an array, elements are only fetched and converted into a Rust type on demand:

use pgrx::prelude::*;

#[pg_extern]
fn with_vec(elems: Array<String>) {
    // Elements converted one by one
    for maybe_elem in elems {
        let elem = maybe_elem.unwrap();
        todo!()
    }
}

Implementations

impl<'mcx, T: UnboxDatum> Array<'mcx, T>

pub fn iter(&self) -> ArrayIterator<'_, T>

Return an iterator of Option<T>.

pub fn iter_deny_null(&self) -> ArrayTypedIterator<'_, T>

Return an iterator over the Array’s elements.

Panics

This function will panic when called if the array contains any SQL NULL values.

pub fn get<'arr>(&'arr self, index: usize) -> Option<Option<T::As<'arr>>>

impl<T> Array<'_, T>

pub fn into_array_type(self) -> *const ArrayType

Rips out the underlying pg_sys::ArrayType pointer. Note that Array may have caused Postgres to allocate to unbox the datum, and this can hypothetically cause a memory leak if so.

pub fn contains_nulls(&self) -> bool

Returns true if this Array contains one or more SQL “NULL” values

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

impl Array<'_, f64>

pub fn as_slice(&self) -> Result<&[f64], ArraySliceError>

Returns a slice of f64s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

impl Array<'_, f32>

pub fn as_slice(&self) -> Result<&[f32], ArraySliceError>

Returns a slice of f32s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

impl Array<'_, i64>

pub fn as_slice(&self) -> Result<&[i64], ArraySliceError>

Returns a slice of i64s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

impl Array<'_, i32>

pub fn as_slice(&self) -> Result<&[i32], ArraySliceError>

Returns a slice of i32s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

impl Array<'_, i16>

pub fn as_slice(&self) -> Result<&[i16], ArraySliceError>

Returns a slice of i16s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

impl Array<'_, i8>

pub fn as_slice(&self) -> Result<&[i8], ArraySliceError>

Returns a slice of i8s which comprise this Array.

Errors

Returns a ArraySliceError::ContainsNulls error if this Array contains one or more SQL “NULL” values. In this case, you’d likely want to fallback to using Array::iter().

Trait Implementations

impl<'fcx, T> ArgAbi<'fcx> for Array<'fcx, T>

where T: ArgAbi<'fcx> + UnboxDatum,

unsafe fn unbox_arg_unchecked(arg: Arg<'_, 'fcx>) -> Self

Unbox an argument with a matching type.

unsafe fn unbox_nullable_arg(arg: Arg<'_, 'fcx>) -> Nullable<Self>

Unbox a nullable arg

fn is_virtual_arg() -> bool

“Is this a virtual arg?”

impl<T: UnboxDatum> Debug for Array<'_, T>

where for<'arr> <T as UnboxDatum>::As<'arr>: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: UnboxDatum> FromDatum for Array<'a, T>

unsafe fn from_polymorphic_datum( datum: Datum, is_null: bool, _typoid: Oid, ) -> Option<Array<'a, T>>

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>

where Self: Sized,

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>

Safety

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

where Self: 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: IntoDatum,

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

impl<T: IntoDatum> IntoDatum for Array<'_, T>

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

fn composite_type_oid(&self) -> Option<Oid>

fn is_compatible_with(other: Oid) -> bool

Is a Datum of this type compatible with another Postgres type?

impl<'mcx, T> IntoIterator for Array<'mcx, T>

where for<'arr> T: UnboxDatum<As<'arr> = T> + 'static,

type Item = Option<<T as UnboxDatum>::As<'mcx>>

The type of the elements being iterated over.

type IntoIter = ArrayIntoIterator<'mcx, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'mcx, T> IntoNullableIterator<<T as UnboxDatum>::As<'mcx>> for &'mcx Array<'mcx, T>

where T: UnboxDatum,

type Iter = NullableArrayIterator<'mcx, T>

fn into_nullable_iter(self) -> Self::Iter

impl<'mcx, T: UnboxDatum> NullableContainer<'mcx, usize, <T as UnboxDatum>::As<'mcx>> for Array<'mcx, T>

type Layout = MaybeStrictNulls<BitSliceNulls<'mcx>>

fn get_layout(&'mcx self) -> &'mcx Self::Layout

unsafe fn get_raw(&'mcx self, idx: usize) -> <T as UnboxDatum>::As<'mcx>

For internal use - implement this over underlying data types Used to implement NullableIter.

fn len(&'mcx self) -> usize

Total array length - doesn’t represent the length of the backing array (as in, the thing accessed by get_raw) but instead represents the length of the array including skipped nulls.

impl<'mcx, T: UnboxDatum> Serialize for Array<'mcx, T>

where for<'arr> <T as UnboxDatum>::As<'arr>: Serialize,

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> SqlTranslatable for Array<'_, T>

where T: SqlTranslatable,

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<T: FromDatum + UnboxDatum> UnboxDatum for Array<'_, T>

type As<'src> = Array<'src, T> where Self: 'src

Self with the lifetime 'src

unsafe fn unbox<'src>(d: Datum<'src>) -> Array<'src, T>

where Self: 'src,

Convert from Datum<'src> to T::As<'src>