Struct janetrs::JanetArray

source ·

pub struct JanetArray<'data> { /* private fields */ }

Expand description

Janet arrays are a fundamental datatype in Janet. Janet Arrays are values that contain a sequence of other values.

Arrays are also mutable, meaning that values can be added or removed in place.

To facilitate the creation of this structure, you can use the macro array.

§Examples

use janetrs::JanetArray;

let mut arr = JanetArray::new();
arr.push(10.1);
arr.push(12);

assert_eq!(2, arr.len());

Implementations§

source §

impl<'data> JanetArray<'data>

source

pub fn new() -> Self

Creates a empty JanetArray.

It is initially created with capacity 0, so it will not allocate until it is first pushed into.

§Examples

use janetrs::JanetArray;

let arr = JanetArray::new();

source

pub fn with_capacity(capacity: i32) -> Self

Create a empty JanetArray given to Janet the specified capacity.

When capacity is lesser than zero, it’s the same as calling with capacity equals to zero.

§Examples

use janetrs::JanetArray;

let arr = JanetArray::with_capacity(20);

source

pub const unsafe fn from_raw(raw: *mut CJanetArray) -> Self

Create a new JanetArray with a raw pointer.

§Safety

This function do not check if the given raw is NULL or not. Use at your own risk.

source

pub fn capacity(&self) -> i32

Returns the number of elements the array can hold without reallocating.

§Examples

use janetrs::JanetArray;

let arr = JanetArray::with_capacity(20);
assert_eq!(arr.capacity(), 20);

source

pub fn len(&self) -> i32

Returns the number of elements in the array, also referred to as its ‘length’.

§Examples

use janetrs::JanetArray;

let mut arr = JanetArray::new();
assert_eq!(arr.len(), 0);

arr.push(10);
assert_eq!(arr.len(), 1);

source

pub fn is_empty(&self) -> bool

Returns true if the array contains no elements.

§Examples

use janetrs::JanetArray;

let mut arr = JanetArray::new();
assert!(arr.is_empty());

arr.push(10);
assert!(!arr.is_empty());

source

pub fn set_len(&mut self, new_len: i32)

Set the length of the array to new_len.

If new_len is greater than the current array length, this append Janet nil values into the array, and if new_len is lesser than the current array length, the Janet garbage collector will handle the elements not used anymore, that’s the reason this function is safe to call compared to the Rust Vec method with the same name.

This functions does nothing if new_len is lesser than zero.

source

pub fn ensure(&mut self, check_capacity: i32, growth: i32)

Ensure that an array has enough space for check_capacity elements. If not, resize the backing memory to check_capacity * growth slots. In most cases, growth should be 1 or 2.

§Examples

use janetrs::JanetArray;

let mut arr = JanetArray::new();
assert_eq!(arr.capacity(), 0);

arr.ensure(2, 2);
assert_eq!(arr.capacity(), 4);

source

pub fn reserve(&mut self, additional: i32)

Reserves capacity for at least additional more elements to be inserted in the given JanetArray. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

§Panics

Panics if the new capacity exceeds i32::MAX bytes.

§Examples

use janetrs::array;

let mut arr = array![1];
arr.reserve(10);
assert!(arr.capacity() >= 11);

source

pub fn reserve_exact(&mut self, additional: i32)

Reserves the minimum capacity for exactly additional more elements to be inserted in the given JanetArray. After calling reserve_exact, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

§Panics

Panics if the new capacity overflows i32.

§Examples

use janetrs::array;

let mut arr = array![1];
arr.reserve_exact(10);
assert_eq!(arr.capacity(), 11);

source

pub fn clear(&mut self)

Clears the array, removing all values.

Note that this method has no effect on the allocated capacity of the array.

source

pub fn push(&mut self, value: impl Into<Janet>)

Appends an element to the back of the array.

§Panics

Panics if the number of elements overflow a i32.

§Examples

use janetrs::{Janet, JanetArray};

let mut arr = JanetArray::new();

arr.push(10);
assert_eq!(arr[0], &Janet::integer(10));

source

pub fn pop(&mut self) -> Option<Janet>

Removes the last element from a array and returns it, or None if it is empty.

§Examples

use janetrs::{Janet, JanetArray};

let mut arr = JanetArray::new();

arr.push(10);
assert_eq!(arr.len(), 1);
assert_eq!(arr.pop(), Some(Janet::integer(10)));
assert!(arr.is_empty())

source

pub fn peek(&mut self) -> Janet

Returns a copy of the last element in the array without modifying it.

§Examples

use janetrs::{Janet, JanetArray};

let mut arr = JanetArray::new();

arr.push(10);
assert_eq!(arr.len(), 1);
assert_eq!(arr.peek(), Janet::integer(10));
assert_eq!(arr.len(), 1);

source

pub fn get(&self, index: i32) -> Option<&Janet>

