Struct listpack::Listpack

pub struct Listpack { /* fields omitted */ }

Methods

impl Listpack

A listpack is encoded into a single linear chunk of memory. It has a fixed length header of six bytes (instead of ten bytes of ziplist, since we no longer need a pointer to the start of the last element). The header is followed by the listpack elements. In theory the data structure does not need any terminator, however for certain concerns, a special entry marking the end of the listpack is provided, in the form of a single byte with value FF (255). The main advantages of the terminator are the ability to scan the listpack without holding (and comparing at each iteration) the address of the end of the listpack, and to recognize easily if a listpack is well formed or truncated. These advantages are, in the idea of the writer, worth the additional byte needed in the representation.

<tot-bytes> <num-elements> <element-1> ... <element-N> <listpack-end-byte>

The six byte header, composed of the tot-bytes and num-elements fields is encoded in the following way:

• tot-bytes: 32 bit unsigned integer holding the total amount of bytes representing the listpack. Including the header itself and the terminator. This basically is the total size of the allocation needed to hold the listpack and allows to jump at the end in order to scan the listpack in reverse order, from the last to the first element, when needed.
• num-elements: 16 bit unsigned integer holding the total number of elements the listpack holds. However if this field is set to 65535, which is the greatest unsigned integer representable in 16 bit, it means that the number of listpack elements is not known, so a LIST-LENGTH operation will require to fully scan the listpack. This happens when, at some point, the listpack has a number of elements equal or greater than 65535. The num-elements field will be set again to a lower number the first time a LIST-LENGTH operation detects the elements count returned in the representable range.

All integers in the listpack are stored in little endian format, if not otherwise specified (certain special encodings are in big endian because it is more natural to represent them in this way for the way the specification maps to C code).

pub fn new() -> Listpack

pub fn len(&self) -> u32

Return the number of elements inside the listpack. This function attempts to use the cached value when within range, otherwise a full scan is needed. As a side effect of calling this function, the listpack header could be modified, because if the count is found to be already within the 'numele' header field range, the new value is set.

pub fn size(&self) -> u32

Return the total number of bytes the listpack is composed of.

pub fn get(&self, ele: Element) -> Value

Decodes and returns the entry value of the element.

If the function is called against a badly encoded listpack, so that there is no valid way to parse it, the function returns like if there was an integer encoded with value 12345678900000000 + , this may be an hint to understand that something is wrong. To crash in this case is not sensible because of the different requirements of the application using this lib.

Similarly, there is no error returned since the listpack normally can be assumed to be valid, so that would be a very high API cost. However a function in order to check the integrity of the listpack at load time is provided, check is_valid().

pub fn get_int(&self, ele: Element) -> i64

pub fn get_int_or(&self, ele: Element, default: i64) -> i64

pub fn get_i8(&self, ele: Element) -> i8

pub fn append_i8(&mut self, v: i8) -> bool

pub fn replace_i8(&mut self, ele: Element, v: i8) -> Option<Element>

pub fn append_i8_fixed(&mut self, v: i8) -> bool

pub fn get_u8(&self, ele: Element) -> u8

pub fn append_u8(&mut self, v: u8) -> bool

pub fn append_u8_fixed(&mut self, v: u8) -> bool

pub fn get_i16(&self, ele: Element) -> i16

pub fn append_i16(&mut self, v: i16) -> bool

pub fn append_i16_fixed(&mut self, v: i16) -> bool

pub fn get_u16(&self, ele: Element) -> u16

pub fn append_u16(&mut self, v: u16) -> bool

pub fn append_u16_fixed(&mut self, v: u16) -> bool

pub fn get_i32(&self, ele: Element) -> i32

pub fn append_i32(&mut self, v: i32) -> bool

pub fn append_i32_fixed(&mut self, v: i32) -> bool

pub fn get_u32(&self, ele: Element) -> u32

pub fn append_u32(&mut self, v: u32) -> bool

pub fn append_u32_fixed(&mut self, v: u32) -> bool

pub fn get_i64(&self, ele: Element) -> i64

pub fn append_i64(&mut self, v: i64) -> bool

pub fn append_i64_fixed(&mut self, v: i64) -> bool

pub fn get_u64(&self, ele: Element) -> u64

pub fn append_u64(&mut self, v: u64) -> bool

pub fn append_u64_fixed(&mut self, v: u64) -> bool

pub fn get_isize(&self, ele: Element) -> isize

pub fn append_isize(&mut self, v: isize) -> bool

pub fn append_isize_fixed(&mut self, v: isize) -> bool

pub fn get_usize(&self, ele: Element) -> usize

pub fn append_usize(&mut self, v: usize) -> bool

pub fn append_usize_fixed(&mut self, v: usize) -> bool

pub fn get_f32(&self, ele: Element) -> f32

pub fn append_f32(&mut self, v: f32) -> bool

pub fn append_f32_fixed(&mut self, v: f32) -> bool

pub fn get_f64(&self, ele: Element) -> f64

pub fn append_f64(&mut self, v: f64) -> bool

pub fn append_f64_fixed(&mut self, v: f64) -> bool

pub fn get_i128(&self, ele: Element) -> i128

pub fn get_str(&self, ele: Element) -> &str

pub fn get_str_or<'a>(&self, ele: Element, default: &'a str) -> &'a str

pub fn insert(     &mut self,     value: Value,     p: Element,     action: c_int ) -> Option<Element>

