Crate spinoso_array

source ·
Expand description

Contiguous growable vector types that implement the Ruby Array API.

Array types are growable vectors with potentially heap-allocated contents. The types in this crate can be passed by pointer over FFI.

Array types implement the mutating APIs in the Ruby Array core class as well as indexing and slicing APIs.

spinoso-array is part of a collection of crates that implement the data structures that comprise the Ruby Core and Standard Library implementation for Artichoke Ruby.

§Array types

  • Array is based on Vec from the Rust alloc crate and standard library. This Spinoso array type is enabled by default.
  • SmallArray is based on SmallVec and implements the small vector optimization – small arrays are stored inline without a heap allocation. This Spinoso array type requires the small-array Cargo feature.
  • TinyArray is based on TinyVec and implements the small vector optimization – small arrays are stored inline without a heap allocation. This Spinoso array type requires the tiny-array Cargo feature.

§no_std

This crate is no_std with a required dependency on the alloc crate.

§Examples

You can create an Array<T> with new:

let ary: Array<i32> = Array::new();

Or with one of the many From and FromIterator implementations:

let ary: Array<i32> = Array::from(vec![1, 2, 3, 4]);
let ary2: Array<i32> = iter::repeat(1).take(10).collect();

You can push values onto the end of an array (which will grow the array as needed):

let mut ary = Array::from(&[1, 2]);
ary.push(3);

Popping values behaves similarly:

let mut ary = Array::from(&[1, 2]);
assert_eq!(ary.pop(), Some(2));

Arrays also support indexing (through the Index and IndexMut traits):

let mut a = Array::from(&[1, 2, 3]);
let three = a[2];
a[1] = a[1] + 5;

The Array vector types in this crate differ from Vec in the Rust std by offering many specialized slicing and mutation APIs. For example, rather than offering APIs like Vec::drain and Vec::splice, array types in this crate offer specialized methods like shift, shift_n, unshift, and unshift_n and splice-like methods with insert_slice, and set_slice.

let mut a = Array::from(&[1, 2, 3]);
a.unshift(0);
assert_eq!(a, [0, 1, 2, 3]);
let b = a.shift_n(10);
assert_eq!(a, []);
assert_eq!(b, [0, 1, 2, 3]);

§Panics

Arrays in this crate do not expose panicking slicing operations (except for their Index and IndexMut implementations). Instead of panicking, slicing APIs operate until the end of the vector or return &[]. Mutating APIs extend Arrays on out of bounds access.

Structs§

Constants§

  • Vectors that implement the small vector optimization can store 8 elements inline without a heap allocation.