Returns a reference to an element in the array at theindex.

§Examples

use janetrs::{Janet, JanetArray};

let mut arr = JanetArray::new();

arr.push(10);
assert_eq!(arr.get(0), Some(&Janet::integer(10)));
assert_eq!(arr.get(1), None);

source

pub fn get_mut(&mut self, index: i32) -> Option<&'data mut Janet>

Returns a mutable reference to an element in the array at theindex. Returns a reference to an element in the array at theindex.

§Examples

use janetrs::{Janet, JanetArray};

let mut arr = JanetArray::new();

arr.push(10);
assert_eq!(arr.get_mut(0), Some(&mut Janet::integer(10)));
assert_eq!(arr.get(1), None);

*arr.get_mut(0).unwrap() = Janet::boolean(true);
assert_eq!(arr[0], &Janet::boolean(true));

source

pub unsafe fn get_unchecked(&self, index: i32) -> &Janet

Returns a reference to an element, without doing bounds checking.

§Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

source

pub unsafe fn get_unchecked_mut(&mut self, index: i32) -> &Janet

Returns a exclusive reference to an element, without doing bounds checking.

§Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

source

pub fn contains(&self, value: impl Into<Janet>) -> bool

Returns true if the array contains an element with the given value.

§Examples

use janetrs::array;

let arr = array![1.0, "foo", 4.0];
assert!(arr.contains("foo"));

source

pub fn append(&mut self, other: &mut Self)

Moves all the elements of other into the array, leaving other empty.

§Panics

Panics if the number of elements overflow a i32.

§Examples

use janetrs::array;

let mut arr1 = array![1, 2, 3];
let mut arr2 = array![4, 5, 6];

assert_eq!(arr1.len(), 3);
assert!(!arr2.is_empty());
arr1.append(&mut arr2);
assert_eq!(arr1.len(), 6);
assert!(arr2.is_empty());

source

pub fn insert(&mut self, index: i32, element: impl Into<Janet>)

Inserts an element at position index within the array, shifting all elements after it to the right.

§Janet Panics

Janet panics if index < 0 or index > len.

§Examples

use janetrs::array;

let mut array = array![1, 2];
array.insert(1, 3) // now it's `[1, 3, 2]`

source

pub fn remove(&mut self, index: i32) -> Janet

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

§Panics

Panics if index is out of the bounds.

§Examples

use janetrs::{array, Janet};

let mut arr = array![1, "2", 3.0];
let rmed = arr.remove(1);
assert_eq!(rmed, Janet::from("2"));
assert_eq!(arr.len(), 2);

source

pub fn truncate(&mut self, len: i32)

Shortens the array, keeping the first len elements and dropping the rest.

If len is greater than the array’s current length or len is lesser than 0, this has no effect.

§Examples

Truncating a five element vector to two elements:

use janetrs::array;

let mut arr = array![1, 2, 3, 4, 5];
arr.truncate(2);
assert_eq!(arr.len(), 2);

No truncation occurs when len is greater than the vector’s current length:

use janetrs::array;

let mut arr = array![1, 2, 3];
arr.truncate(8);
assert_eq!(arr.len(), 3);

Truncating when len == 0 is equivalent to calling the clear method.

use janetrs::array;

let mut arr = array![1, 2, 3];
arr.truncate(0);
assert!(arr.is_empty());

source

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

Returns a reference to the first element of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert_eq!(Some(&Janet::from(10)), v.first());

let w = array![];
assert_eq!(None, w.first());

source

pub fn first_mut(&mut self) -> Option<&mut Janet>

Returns a mutable reference to the first element of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let mut x = array![0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = Janet::from(5);
}
assert_eq!(x.as_ref(), array![5, 1, 2].as_ref());

source

pub fn split_first(&self) -> Option<(&Janet, &[Janet])>

Returns a reference of the first and a reference to all the rest of the elements of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let x = array![0, 1, 2];

if let Some((first, elements)) = x.split_first() {
    assert_eq!(first, &Janet::from(0));
    assert_eq!(elements, &[Janet::from(1), Janet::from(2)]);
}

source

pub fn split_first_mut(&mut self) -> Option<(&mut Janet, &mut [Janet])>

Returns a mutable reference of the first and a mutable reference to all the rest of the elements of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let mut x = array![0, 1, 2];

if let Some((first, elements)) = x.split_first_mut() {
    *first = Janet::from(3);
    elements[0] = Janet::from(4);
    elements[1] = Janet::from(5);
}
assert_eq!(x.as_ref(), array![3, 4, 5].as_ref());

source

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

Returns a reference to the last element of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert_eq!(Some(&Janet::from(30)), v.last());

let w = array![];
assert_eq!(None, w.last());

source

pub fn last_mut(&mut self) -> Option<&mut Janet>

Returns a mutable reference to the last element of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let mut x = array![0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = Janet::from(10);
}
assert_eq!(x.as_ref(), array![0, 1, 10].as_ref());

