Struct rosy::Array

#[repr(transparent)]
pub struct Array<O = AnyObject> { /* fields omitted */ }

An instance of Ruby's Array class.

Performance

Although caution must be taken with as_slice and its mutable counterpart, it is much faster to iterate over the inner slice of objects in an array than it is to iterate over the array directly.

Examples

Ruby arrays can be treated as somewhat like a Vec without the borrow checker.

use rosy::prelude::*;

let s = String::from("hellooo");

let a = Array::from_slice(&[s, s, s]);
assert_eq!(a.len(), 3);

for obj in a {
    assert_eq!(obj, s);
}

Because the Iterator for Array performs a volatile read of the array length each time, a buffer overrun will never occur.

assert_eq!(a.len(), 3);
let mut num_iter = 0;

for _ in a {
    // `unsafe` required because `pop` raises an exception if `a` is frozen
    unsafe { a.pop() };
    num_iter += 1;
}

assert_eq!(num_iter, 2);

Just like Vec, one can even safely collect an iterator into an Array:

let array: Array = (0..10).collect();

for (i, obj) in array.into_iter().enumerate() {
    assert_eq!(obj, i);
}

Methods

impl<O: Object> Array<O>

pub fn new() -> Self

Creates a new empty instance.

pub fn from_slice<'s, T>(slice: &'s [T]) -> Self where
    &'s [T]: Into<Self>, 

Creates a new instance from the elements in slice.

pub fn with_capacity(capacity: usize) -> Self

Creates a new instance with capacity amount of storage.

pub fn duplicate(self) -> Self

Duplicates the contents of self into a new instance.

pub fn len(self) -> usize

Returns the number of elements in self.

Examples

use rosy::{Array, String};

let s = String::from("hi");
let a = Array::from_slice(&[s, s, s]);

assert_eq!(a.len(), 3);

pub fn is_empty(self) -> bool

Returns whether self is empty.

pub fn as_ptr(self) -> *const O

Returns a pointer to the first object in self.

pub fn as_ptr_mut(self) -> *mut O

Returns a mutable pointer to the first object in self.

pub unsafe fn as_slice(&self) -> &[O]

Returns a slice to the underlying objects of self.

Safety

Care must be taken to ensure that the length of self is not changed through the VM or otherwise.

pub unsafe fn as_slice_mut(&mut self) -> &mut [O]

Returns a mutable slice to the underlying objects of self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised. Care must also be taken to ensure that the length of self is not changed through the VM or otherwise.

pub fn get<I: ArrayIndex<O>>(self, index: I) -> Option<I::Output>

Returns the output at index or None if index is out-of-bounds.

pub unsafe fn get_unchecked<I: ArrayIndex<O>>(self, index: I) -> I::Output

Returns the output at index without safety checks on index.

pub fn subseq(self, range: Range<usize>) -> Option<Self>

Returns the subsequence of self at range.

Note: This respects the semantics of rb_ary_subseq, where indexing out of the array with a range greater than the actual slice in self will just return all remaining elements. Use get for slice indexing semantics.

pub fn first(self) -> Option<O>

Returns the first object in self.

pub fn last(self) -> Option<O>

Returns the last element in self.

pub unsafe fn clear(self)

Removes all elements from self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub unsafe fn extend_from_slice(self, slice: &[O])

Appends all of the elements in slice to self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub fn plus(self, other: Self) -> Self

Returns the result of performing self + other.

pub unsafe fn push(self, obj: O) -> AnyObject

Pushes obj onto the end of self.

Safety

The caller must ensure that self is not:

• Frozen, or else a FrozenError exception will be raised
• Array<AnyObject> that references Array<ConcreteObject> where obj is not the same type as ConcreteObject

pub unsafe fn pop(self) -> AnyObject

Pops the last element from self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

Examples

use rosy::{Array, String};

let s = String::from("Hi");
let a = Array::from_slice(&[s]);

unsafe {
    assert!(!a.pop().is_nil());
    assert!(a.pop().is_nil());
}

pub fn contains(self, obj: impl Into<O>) -> bool

Returns whether self contains obj.

This is equivalent to the include? method.

Examples

use rosy::{Array, String};

let array = Array::from_slice(&[
    String::from("yo"),
    String::from("hi"),
]);

assert!(array.contains("hi"));

pub unsafe fn remove_all(self, obj: impl Into<O>) -> Option<O>

Removes all items in self that are equal to obj.

This is equivalent to the delete method.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub unsafe fn reverse(self)

Reverses the contents of self in-palace.

This is equivalent to the reverse! method.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

#[must_use]

pub fn sorted(self) -> Self

Returns an instance with its contents sorted.

pub unsafe fn sort(self)

Sorts the contents of self in-place without checking whether self is frozen.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub fn join(self, separator: impl Into<String>) -> String

Joins the contents of self with separator.

Examples

use rosy::{Array, String};

let s = String::from("-");
let a = Array::from_slice(&[s, s, s]);

assert_eq!(a.join("."), "-.-.-");

Trait Implementations

impl<O: Object> Classify for Array<O>

