logo
pub struct Array(_);
Expand description

A contiguous growable array type based on Vec<sys::mrb_value> that implements the Ruby Array API for artichoke-backend and mruby.

Array implements indexing and mutating APIs that make an ideal backend for the Ruby Array core class. In practice, this results in less generic, more single-use APIs. For example, instead of Vec::drain, Array implements shift, shift_n, pop, and pop_n.

Similarly, slicing APIs are more specialized, such as first_n and last_n. Slicing APIs do not return Option, instead preferring to return an empty slice.

Array implements BoxUnboxVmValue which enables it to be serialized to a mruby value and unboxed to the Rust Array type.

Implementations

Construct a new, empty Array.

The vector will not allocate until elements are pushed into it.

Construct a new, empty Array with the specified capacity.

The vector will be able to hold exactly capacity elements without reallocating. If capacity is 0, the vector will not allocate.

It is important to note that although the returned vector has the capacity specified, the vector will have a zero length.

Construct a new two-element Array from the given arguments.

The vector is constructed with capacity of 2.

Returns an iterator over the slice.

Extracts a slice containing the entire vector.

Equivalent to &ary[..].

Extracts a mutable slice containing the entire vector.

Equivalent to &mut ary[..].

Returns a raw pointer to the vector’s buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to (except inside an UnsafeCell) using this pointer or any pointer derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.

Returns an unsafe mutable pointer to the vector’s buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Examples

This method is primarily used when mutating a Array via a raw pointer passed over FFI.

See the ARY_PTR macro in mruby.

Set the vector’s length without dropping or moving out elements

This method is unsafe because it changes the notion of the number of “valid” elements in the vector. Use with care.

Safety
  • new_len must be less than or equal to capacity().
  • The elements at old_len..new_len must be initialized.
Examples

This method is primarily used when mutating a Array via a raw pointer passed over FFI.

See the ARY_PTR macro in mruby.

Creates an Array directly from the raw components of another array.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

  • ptr needs to have been previously allocated via Array<T> (at least, it’s highly likely to be incorrect if it wasn’t).
  • T needs to have the same size and alignment as what ptr was allocated with. (T having a less strict alignment is not sufficient, the alignment really needs to be equal to satisfy the dealloc requirement that memory must be allocated and deallocated with the same layout.)
  • length needs to be less than or equal to capacity.
  • capacity needs to be the capacity that the pointer was allocated with.

Violating these may cause problems like corrupting the allocator’s internal data structures.

The ownership of ptr is effectively transferred to the Array<T> which may then deallocate, reallocate or change the contents of memory pointed to by the pointer at will. Ensure that nothing else uses the pointer after calling this function.

Decomposes an Array<T> into its raw components.

Returns the raw pointer to the underlying data, the length of the array (in elements), and the allocated capacity of the data (in elements).

After calling this function, the caller is responsible for the memory previously managed by the Array. The only way to do this is to convert the raw pointer, length, and capacity back into a Array with the from_raw_parts function, allowing the destructor to perform the cleanup.

Consume the array and return its elements as a Vec<T>.

For Array, this is a cheap operation that unwraps the inner Vec.

Converts the vector into Box<[T]>.

This will drop any excess capacity.

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

Reserves capacity for at least additional more elements to be inserted in the given Array<T>. 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 overflows usize.

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

Clears the vector, removing all values.

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

Returns the number of elements in the vector, also referred to as its “length”.

Returns true if the vector contains no elements.

Returns a reference to an element at the index.

Unlike Vec, this method does not support indexing with a range. See the slice method for retrieving a sub-slice from the array.

Deletes the element at the specified index, returning that element, or None if the index is out of range.

Returns the first element from the vector, or None if the vector is empty.

To retrieve a slice of the first elements in the vector, use first_n.

Returns up to n of the first elements from the vector, or &[] if the vector is empty.

To retrieve only the first element in the vector, use first.

Returns the last element from the vector, or None if the vector is empty.

To retrieve a slice of the last elements in the vector, use last_n.

Returns up to n of the last elements from the vector, or &[] if the vector is empty.

To retrieve only the last element in the vector, use last.

Returns a slice of the underlying vector that includes only the first n elements.

If n is greater than or equal to the length of the vector, &self[..] is returned.

The inverse of this operation is drop_n.

Returns a slice of the underlying vector that excludes the first n elements.

If n is greater than or equal to the length of the vector, &[] is returned.

The inverse of this operation is take_n.

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

To pop more than one element from the end of the vector, use pop_n.

Removes the last n elements from the vector.

To pop a single element from the end of the vector, use pop.

Appends an element to the back of the vector.

To push more than one element to the end of the vector, use concat or extend.

Panics

Panics if the number of elements in the vector overflows a usize.

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

Removes the first element of the vector and returns it (shifting all other elements down by one). Returns None if the vector is empty.

This operation is also known as “pop front”.

To remove more than one element from the front of the vector, use shift_n.

Removes the first n elements from the vector.

To shift a single element from the front of the vector, use shift.

Inserts an element to the front of the vector.

To insert more than one element to the front of the vector, use unshift_n.

This operation is also known as “prepend”.

Panics

Panics if the number of elements in the vector overflows a usize.

Return a reference to a subslice of the vector.

This function always returns a slice. If the range specified by start and end overlaps the vector (even if only partially), the overlapping slice is returned. If the range does not overlap the vector, an empty slice is returned.

Construct a new Array with length len and all elements set to default. The Array will have capacity len.

Appends the elements of other to self.

Slice version of extend. This operation is analogous to “push n”.

Prepends the elements of other to self.

To insert one element to the front of the vector, use unshift.

This operation is also known as “prepend”.

Panics

Panics if the number of elements in the vector overflows a usize.

Creates a new array by repeating this array n times.

This function will not panic. If the resulting Array’s capacity would overflow, None is returned.

Set element at position index within the vector, extending the vector with nil if index is out of bounds.

Insert element at position start within the vector and remove the following drain elements. If start is out of bounds, the vector will be extended with nil.

This method sets a slice of the Array to a single element, including the zero-length slice. It is similar in intent to calling Vec::splice with a one-element iterator.

set_with_drain will only drain up to the end of the vector.

To set a single element without draining, use set.

Insert the elements from a slice at a position index in the vector, extending the vector with nil if index is out of bounds.

This method is similar to Vec::splice when called with a zero-length range.

Insert the elements from a slice at a position index in the vector and remove the following drain elements. The vector is extended with nil if index is out of bounds.

This method is similar to Vec::splice when called with a nonzero-length range.

When called with drain == 0, this method is equivalent to insert_slice.

If drain >= src.len() or the tail of the vector is replaced, this method is efficient. Otherwise, a temporary buffer is used to move the elements.

Trait Implementations

Safety Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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

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

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

Extends a collection with exactly one element.

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

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

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

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

Extends a collection with exactly one element.

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

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

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

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

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.