source

pub fn split_last(&self) -> Option<(&Janet, &[Janet])>

Returns a reference of the last and all the rest of the elements of the array, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let x = array![0, 1, 2];

if let Some((last, elements)) = x.split_last() {
    assert_eq!(last, &Janet::from(2));
    assert_eq!(elements, &[Janet::from(0), Janet::from(1)]);
}

source

pub fn split_last_mut(&mut self) -> Option<(&mut Janet, &mut [Janet])>

Returns a mutable to the last and all the rest of the elements of the slice, or None if it is empty.

§Examples

use janetrs::{array, Janet};

let mut x = array![0, 1, 2];

if let Some((last, elements)) = x.split_last_mut() {
    *last = Janet::from(3);
    elements[0] = Janet::from(4);
    elements[1] = Janet::from(5);
}
assert_eq!(x.as_ref(), array![4, 5, 3].as_ref());

source

pub fn split_at(&self, mid: i32) -> (&[Janet], &[Janet])

Divides one array into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

§Janet Panics

Panics if mid > len or mid < 0.

§Examples

use janetrs::{array, Janet};

let v = array![1, 2, 3, 4, 5, 6];

{
    let (left, right) = v.split_at(0);
    assert!(left.is_empty());
    assert_eq!(right, array![1, 2, 3, 4, 5, 6].as_ref());
}

{
    let (left, right) = v.split_at(2);
    assert_eq!(left, array![1, 2].as_ref());
    assert_eq!(right, array![3, 4, 5, 6].as_ref());
}

{
    let (left, right) = v.split_at(6);
    assert_eq!(left, array![1, 2, 3, 4, 5, 6].as_ref());
    assert!(right.is_empty());
}

source

pub fn split_at_mut(&mut self, mid: i32) -> (&mut [Janet], &mut [Janet])

Divides one mutable slice into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

§Janet Panics

Panics if mid > len or mid < 0.

§Examples

use janetrs::{array, Janet};

let mut v = array![1, 0, 3, 0, 5, 6];
// scoped to restrict the lifetime of the borrows
{
    let (left, right) = v.split_at_mut(2);
    assert_eq!(left, array![1, 0].as_ref());
    assert_eq!(right, array![3, 0, 5, 6].as_ref());
    left[1] = Janet::from(2);
    right[1] = Janet::from(4);
}
assert_eq!(v.as_ref(), array![1, 2, 3, 4, 5, 6].as_ref());

source

pub fn swap(&mut self, a: i32, b: i32)

Swaps two elements in the array.

§Arguments

a - The index of the first element
b - The index of the second element

§Janet Panics

Panics if a or b are out of bounds.

§Examples

use janetrs::{array, Janet};

let mut v = array!["a", "b", "c", "d"];
v.swap(1, 3);
assert_eq!(v.as_ref(), array!["a", "d", "c", "b"].as_ref());

source

pub fn reverse(&mut self)

Reverses the order of elements in the array, in place.

§Examples

use janetrs::{array, Janet};

let mut v = array![1, 2, 3];
v.reverse();
assert_eq!(v.as_ref(), array![3, 2, 1].as_ref());

source

pub fn repeat(&self, n: usize) -> Self

Creates a array by repeating a array n times.

§Janet Panics

This function will panic if the capacity would overflow.

§Examples

Basic usage:

use janetrs::{array, Janet};

assert_eq!(
    array![1, 2].repeat(3).as_ref(),
    array![1, 2, 1, 2, 1, 2].as_ref()
);

A panic upon overflow:

use janetrs::{array, Janet};

// this will panic at runtime
b"0123456789abcdef".repeat(usize::MAX);

source

pub fn starts_with(&self, needle: &[Janet]) -> bool

Returns true if needle is a prefix of the array.

§Examples

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert!(v.starts_with(&[Janet::from(10)]));
assert!(v.starts_with(&[Janet::from(10), Janet::from(40)]));
assert!(!v.starts_with(&[Janet::from(50)]));
assert!(!v.starts_with(&[Janet::from(10), Janet::from(50)]));

Always returns true if needle is an empty slice:

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert!(v.starts_with(&[]));
let v = array![];
assert!(v.starts_with(&[]));

source

pub fn ends_with(&self, needle: &[Janet]) -> bool

Returns true if needle is a suffix of the array.

§Examples

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert!(v.ends_with(&[Janet::from(30)]));
assert!(v.ends_with(&[Janet::from(40), Janet::from(30)]));
assert!(!v.ends_with(&[Janet::from(50)]));
assert!(!v.ends_with(&[Janet::from(50), Janet::from(30)]));

Always returns true if needle is an empty slice:

use janetrs::{array, Janet};

let v = array![10, 40, 30];
assert!(v.ends_with(&[]));
let v = array![];
assert!(v.ends_with(&[]));