fn class() -> Class<Self>

Returns the typed class that can be used to get an instance of self.

impl<O: Object> Object for Array<O>

fn unique_id() -> Option<u128>

Returns a unique identifier for an object type to facilitate casting.

fn cast<A: Object>(obj: A) -> Option<Self>

Attempts to create an instance by casting obj.

fn ty(self) -> Ty

Returns the virtual type of self.

fn is_ty(self, ty: Ty) -> bool

Returns whether the virtual type of self is ty.

unsafe fn from_raw(raw: usize) -> Self

Creates a new object from raw without checking.

unsafe fn cast_unchecked(obj: impl Object) -> Self

Casts obj to Self without checking its type.

fn into_any_object(self) -> AnyObject

Returns self as an AnyObject.

fn as_any_object(&self) -> &AnyObject

Returns a reference to self as an AnyObject.

fn as_any_slice(&self) -> &[AnyObject]

Returns self as a reference to a single-element slice.

fn raw(self) -> usize

Returns the raw object pointer.

unsafe fn as_unchecked<O: Object>(&self) -> &O

Casts self to O without checking whether it is one.

unsafe fn into_unchecked<O: Object>(self) -> O

Converts self to O without checking whether it is one.

fn id(self) -> u64

Returns the object's identifier.

fn class(self) -> Class<Self>

Returns the Class for self.

fn singleton_class(self) -> Class<Self>

Returns the singleton Class of self, creating one if it doesn't exist already.

fn mark(self)

Marks self for Ruby to avoid garbage collecting it.

unsafe fn force_recycle(self)

Forces the garbage collector to free the contents of self.

fn def_singleton_method<N, F>(self, name: N, f: F) -> Result where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn def_singleton_method_unchecked<N, F>(self, name: N, f: F) where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn call(self, method: impl Into<SymbolId>) -> AnyObject

Calls method on self and returns its output.

unsafe fn call_protected(self, method: impl Into<SymbolId>) -> Result<AnyObject>

Calls method on self and returns its output, or an exception if one is raised.

unsafe fn call_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls method on self with args and returns its output.

unsafe fn call_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls method on self with args and returns its output, or an exception if one is raised.

unsafe fn call_public(self, method: impl Into<SymbolId>) -> AnyObject

Calls the public method on self and returns its output.

unsafe fn call_public_protected(
    self,
    method: impl Into<SymbolId>
) -> Result<AnyObject>

Calls the public method on self and returns its output, or an exception if one is raised.

unsafe fn call_public_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls the public method on self with args and returns its output.

unsafe fn call_public_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls the public method on self with args and returns its output, or an exception if one is raised.

fn inspect(self) -> String

Returns a printable string representation of self.

fn to_s(self) -> String

Returns the result of calling the to_s method on self.

fn is_frozen(self) -> bool

Returns whether modifications can be made to self.

fn freeze(self)

Freezes self, preventing any further mutations.

fn is_eql<O: Object>(self, other: &O) -> bool

Returns whether self is equal to other in terms of the eql? method.

fn get_attr<N: Into<SymbolId>>(self, name: N) -> AnyObject

Returns the value for the attribute of self associated with name.

unsafe fn eval(self, args: impl EvalArgs) -> AnyObject

Evaluates args in the context of self.

unsafe fn eval_protected(self, args: impl EvalArgs) -> Result<AnyObject>

Evaluates args in the context of self, returning any raised exceptions.

impl<O: Object> PartialEq<AnyObject> for Array<O>

fn eq(&self, obj: &AnyObject) -> 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<O, A> PartialEq<[A]> for Array<O> where
    O: Object + PartialEq<A>, 

fn eq(&self, other: &[A]) -> 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<O, A> PartialEq<Vec<A>> for Array<O> where
    O: Object + PartialEq<A>, 

fn eq(&self, other: &Vec<A>) -> 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<T: Object, U: Object> PartialEq<Array<U>> for Array<T>

fn eq(&self, other: &Array<U>) -> 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<O> Copy for Array<O>

impl<O> Clone for Array<O>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Object, U: Object> PartialOrd<Array<U>> for Array<T>

fn partial_cmp(&self, other: &Array<U>) -> 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<O: Object> AsRef<AnyObject> for Array<O>

fn as_ref(&self) -> &AnyObject

Performs the conversion.

impl<O: Object> From<Array<O>> for AnyObject

fn from(object: Array<O>) -> AnyObject

Performs the conversion.

impl<O: Object, '_> From<&'_ [O]> for Array<O>

fn from(slice: &[O]) -> Self

Performs the conversion.

impl<O: Object> IntoIterator for Array<O>

type Item = O

The type of the elements being iterated over.

type IntoIter = Iter<O>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<O: Object> Debug for Array<O>

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

Formats the value using the given formatter.

impl<O: Object> Display for Array<O>

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

Formats the value using the given formatter.

impl<O: Object> Add<Array<O>> for Array<O>

type Output = Self

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self::Output

Performs the + operation.

impl<O: Object, A: Into<O>> FromIterator<A> for Array<O>

fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> Self

Creates a value from an iterator.