Enum List 

pub enum List<'cx, T> {
    Nil,
    Cons(ListHead<'cx, T>),
}

The List type from Postgres, lifted into Rust Note: you may want the ListHead type

Variants

Nil

Cons(ListHead<'cx, T>)

Implementations

impl<'cx, T: Enlist> List<'cx, T>

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

Borrow an item from the List at the index

pub fn get_mut(&mut self, index: usize) -> Option<&mut T>

Mutably borrow an item from the List at the index

pub fn unstable_push_in_context( &mut self, value: T, mcx: &'cx MemCx<'_>, ) -> &mut ListHead<'cx, T>

Pushes an item into the List

Allocates the entire list in referenced context if it had zero elements, otherwise uses the List’s own context.

“Unstable” because this may receive breaking changes.

pub fn drain<R>(&mut self, range: R) -> Drain<'_, 'cx, T>

where R: RangeBounds<usize>,

pub fn iter(&self) -> impl Iterator<Item = &T>

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T>

impl<T> List<'_, T>

pub fn as_cells(&self) -> &[ListCell<T>]

Borrow the List’s slice of cells

Note that like with Vec, this slice may move after appending to the List! Due to lifetimes this isn’t a problem until unsafe Rust becomes involved, but with Postgres extensions it often does.

Note that if you use this on a 0-item list, you get an empty slice, which is not going to be equal to the null pointer.

pub fn as_cells_mut(&mut self) -> &mut [ListCell<T>]

Mutably borrow the List’s slice of cells

Includes the same caveats as with List::as_cells, but with “less” problems: &mut means you should not have other pointers to the list anyways.

Note that if you use this on a 0-item list, you get an empty slice, which is not going to be equal to the null pointer.

impl<T: Enlist> List<'_, T>

pub unsafe fn downcast_ptr_in_memcx<'cx>( ptr: *mut List, memcx: &'cx MemCx<'_>, ) -> Option<List<'cx, T>>

Attempt to obtain a List<T> from a *mut pg_sys::List

This may be somewhat confusing: A valid List of any type is the null pointer, as in the Lisp (car, cdr) representation. This remains true even after significant reworks of the List type in Postgres 13, which cause it to internally use a “flat array” representation.

Thus, this returns Some even if the List is NULL, because it is Some(List::Nil), and returns None only if the List is non-NULL but downcasting failed!

Safety

This assumes the pointer is either NULL or the NodeTag is valid to read, so it is not okay to call this on pointers to deallocated or uninit data.

If it returns as Some and the List is more than zero length, it also asserts that the entire List’s elements: *mut ListCell is validly initialized as T in each ListCell and that the List is allocated from a MemCx that lasts at least as long as the current context.

Note: This memory context must last long enough for your purposes. YOU are responsible for bounding its lifetime correctly.

impl<'cx, T> List<'cx, T>

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn capacity(&self) -> usize

pub fn into_ptr(self) -> *mut List

pub fn as_ptr(&self) -> *const List

pub fn as_mut_ptr(&mut self) -> *mut List

impl<'cx, T: Enlist> List<'cx, T>

pub fn try_push(&mut self, value: T) -> Result<&mut ListHead<'cx, T>, &mut Self>

Attempt to push or Err if it would allocate

This exists primarily to allow working with a list with maybe-zero capacity.

pub fn try_reserve( &mut self, items: usize, ) -> Result<&mut ListHead<'cx, T>, &mut Self>

Try to reserve space for N more items

Trait Implementations

impl<'cx, T: Debug> Debug for List<'cx, T>

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

Formats the value using the given formatter.

impl<'cx, T> Default for List<'cx, T>

Note the absence of impl Default for ListHead: it must initialize at least 1 element to be created at all

fn default() -> List<'cx, T>

Returns the “default value” for a type.

impl<'a, T: Enlist> IntoIterator for List<'a, T>

type IntoIter = ListIter<'a, T>

Which kind of iterator are we turning this into?

type Item = T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.