source

pub fn binary_search(&self, x: &Janet) -> Result<usize, usize>

Binary searches this array for a given element.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

§Examples

Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].

use janetrs::{array, Janet};

let s = array![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&Janet::from(13)), Ok(9));
assert_eq!(s.binary_search(&Janet::from(4)), Err(7));
assert_eq!(s.binary_search(&Janet::from(100)), Err(13));
let r = s.binary_search(&Janet::from(1));
assert!(match r {
    Ok(1..=4) => true,
    _ => false,
});

If you want to insert an item to a sorted vector, while maintaining sort order:

use janetrs::{array, Janet};

let mut s = array![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = Janet::from(42);
let idx = s.binary_search(&num).unwrap_or_else(|x| x);
s.insert(idx as i32, num);
assert_eq!(
    s.as_ref(),
    array![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55].as_ref()
);

source

pub fn binary_search_by<'a, F>(&'a self, f: F) -> Result<usize, usize>
where F: FnMut(&'a Janet) -> Ordering,

Binary searches this sorted array with a comparator function.

The comparator function should implement an order consistent with the sort order of the underlying slice, returning an order code that indicates whether its argument is Less, Equal or Greater the desired target.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

§Examples

Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].

use janetrs::{array, Janet};

let s = array![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let seek = Janet::from(13);
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = Janet::from(4);
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = Janet::from(100);
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = Janet::from(1);
let r = s.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r {
    Ok(1..=4) => true,
    _ => false,
});

source

pub fn binary_search_by_key<'a, B, F>( &'a self, b: &B, f: F ) -> Result<usize, usize>
where F: FnMut(&'a Janet) -> B, B: Ord,

Binary searches this array with a key extraction function.

Assumes that the array is sorted by the key, for instance with sort_by_key using the same key extraction function.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

§Examples

TODO: Find a good example

use janetrs::{array, Janet};

source

pub fn dedup(&mut self)

Removes consecutive repeated elements in the array according to the DeepEq trait implementation.

If the array is sorted, this removes all duplicates.

§Examples

use janetrs::{array, DeepEq, Janet, TaggedJanet::Number};
let mut arr = array![1, 2, 2, 3, 2];

arr.dedup();

assert!(arr.deep_eq(&array![1, 2, 3, 2]));

source

pub fn dedup_by_key<F>(&mut self, key: F)
where F: FnMut(&mut Janet) -> Janet,

Removes all but the first of consecutive elements in the array that resolve to the same key.

If the array is sorted, this removes all duplicates.

§Examples

use janetrs::{array, DeepEq, Janet, TaggedJanet::Number};
let mut arr = array![10, 20, 21, 30, 20];

arr.dedup_by_key(|i| {
    if let Number(i) = i.unwrap() {
        ((i / 10.0) as i32).into()
    } else {
        Janet::nil()
    }
});

assert!(arr.deep_eq(&array![10, 20, 30, 20]));

source

pub fn dedup_by<F>(&mut self, same_bucket: F)
where F: FnMut(&mut Janet, &mut Janet) -> bool,

Removes all but the first of consecutive elements in the array satisfying a given equality relation.

The same_bucket function is passed references to two elements from the vector and must determine if the elements compare equal. The elements are passed in opposite order from their order in the slice, so if same_bucket(a, b) returns true, a is removed.

If the vector is sorted, this removes all duplicates.

§Examples

use janetrs::{array, DeepEq, Janet};
let mut arr = array!["foo", "bar", "bar", "baz", "bar"];

arr.dedup_by(|&mut a, &mut b| a.eq(&b));
assert!(arr.deep_eq(&array!["foo", "bar", "baz", "bar"]));

source

pub fn sort(&mut self)

Sorts the array.

This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) worst-case.

When applicable, unstable sorting is preferred because it is generally faster than stable sorting and it doesn’t allocate auxiliary memory. See sort_unstable.

§Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the slice is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short slices a non-allocating insertion sort is used instead.

§Examples

use janetrs::{array, Janet};

let mut v = array![-5, 4, 1, -3, 2];

v.sort();
assert_eq!(v.as_ref(), array![-5, -3, 1, 2, 4].as_ref());

source

pub fn sort_by<F>(&mut self, compare: F)
where F: FnMut(&Janet, &Janet) -> Ordering,

Sorts the array with a comparator function.

This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) worst-case.

The comparator function must define a total ordering for the elements in the slice. If the ordering is not total, the order of the elements is unspecified. An order is a total order if it is (for all a, b and c):

total and antisymmetric: exactly one of a < b, a == b or a > b is true, and
transitive, a < b and b < c implies a < c. The same must hold for both == and >.

When applicable, unstable sorting is preferred because it is generally faster than stable sorting and it doesn’t allocate auxiliary memory. See sort_unstable_by.

§Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the slice is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short slices a non-allocating insertion sort is used instead.

§Examples

