Struct janetrs::JanetTuple

#[repr(transparent)]
pub struct JanetTuple<'data> { /* fields omitted */ }

Janet tuples are immutable, sequential types that are similar to Janet arrays.

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

Example

use janetrs::{Janet, JanetTuple};

let tuple = JanetTuple::builder(2)
    .put(Janet::number(10.0))
    .put(Janet::boolean(true));

Implementations

impl<'data> JanetTuple<'data>

pub fn builder(len: i32) -> JanetTupleBuilder<'data>

Start the build process to create a JanetTuple.

If the given len is lesser than zero it behaves the same as if len is zero.

pub fn with_default_elem(elem: Janet, len: i32) -> Self

Creates a tuple where all of it’s elements are elem.

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

Create a new JanetTuple with a raw pointer.

Safety

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

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

Returns a reference to an element in the tuple.

Examples

use janetrs::{Janet, JanetTuple};

let tup = JanetTuple::builder(2).put("hey").put(11).finalize();
assert_eq!(tup.get(0), Some(&Janet::from("hey")));
assert_eq!(tup.get(1), Some(&Janet::integer(11)));

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.

pub fn len(&self) -> i32

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

Examples

use janetrs::JanetTuple;

let tup = JanetTuple::builder(2).put("hey").put(11).finalize();
assert_eq!(tup.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if the tuple contains no elements.

Examples

use janetrs::JanetTuple;

let tup = JanetTuple::builder(2).put("hey").put(11).finalize();
assert!(!tup.is_empty());

let tup = JanetTuple::builder(0).finalize();
assert!(tup.is_empty());

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

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

Examples

use janetrs::tuple;

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

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

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

Examples

use janetrs::{tuple, Janet};

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

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

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 tuple, or None if it is empty.

Examples

use janetrs::{tuple, Janet};

let x = tuple![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)]);
}

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

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

Examples

use janetrs::{tuple, Janet};

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

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

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)]);
}

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

Divides one tuple 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).

Panics

Panics if mid > len or mid < 0.

Examples

use janetrs::{tuple, Janet};

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

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

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

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

pub fn repeat(&self, n: usize) -> JanetArray<'_>

Creates a tuple by repeating a tuple n times.

Panics

This function will panic if the capacity would overflow.

Examples

Basic usage:

use janetrs::{tuple, Janet};

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

A panic upon overflow:

use janetrs::{tuple, Janet};

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

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

Returns true if needle is a prefix of the tuple.

Examples

use janetrs::{tuple, Janet};