Insert, delete or replace the specified element 'ele' of length 'len' at the specified position 'p', with 'p' being a listpack element pointer obtained with first(), last(), index(), next(), prev() or seek().

The element is inserted before, after, or replaces the element pointed by 'p' depending on the 'where' argument, that can be BEFORE, AFTER or REPLACE.

If 'ele' is set to NULL, the function removes the element pointed by 'p' instead of inserting one.

Returns None on out of memory or when the listpack total length would exceed the max allowed size of 2^32-1, otherwise the new pointer to the listpack holding the new element is returned (and the old pointer passed is no longer considered valid)

If 'newp' is not NULL, at the end of a successful call '*newp' will be set to the address of the element just added, so that it will be possible to continue an iteration with next() and prev().

For deletion operations ('ele' set to None) 'newp' is set to the next element, on the right of the deleted one, or to NULL if the deleted element was the last one.

pub fn append(&mut self, value: Value) -> bool

Append the specified element 'ele' of length 'len' at the end of the listpack. It is implemented in terms of insert(), so the return value is the same as insert().

pub fn replace(&mut self, pos: Element, value: Value) -> Option<Element>

pub fn insert_int<V>(     &mut self,     value: V,     p: Element,     action: c_int ) -> Option<Element> where     V: Int,

Insert, delete or replace the specified element 'ele' of length 'len' at the specified position 'p', with 'p' being a listpack element pointer obtained with first(), last(), index(), next(), prev() or seek().

The element is inserted before, after, or replaces the element pointed by 'p' depending on the 'where' argument, that can be BEFORE, AFTER or REPLACE.

If 'ele' is set to NULL, the function removes the element pointed by 'p' instead of inserting one.

Returns None on out of memory or when the listpack total length would exceed the max allowed size of 2^32-1, otherwise the new pointer to the listpack holding the new element is returned (and the old pointer passed is no longer considered valid)

If 'newp' is not NULL, at the end of a successful call '*newp' will be set to the address of the element just added, so that it will be possible to continue an iteration with next() and prev().

pub fn append_int<V>(&mut self, value: V) -> bool where     V: Int,

Append the specified element 'ele' of length 'len' at the end of the listpack. It is implemented in terms of insert(), so the return value is the same as insert().

Returns true if it succeeded or false when out-of-memory or when the listpack total length would exceed the max allowed size of 2^32-1

pub fn replace_int<V>(&mut self, pos: Element, value: V) -> Option<Element> where     V: Int,

pub fn insert_str<V>(     &mut self,     value: V,     p: Element,     action: c_int ) -> Option<Element> where     V: Str,

Insert, delete or replace the specified element 'ele' of length 'len' at the specified position 'p', with 'p' being a listpack element pointer obtained with first(), last(), index(), next(), prev() or seek().

The element is inserted before, after, or replaces the element pointed by 'p' depending on the 'where' argument, that can be BEFORE, AFTER or REPLACE.

If 'ele' is set to NULL, the function removes the element pointed by 'p' instead of inserting one.

Returns None on out of memory or when the listpack total length would exceed the max allowed size of 2^32-1, otherwise the new pointer to the listpack holding the new element is returned (and the old pointer passed is no longer considered valid)

If 'newp' is not NULL, at the end of a successful call '*newp' will be set to the address of the element just added, so that it will be possible to continue an iteration with next() and prev().

For deletion operations ('ele' set to None) 'newp' is set to the next element, on the right of the deleted one, or to NULL if the deleted element was the last one.

If None is returned then it failed because of out-of-memory or invalid element pointer.

pub fn append_str<V>(&mut self, value: V) -> bool where     V: Str,

Append the specified element 'ele' of length 'len' at the end of the listpack. It is implemented in terms of insert(), so the return value is the same as insert().

pub fn replace_str<V>(&mut self, value: V, ele: Element) where     V: Str,

Replace the specified element with the specified value

pub fn delete(&mut self, p: Element) -> Option<Element>

Remove the element pointed by 'p', and return the resulting listpack. If 'newp' is not NULL, the next element pointer (to the right of the deleted one) is returned by reference. If the deleted element was the last one, '*newp' is set to None.

pub fn first(&self) -> Option<Element>

Return a pointer to the first element of the listpack, or None if the listpack has no elements.

pub fn last(&self) -> Option<Element>

Return a pointer to the last element of the listpack, or None if the listpack has no elements.

pub fn start(&self) -> Element

pub fn first_or_next(&self, after: Element) -> Option<Element>

pub fn next(&self, after: Element) -> Option<Element>

/* If 'after' points to an element of the listpack, calling next() will return the pointer to the next element (the one on the right), or None if 'after' already pointed to the last element of the listpack. */

pub fn last_or_prev(&self, after: Element) -> Option<Element>

pub fn prev(&self, before: Element) -> Option<Element>

If 'p' points to an element of the listpack, calling prev() will return the pointer to the previous element (the one on the left), or None if 'before' already pointed to the first element of the listpack.

pub fn seek(&self, index: i64) -> Option<Element>

Seek the specified element and returns the pointer to the seeked element. Positive indexes specify the zero-based element to seek from the head to the tail, negative indexes specify elements starting from the tail, where -1 means the last element, -2 the penultimate and so forth. If the index is out of range, NULL is returned.

pub unsafe fn unsafe_set_bytes(&mut self, len: u32)

pub unsafe fn unsafe_set_len(&mut self, len: u16)

Trait Implementations

impl Drop for Listpack

fn drop(&mut self)

Executes the destructor for this type.