use janetrs::{array, Janet};

let mut v = array![5, 4, 1, 3, 2];
v.sort_by(|a, b| a.cmp(b));
assert_eq!(v.as_ref(), array![1, 2, 3, 4, 5].as_ref());

// reverse sorting
v.sort_by(|a, b| b.cmp(a));
assert_eq!(v.as_ref(), array![5, 4, 3, 2, 1].as_ref());

source

pub fn sort_by_key<K, F>(&mut self, f: F)
where F: FnMut(&Janet) -> K, K: Ord,

Sorts the array with a key extraction function.

This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) worst-case, where the key function is O(m).

For expensive key functions (e.g. functions that are not simple property accesses or basic operations), sort_by_cached_key is likely to be significantly faster, as it does not recompute element keys.

When applicable, unstable sorting is preferred because it is generally faster than stable sorting and it doesn’t allocate auxiliary memory. See sort_unstable_by_key.

§Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the slice is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short slices a non-allocating insertion sort is used instead.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut v = array![-5i32, 4, 1, -3, 2];

v.sort_by_key(|k| match k.unwrap() {
    TaggedJanet::Number(n) => n.abs() as i128,
    _ => 0,
});
assert_eq!(v.as_ref(), array![1, 2, -3, 4, -5].as_ref());

source

pub fn sort_unstable(&mut self)

Sorts the array, but may not preserve the order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(n * log(n)) worst-case.

§Current implementation

The current algorithm is based on pattern-defeating quicksort by Orson Peters, which combines the fast average case of randomized quicksort with the fast worst case of heapsort, while achieving linear time on slices with certain patterns. It uses some randomization to avoid degenerate cases, but with a fixed seed to always provide deterministic behavior.

It is typically faster than stable sorting, except in a few special cases, e.g., when the slice consists of several concatenated sorted sequences.

§Examples

use janetrs::{array, Janet};

let mut v = array![-5, 4, 1, -3, 2];

v.sort_unstable();
assert_eq!(v.as_ref(), array![-5, -3, 1, 2, 4].as_ref());

source

pub fn sort_unstable_by<F>(&mut self, compare: F)
where F: FnMut(&Janet, &Janet) -> Ordering,

Sorts the array with a comparator function, but may not preserve the order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(n * log(n)) worst-case.

The comparator function must define a total ordering for the elements in the array. If the ordering is not total, the order of the elements is unspecified. An order is a total order if it is (for all a, b and c):

total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
transitive, a .

§Current implementation

The current algorithm is based on pattern-defeating quicksort by Orson Peters, which combines the fast average case of randomized quicksort with the fast worst case of heapsort, while achieving linear time on slices with certain patterns. It uses some randomization to avoid degenerate cases, but with a fixed seed to always provide deterministic behavior.

It is typically faster than stable sorting, except in a few special cases, e.g., when the slice consists of several concatenated sorted sequences.

§Examples

use janetrs::{array, Janet};

let mut v = array![5, 4, 1, 3, 2];
v.sort_unstable_by(|a, b| a.cmp(b));
assert_eq!(v.as_ref(), array![1, 2, 3, 4, 5].as_ref());

// reverse sorting
v.sort_unstable_by(|a, b| b.cmp(a));
assert_eq!(v.as_ref(), array![5, 4, 3, 2, 1].as_ref());

source

pub fn sort_unstable_by_key<K, F>(&mut self, f: F)
where F: FnMut(&Janet) -> K, K: Ord,

Sorts the array with a key extraction function, but may not preserve the order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(m * n * log(n)) worst-case, where the key function is O(m).

§Current implementation

The current algorithm is based on pattern-defeating quicksort by Orson Peters, which combines the fast average case of randomized quicksort with the fast worst case of heapsort, while achieving linear time on slices with certain patterns. It uses some randomization to avoid degenerate cases, but with a fixed seed to always provide deterministic behavior.

Due to its key calling strategy, sort_unstable_by_key is likely to be slower than sort_by_cached_key in cases where the key function is expensive.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut v = array![-5i32, 4, 1, -3, 2];

v.sort_unstable_by_key(|k| match k.unwrap() {
    TaggedJanet::Number(n) => n.abs() as i128,
    _ => 0,
});
assert_eq!(v.as_ref(), array![1, 2, -3, 4, -5].as_ref());

source

pub fn iter(&self) -> Iter<'_, '_> ⓘ

Creates a iterator over the reference of the array itens.

§Examples

use janetrs::array;

let arr = array![1, 2, "janet"];

for elem in arr.iter() {
    println!("{}", elem);
}

source

pub fn iter_mut<'a>(&'a mut self) -> IterMut<'a, 'data> ⓘ

Creates a iterator over the mutable reference of the array itens.

use janetrs::{array, Janet};

let mut arr = array![1, 2, "janet"];

for elem in arr.iter_mut() {
    *elem = Janet::from("Janet");
}