let v = tuple![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::{tuple, Janet};

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

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

Returns true if needle is a suffix of the tuple.

Examples

use janetrs::{tuple, Janet};

let v = tuple![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::{tuple, Janet};

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

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

Binary searches this tuple 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::{tuple, Janet};

let s = tuple![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::{tuple, Janet, JanetArray};

let mut s = tuple![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);
let mut s = JanetArray::from(s);
s.insert(idx as i32, num);
assert_eq!(
    s.as_ref(),
    tuple![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55].as_ref()
);

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

Binary searches this sorted tuple 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::{tuple, Janet};

let s = tuple![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,
});

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 tuple with a key extraction function.

Assumes that the tuple 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::{tuple, Janet};

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

Creates a iterator over the reference of the array itens.

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

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

Panics

Panics if size is 0.

Examples

use janetrs::{tuple, Janet};

let arr = tuple!['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 tuple is shorter than size:

use janetrs::{tuple, Janet};

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

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

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the tuple, 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 tuple.

Panics

Panics if chunk_size is 0.

Examples

use janetrs::{tuple, Janet};

let arr = tuple!['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());

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

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the tuple, 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 tuple.

Panics

Panics if chunk_size is 0.

Examples

use janetrs::{tuple, Janet};

let arr = tuple!['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')]);

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

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the tuple, 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 tuple.

Panics

Panics if chunk_size is 0.

Examples

use janetrs::{tuple, Janet};

let arr = tuple!['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());

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

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the tuple, 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 tuple.

Panics

Panics if chunk_size is 0.

Examples

use janetrs::{tuple, Janet};

let arr = tuple!['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')]);

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::{tuple, Janet, TaggedJanet};

let arr = tuple![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(), tuple![10, 40].as_ref());
assert_eq!(iter.next().unwrap(), tuple![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::{tuple, Janet, TaggedJanet};

let arr = tuple![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(), tuple![10, 40].as_ref());
assert_eq!(iter.next().unwrap(), tuple![].as_ref());
assert!(iter.next().is_none());

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

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

let arr = tuple![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(), tuple![10].as_ref());
assert_eq!(iter.next().unwrap(), tuple![].as_ref());
assert_eq!(iter.next().unwrap(), tuple![20].as_ref());
assert!(iter.next().is_none());

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::{tuple, Janet, TaggedJanet};

let arr = tuple![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(), tuple![44, 55].as_ref());
assert_eq!(iter.next().unwrap(), tuple![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::{tuple, Janet, TaggedJanet};

let v = tuple![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(), tuple![].as_ref());
assert_eq!(it.next().unwrap(), tuple![3, 5].as_ref());
assert_eq!(it.next().unwrap(), tuple![1, 1].as_ref());
assert_eq!(it.next().unwrap(), tuple![].as_ref());
assert_eq!(it.next(), None);

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 tuple.

Examples

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

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

let v = tuple![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);
}

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 tuple and works backwards. The matched element is not contained in the subslices.

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

Examples

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

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

let v = tuple![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);
}

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

Return a raw pointer to the tuple raw structure.

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

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

Return a raw pointer to the tuple 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

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

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

Performs the conversion.

impl Clone for JanetTuple<'_>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for JanetTuple<'_>

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

Formats the value using the given formatter.

impl DeepEq<JanetArray<'_>> for JanetTuple<'_>

fn deep_eq(&self, other: &JanetArray<'_>) -> bool

impl DeepEq<JanetTuple<'_>> for JanetArray<'_>

fn deep_eq(&self, other: &JanetTuple<'_>) -> bool

impl Default for JanetTuple<'_>

fn default() -> Self

Returns the “default value” for a type.

impl From<&'_ JanetArray<'_>> for JanetTuple<'_>

fn from(arr: &JanetArray<'_>) -> Self

Performs the conversion.

impl From<&'_ JanetTuple<'_>> for Janet

fn from(val: &JanetTuple<'_>) -> Self

Performs the conversion.

impl From<JanetArray<'_>> for JanetTuple<'_>

fn from(arr: JanetArray<'_>) -> Self

Performs the conversion.

impl From<JanetTuple<'_>> for JanetArray<'_>

fn from(tup: JanetTuple<'_>) -> Self

Performs the conversion.

impl From<JanetTuple<'_>> for Janet

fn from(val: JanetTuple<'_>) -> Self

Performs the conversion.

impl<U: Into<Janet>> FromIterator<U> for JanetTuple<'_>

fn from_iter<T: IntoIterator<Item = U>>(iter: T) -> Self

Creates a value from an iterator.

impl Index<i32> for JanetTuple<'_>

fn index(&self, index: i32) -> &Self::Output

Get a reference of the Janet hold by JanetTuple at index.

Janet Panics

This function may Janet panic if try to access index out of the bounds

type Output = Janet

The returned type after indexing.

impl<'data> IntoIterator for JanetTuple<'data>

type IntoIter = IntoIter<'data>

Which kind of iterator are we turning this into?

type Item = Janet

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, 'data> IntoIterator for &'a JanetTuple<'data>

type IntoIter = Iter<'a, 'data>

Which kind of iterator are we turning this into?

type Item = &'a Janet

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Ord for JanetTuple<'_>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<JanetTuple<'_>> for JanetTuple<'_>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialOrd<JanetTuple<'_>> for JanetTuple<'_>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<Janet> for JanetTuple<'_>

type Error = JanetConversionError

The type returned in the event of a conversion error.

fn try_from(value: Janet) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for JanetTuple<'_>