assert!(arr.iter().all(|j| j == Janet::from("Janet")));

source

pub fn windows(&self, size: usize) -> Windows<'_, Janet>

Creates an iterator over all contiguous windows of length size. The windows overlap. If the array is shorter than size, the iterator returns no values.

§Janet Panics

Panics if size is 0.

§Examples

use janetrs::{array, Janet};

let arr = array!['r', 'u', 's', 't'];
let mut iter = arr.windows(2);
assert_eq!(iter.next().unwrap(), &[Janet::from('r'), Janet::from('u')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('u'), Janet::from('s')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('s'), Janet::from('t')]);
assert!(iter.next().is_none());

If the array is shorter than size:

use janetrs::{array, Janet};

let arr = array!['f', 'o', 'o'];
let mut iter = arr.windows(4);
assert!(iter.next().is_none());

source

pub fn chunks(&self, chunk_size: usize) -> Chunks<'_, Janet>

Creates an iterator over chunk_size elements of the array at a time, starting at the beginning of the array.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the array, then the last chunk will not have length chunk_size.

See chunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size elements, and rchunks for the same iterator but starting at the end of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let arr = array!['l', 'o', 'r', 'e', 'm'];
let mut iter = arr.chunks(2);
assert_eq!(iter.next().unwrap(), &[Janet::from('l'), Janet::from('o')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('r'), Janet::from('e')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('m')]);
assert!(iter.next().is_none());

source

pub fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut<'_, Janet>

Creates an iterator over chunk_size elements of the array at a time, starting at the beginning of the array.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the array, then the last chunk will not have length chunk_size.

See chunks_exact_mut for a variant of this iterator that returns chunks of always exactly chunk_size elements, and rchunks_mut for the same iterator but starting at the end of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let mut v = array![0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.chunks_mut(2) {
    for elem in chunk.iter_mut() {
        *elem = Janet::from(count);
    }
    count += 1;
}
assert_eq!(v.as_ref(), array![1, 1, 2, 2, 3].as_ref());

source

pub fn chunks_exact(&self, chunk_size: usize) -> ChunksExact<'_, Janet>

Creates an iterator over chunk_size elements of the array at a time, starting at the beginning of the array.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the array, then the last up to chunk_size-1 elements will be omitted and can be retrieved from the remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks.

See chunks for a variant of this iterator that also returns the remainder as a smaller chunk, and rchunks_exact for the same iterator but starting at the end of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let arr = array!['l', 'o', 'r', 'e', 'm'];
let mut iter = arr.chunks_exact(2);
assert_eq!(iter.next().unwrap(), &[Janet::from('l'), Janet::from('o')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('r'), Janet::from('e')]);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &[Janet::from('m')]);

source

pub fn chunks_exact_mut( &mut self, chunk_size: usize ) -> ChunksExactMut<'_, Janet>

Creates an iterator over chunk_size elements of the array at a time, starting at the beginning of the array.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the array, then the last up to chunk_size-1 elements will be omitted and can be retrieved from the into_remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks_mut.

See chunks_mut for a variant of this iterator that also returns the remainder as a smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let mut v = array![0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.chunks_exact_mut(2) {
    for elem in chunk.iter_mut() {
        *elem = Janet::from(count);
    }
    count += 1;
}
assert_eq!(v.as_ref(), array![1, 1, 2, 2, 0].as_ref());

source

pub fn rchunks(&self, chunk_size: usize) -> RChunks<'_, Janet>

Create an iterator over chunk_size elements of the array at a time, starting at the end of the array.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the array, then the last chunk will not have length chunk_size.

See rchunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size elements, and chunks for the same iterator but starting at the beginning of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let arr = array!['l', 'o', 'r', 'e', 'm'];
let mut iter = arr.rchunks(2);
assert_eq!(iter.next().unwrap(), &[Janet::from('e'), Janet::from('m')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('o'), Janet::from('r')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('l')]);
assert!(iter.next().is_none());

source

pub fn rchunks_mut(&mut self, chunk_size: usize) -> RChunksMut<'_, Janet>

Create an iterator over chunk_size elements of the array at a time, starting at the end of the array.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the array, then the last chunk will not have length chunk_size.

See rchunks_exact_mut for a variant of this iterator that returns chunks of always exactly chunk_size elements, and chunks_mut for the same iterator but starting at the beginning of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let mut v = array![0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.rchunks_mut(2) {
    for elem in chunk.iter_mut() {
        *elem = Janet::from(count);
    }
    count += 1;
}
assert_eq!(v.as_ref(), array![3, 2, 2, 1, 1].as_ref());

source

pub fn rchunks_exact(&self, chunk_size: usize) -> RChunksExact<'_, Janet>

Returns an iterator over chunk_size elements of the array at a time, starting at the end of the array.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the array, then the last up to chunk_size-1 elements will be omitted and can be retrieved from the remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks.

See rchunks for a variant of this iterator that also returns the remainder as a smaller chunk, and chunks_exact for the same iterator but starting at the beginning of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let arr = array!['l', 'o', 'r', 'e', 'm'];
let mut iter = arr.rchunks_exact(2);
assert_eq!(iter.next().unwrap(), &[Janet::from('e'), Janet::from('m')]);
assert_eq!(iter.next().unwrap(), &[Janet::from('o'), Janet::from('r')]);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &[Janet::from('l')]);

source

pub fn rchunks_exact_mut( &mut self, chunk_size: usize ) -> RChunksExactMut<'_, Janet>

Returns an iterator over chunk_size elements of the array at a time, starting at the end of the array.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the array, then the last up to chunk_size-1 elements will be omitted and can be retrieved from the into_remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks_mut.

See rchunks_mut for a variant of this iterator that also returns the remainder as a smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning of the array.

§Janet Panics

Panics if chunk_size is 0.

§Examples

use janetrs::{array, Janet};

let mut v = array![0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.rchunks_exact_mut(2) {
    for elem in chunk.iter_mut() {
        *elem = Janet::from(count);
    }
    count += 1;
}
assert_eq!(v.as_ref(), array![0, 2, 2, 1, 1].as_ref());

source

pub fn split<F>(&self, pred: F) -> Split<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over subslices separated by elements that match pred. The matched element is not contained in the subslices.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let arr = array![10, 40, 33, 20];
let mut iter = arr.split(|j| match j.unwrap() {
    TaggedJanet::Number(num) => (num % 3.0) as u128 == 0,
    _ => false,
});

assert_eq!(iter.next().unwrap(), array![10, 40].as_ref());
assert_eq!(iter.next().unwrap(), array![20].as_ref());
assert!(iter.next().is_none());

If the first element is matched, an empty slice will be the first item returned by the iterator. Similarly, if the last element in the slice is matched, an empty slice will be the last item returned by the iterator:

use janetrs::{array, Janet, TaggedJanet};

let arr = array![10, 40, 33];
let mut iter = arr.split(|j| match j.unwrap() {
    TaggedJanet::Number(num) => (num % 3.0) as u128 == 0,
    _ => false,
});

assert_eq!(iter.next().unwrap(), array![10, 40].as_ref());
assert_eq!(iter.next().unwrap(), array![].as_ref());
assert!(iter.next().is_none());

If two matched elements are directly adjacent, an empty slice will be present between them:

use janetrs::{array, Janet, TaggedJanet};

let arr = array![10, 6, 33, 20];
let mut iter = arr.split(|j| match j.unwrap() {
    TaggedJanet::Number(num) => (num % 3.0) as u128 == 0,
    _ => false,
});

assert_eq!(iter.next().unwrap(), array![10].as_ref());
assert_eq!(iter.next().unwrap(), array![].as_ref());
assert_eq!(iter.next().unwrap(), array![20].as_ref());
assert!(iter.next().is_none());

source

pub fn split_mut<F>(&mut self, pred: F) -> SplitMut<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over mutable subslices separated by elements that match pred. The matched element is not contained in the subslices.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut v = array![10, 40, 30, 20, 60, 50];

for group in v.split_mut(|j| match j.unwrap() {
    TaggedJanet::Number(num) => (num % 3.0) as i128 == 0,
    _ => false,
}) {
    group[0] = Janet::from(1);
}
assert_eq!(v.as_ref(), array![1, 40, 30, 1, 60, 1].as_ref());

source

pub fn rsplit<F>(&self, pred: F) -> RSplit<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over subslices separated by elements that match pred, starting at the end of the slice and working backwards. The matched element is not contained in the subslices.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let arr = array![11, 22, 33, 0, 44, 55];
let mut iter = arr.rsplit(|j| match j.unwrap() {
    TaggedJanet::Number(num) => num as i64 == 0,
    _ => false,
});

assert_eq!(iter.next().unwrap(), array![44, 55].as_ref());
assert_eq!(iter.next().unwrap(), array![11, 22, 33].as_ref());
assert_eq!(iter.next(), None);

As with split(), if the first or last element is matched, an empty slice will be the first (or last) item returned by the iterator.

use janetrs::{array, Janet, TaggedJanet};

let v = array![0, 1, 1, 2, 3, 5, 8];
let mut it = v.rsplit(|j| match j.unwrap() {
    TaggedJanet::Number(n) => n as i64 % 2 == 0,
    _ => false,
});
assert_eq!(it.next().unwrap(), array![].as_ref());
assert_eq!(it.next().unwrap(), array![3, 5].as_ref());
assert_eq!(it.next().unwrap(), array![1, 1].as_ref());
assert_eq!(it.next().unwrap(), array![].as_ref());
assert_eq!(it.next(), None);

source

pub fn rsplit_mut<F>(&mut self, pred: F) -> RSplitMut<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over mutable subslices separated by elements that match pred, starting at the end of the slice and working backwards. The matched element is not contained in the subslices.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut v = array![100, 400, 300, 200, 600, 500];

let mut count = 0;
for group in v.rsplit_mut(|j| match j.unwrap() {
    TaggedJanet::Number(num) => (num % 3.0) as i128 == 0,
    _ => false,
}) {
    count += 1;
    group[0] = Janet::from(count);
}
assert_eq!(v.as_ref(), array![3, 400, 300, 2, 600, 1].as_ref());

source

pub fn splitn<F>(&self, n: usize, pred: F) -> SplitN<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over subslices separated by elements that match pred, limited to returning at most n items. The matched element is not contained in the subslices.

The last element returned, if any, will contain the remainder of the array.

§Examples

Print the array split once by numbers divisible by 3 (i.e., [10, 40], [20, 60, 50]):

use janetrs::{array, Janet, TaggedJanet};

let v = array![10, 40, 30, 20, 60, 50];

for group in v.splitn(2, |j| match j.unwrap() {
    TaggedJanet::Number(num) => num as i64 % 3 == 0,
    _ => false,
}) {
    println!("{:?}", group);
}

source

pub fn splitn_mut<F>(&mut self, n: usize, pred: F) -> SplitNMut<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over subslices separated by elements that match pred, limited to returning at most n items. The matched element is not contained in the subslices.

The last element returned, if any, will contain the remainder of the array.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut v = array![10, 40, 30, 20, 60, 50];

for group in v.splitn_mut(2, |j| match j.unwrap() {
    TaggedJanet::Number(num) => num as i64 % 3 == 0,
    _ => false,
}) {
    group[0] = Janet::from(1);
}
assert_eq!(v.as_ref(), array![1, 40, 30, 1, 60, 50].as_ref());

source

pub fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<'_, F>
where F: FnMut(&Janet) -> bool,

Returns an iterator over subslices separated by elements that match pred limited to returning at most n items. This starts at the end of the array and works backwards. The matched element is not contained in the subslices.

The last element returned, if any, will contain the remainder of the array.

§Examples

Print the array split once, starting from the end, by numbers divisible by 3 (i.e., [50], [10, 40, 30, 20]):

use janetrs::{array, Janet, TaggedJanet};

let v = array![10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |j| match j.unwrap() {
    TaggedJanet::Number(num) => num as i64 % 3 == 0,
    _ => false,
}) {
    println!("{:?}", group);
}

source

pub fn rsplitn_mut<F>(&mut self, n: usize, pred: F) -> RSplitNMut<'_, F>
where F: FnMut(&Janet) -> bool,

Creates an iterator over subslices separated by elements that match pred limited to returning at most n items. This starts at the end of the array and works backwards. The matched element is not contained in the subslices.

The last element returned, if any, will contain the remainder of the array.

§Examples

use janetrs::{array, Janet, TaggedJanet};

let mut s = array![10, 40, 30, 20, 60, 50];

for group in s.rsplitn_mut(2, |j| match j.unwrap() {
    TaggedJanet::Number(num) => num as i64 % 3 == 0,
    _ => false,
}) {
    group[0] = Janet::from(1);
}
assert_eq!(s.as_ref(), array![1, 40, 30, 20, 60, 1].as_ref());

source

pub const fn as_raw(&self) -> *const CJanetArray

Return a raw pointer to the array raw structure.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage.

If you need to mutate the contents of the slice, use as_mut_ptr.

source

pub fn as_mut_raw(&mut self) -> *mut CJanetArray

Return a raw mutable pointer to the array raw structure.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage.

source

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

Return a raw pointer to the array first data.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage.

source

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

Return a raw mutable pointer to the array first data.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage.

Trait Implementations§

source §

impl AsMut<[Janet]> for JanetArray<'_>

source §

fn as_mut(&mut self) -> &mut [Janet]

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

source §

impl AsRef<[Janet]> for JanetArray<'_>

source §

fn as_ref(&self) -> &[Janet]

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

source §

impl Clone for JanetArray<'_>

source §

fn clone(&self) -> Self

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

source §

impl Debug for JanetArray<'_>

source §

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

Formats the value using the given formatter. Read more

source §

fn default() -> Self

Returns the “default value” for a type. Read more

source §

impl<'a> Extend<&'a Janet> for JanetArray<'_>

source §

fn extend<T: IntoIterator<Item = &'a Janet>>(&mut self, iter: T)

Extends a collection with the contents of an iterator. Read more

source §

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

source §

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

source §

impl Extend<Janet> for JanetArray<'_>

source §

fn extend<T: IntoIterator<Item = Janet>>(&mut self, iter: T)

Extends a collection with the contents of an iterator. Read more

source §

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

source §

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

source §