Struct smallvec::SmallVec

source · [−]
pub struct SmallVec<A: Array> { /* private fields */ }
Expand description

A Vec-like container that can store a small number of elements inline.

SmallVec acts like a vector, but can store a limited amount of data inline within the SmallVec struct rather than in a separate allocation. If the data exceeds this limit, the SmallVec will “spill” its data onto the heap, allocating a new buffer to hold it.

The amount of data that a SmallVec can store inline depends on its backing store. The backing store can be any type that implements the Array trait; usually it is a small fixed-sized array. For example a SmallVec<[u64; 8]> can hold up to eight 64-bit integers inline.

Example

use smallvec::SmallVec;
let mut v = SmallVec::<[u8; 4]>::new(); // initialize an empty vector

// The vector can hold up to 4 items without spilling onto the heap.
v.extend(0..4);
assert_eq!(v.len(), 4);
assert!(!v.spilled());

// Pushing another element will force the buffer to spill:
v.push(4);
assert_eq!(v.len(), 5);
assert!(v.spilled());

Implementations

Construct an empty vector

Construct an empty vector with enough capacity pre-allocated to store at least n elements.

Will create a heap allocation only if n is larger than the inline capacity.


let v: SmallVec<[u8; 3]> = SmallVec::with_capacity(100);

assert!(v.is_empty());
assert!(v.capacity() >= 100);

Construct a new SmallVec from a Vec<A::Item>.

Elements will be copied to the inline buffer if vec.capacity() <= Self::inline_capacity().

use smallvec::SmallVec;

let vec = vec![1, 2, 3, 4, 5];
let small_vec: SmallVec<[_; 3]> = SmallVec::from_vec(vec);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

Constructs a new SmallVec on the stack from an A without copying elements.

use smallvec::SmallVec;

let buf = [1, 2, 3, 4, 5];
let small_vec: SmallVec<_> = SmallVec::from_buf(buf);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

Constructs a new SmallVec on the stack from an A without copying elements. Also sets the length, which must be less or equal to the size of buf.

use smallvec::SmallVec;

let buf = [1, 2, 3, 4, 5, 0, 0, 0];
let small_vec: SmallVec<_> = SmallVec::from_buf_and_len(buf, 5);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

Constructs a new SmallVec on the stack from an A without copying elements. Also sets the length. The user is responsible for ensuring that len <= A::size().

use smallvec::SmallVec;
use std::mem::MaybeUninit;

let buf = [1, 2, 3, 4, 5, 0, 0, 0];
let small_vec: SmallVec<_> = unsafe {
    SmallVec::from_buf_and_len_unchecked(MaybeUninit::new(buf), 5)
};

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

Sets the length of a vector.

This will explicitly set the size of the vector, without actually modifying its buffers, so it is up to the caller to ensure that the vector is actually the specified size.

The maximum number of elements this vector can hold inline

The number of elements stored in the vector

Returns true if the vector is empty

The number of items the vector can hold without reallocating

Returns true if the data has spilled into a separate heap-allocated buffer.

Creates a draining iterator that removes the specified range in the vector and yields the removed items.

Note 1: The element range is removed even if the iterator is only partially consumed or not consumed at all.

Note 2: It is unspecified how many elements are removed from the vector if the Drain value is leaked.

Panics

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

Append an item to the vector.

Remove an item from the end of the vector and return it, or None if empty.

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

Example
let mut v0: SmallVec<[u8; 16]> = smallvec![1, 2, 3];
let mut v1: SmallVec<[u8; 32]> = smallvec![4, 5, 6];
v0.append(&mut v1);
assert_eq!(*v0, [1, 2, 3, 4, 5, 6]);
assert_eq!(*v1, []);

Re-allocate to set the capacity to max(new_cap, inline_size()).

Panics if new_cap is less than the vector’s length or if the capacity computation overflows usize.

Re-allocate to set the capacity to max(new_cap, inline_size()).

Panics if new_cap is less than the vector’s length

Reserve capacity for additional more elements to be inserted.

May reserve more space to avoid frequent reallocations.

Panics if the capacity computation overflows usize.

Reserve capacity for additional more elements to be inserted.

May reserve more space to avoid frequent reallocations.

Reserve the minimum capacity for additional more elements to be inserted.

Panics if the new capacity overflows usize.

Reserve the minimum capacity for additional more elements to be inserted.

Shrink the capacity of the vector as much as possible.

When possible, this will move data from an external heap buffer to the vector’s inline storage.

Shorten the vector, keeping the first len elements and dropping the rest.

If len is greater than or equal to the vector’s current length, this has no effect.

This does not re-allocate. If you want the vector’s capacity to shrink, call shrink_to_fit after truncating.

Extracts a slice containing the entire vector.

Equivalent to &s[..].

Extracts a mutable slice of the entire vector.

Equivalent to &mut s[..].

Remove the element at position index, replacing it with the last element.

This does not preserve ordering, but is O(1).

Panics if index is out of bounds.

Remove all elements from the vector.

Remove and return the element at position index, shifting all elements after it to the left.

Panics if index is out of bounds.

Insert an element at position index, shifting all elements after it to the right.

Panics if index is out of bounds.

Insert multiple elements at position index, shifting all following elements toward the back.

Convert a SmallVec to a Vec, without reallocating if the SmallVec has already spilled onto the heap.

Converts a SmallVec into a Box<[T]> without reallocating if the SmallVec has already spilled onto the heap.

Note that this will drop any excess capacity.

Convert the SmallVec into an A if possible. Otherwise return Err(Self).

This method returns Err(Self) if the SmallVec is too short (and the A contains uninitialized elements), or if the SmallVec is too long (and all the elements were spilled to the heap).

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place and preserves the order of the retained elements.

Removes consecutive duplicate elements.

Removes consecutive duplicate elements using the given equality relation.

Removes consecutive elements that map to the same key.

Resizes the SmallVec in-place so that len is equal to new_len.

If new_len is greater than len, the SmallVec is extended by the difference, with each additional slot filled with the result of calling the closure f. The return values from f

If new_len is less than len, the SmallVec is simply truncated.

This method uses a closure to create new values on every push. If you’d rather Clone a given value, use resize. If you want to use the Default trait to generate values, you can pass Default::default() as the second argument.

Added for std::vec::Vec compatibility (added in Rust 1.33.0)

let mut vec : SmallVec<[_; 4]> = smallvec![1, 2, 3];
vec.resize_with(5, Default::default);
assert_eq!(&*vec, &[1, 2, 3, 0, 0]);

let mut vec : SmallVec<[_; 4]> = smallvec![];
let mut p = 1;
vec.resize_with(4, || { p *= 2; p });
assert_eq!(&*vec, &[2, 4, 8, 16]);

Creates a SmallVec directly from the raw components of another SmallVec.

Safety

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

  • ptr needs to have been previously allocated via SmallVec for its spilled storage (at least, it’s highly likely to be incorrect if it wasn’t).
  • ptr’s A::Item type needs to be the same size and alignment that it was allocated with
  • 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.

Additionally, capacity must be greater than the amount of inline storage A has; that is, the new SmallVec must need to spill over into heap allocated storage. This condition is asserted against.

The ownership of ptr is effectively transferred to the SmallVec 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.

Examples
use std::mem;
use std::ptr;

fn main() {
    let mut v: SmallVec<[_; 1]> = smallvec![1, 2, 3];

    // Pull out the important parts of `v`.
    let p = v.as_mut_ptr();
    let len = v.len();
    let cap = v.capacity();
    let spilled = v.spilled();

    unsafe {
        // Forget all about `v`. The heap allocation that stored the
        // three values won't be deallocated.
        mem::forget(v);

        // Overwrite memory with [4, 5, 6].
        //
        // This is only safe if `spilled` is true! Otherwise, we are
        // writing into the old `SmallVec`'s inline storage on the
        // stack.
        assert!(spilled);
        for i in 0..len {
            ptr::write(p.add(i), 4 + i);
        }

        // Put everything back together into a SmallVec with a different
        // amount of inline storage, but which is still less than `cap`.
        let rebuilt = SmallVec::<[_; 2]>::from_raw_parts(p, len, cap);
        assert_eq!(&*rebuilt, &[4, 5, 6]);
    }
}

Returns a raw pointer to the vector’s buffer.

Returns a raw mutable pointer to the vector’s buffer.

Copy the elements from a slice into a new SmallVec.

For slices of Copy types, this is more efficient than SmallVec::from(slice).

Copy elements from a slice into the vector at position index, shifting any following elements toward the back.

For slices of Copy types, this is more efficient than insert.

Copy elements from a slice and append them to the vector.

For slices of Copy types, this is more efficient than extend.

Resizes the vector so that its length is equal to len.

If len is less than the current length, the vector simply truncated.

If len is greater than the current length, value is appended to the vector until its length equals len.

Creates a SmallVec with n copies of elem.

use smallvec::SmallVec;

let v = SmallVec::<[char; 128]>::from_elem('d', 2);
assert_eq!(v, SmallVec::from_buf(['d', 'd']));

Methods from Deref<Target = [A::Item]>

Returns the number of elements in the slice.

Examples
let a = [1, 2, 3];
assert_eq!(a.len(), 3);

Returns true if the slice has a length of 0.

Examples
let a = [1, 2, 3];
assert!(!a.is_empty());

Returns the first element of the slice, or None if it is empty.

Examples
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());

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

Examples
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

Returns the first and all the rest of the elements of the slice, or None if it is empty.

Examples
let x = &[0, 1, 2];

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

Returns the first and all the rest of the elements of the slice, or None if it is empty.

Examples
let x = &mut [0, 1, 2];

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

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

Examples
let x = &[0, 1, 2];

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

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

Examples
let x = &mut [0, 1, 2];

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

Returns the last element of the slice, or None if it is empty.

Examples
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());

Returns a mutable pointer to the last item in the slice.

Examples
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

Returns a reference to an element or subslice depending on the type of index.

  • If given a position, returns a reference to the element at that position or None if out of bounds.
  • If given a range, returns the subslice corresponding to that range, or None if out of bounds.
Examples
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));

Returns a mutable reference to an element or subslice depending on the type of index (see get) or None if the index is out of bounds.

Examples
let x = &mut [0, 1, 2];

if let Some(elem) = x.get_mut(1) {
    *elem = 42;
}
assert_eq!(x, &[0, 42, 2]);

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

For a safe alternative see get.

Safety

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

Examples
let x = &[1, 2, 4];

unsafe {
    assert_eq!(x.get_unchecked(1), &2);
}

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

For a safe alternative see get_mut.

Safety

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

Examples
let x = &mut [1, 2, 4];

unsafe {
    let elem = x.get_unchecked_mut(1);
    *elem = 13;
}
assert_eq!(x, &[1, 13, 4]);

Returns a raw pointer to the slice’s buffer.

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

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.

Modifying the container referenced by this slice may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Examples
let x = &[1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
    }
}

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

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

Modifying the container referenced by this slice may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Examples
let x = &mut [1, 2, 4];
let x_ptr = x.as_mut_ptr();

unsafe {
    for i in 0..x.len() {
        *x_ptr.add(i) += 2;
    }
}
assert_eq!(x, &[3, 4, 6]);

Returns the two raw pointers spanning the slice.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

See as_ptr for warnings on using these pointers. The end pointer requires extra caution, as it does not point to a valid element in the slice.

This function is useful for interacting with foreign interfaces which use two pointers to refer to a range of elements in memory, as is common in C++.

It can also be useful to check if a pointer to an element refers to an element of this slice:

let a = [1, 2, 3];
let x = &a[1] as *const _;
let y = &5 as *const _;

assert!(a.as_ptr_range().contains(&x));
assert!(!a.as_ptr_range().contains(&y));

Returns the two unsafe mutable pointers spanning the slice.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

See as_mut_ptr for warnings on using these pointers. The end pointer requires extra caution, as it does not point to a valid element in the slice.

This function is useful for interacting with foreign interfaces which use two pointers to refer to a range of elements in memory, as is common in C++.

Swaps two elements in the slice.

Arguments
  • a - The index of the first element
  • b - The index of the second element
Panics

Panics if a or b are out of bounds.

Examples
let mut v = ["a", "b", "c", "d", "e"];
v.swap(2, 4);
assert!(v == ["a", "b", "e", "d", "c"]);
🔬 This is a nightly-only experimental API. (slice_swap_unchecked)

Swaps two elements in the slice, without doing bounds checking.

For a safe alternative see swap.

Arguments
  • a - The index of the first element
  • b - The index of the second element
Safety

Calling this method with an out-of-bounds index is undefined behavior. The caller has to ensure that a < self.len() and b < self.len().

Examples
#![feature(slice_swap_unchecked)]

let mut v = ["a", "b", "c", "d"];
// SAFETY: we know that 1 and 3 are both indices of the slice
unsafe { v.swap_unchecked(1, 3) };
assert!(v == ["a", "d", "c", "b"]);

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

Examples
let mut v = [1, 2, 3];
v.reverse();
assert!(v == [3, 2, 1]);

Returns an iterator over the slice.

Examples
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);

Returns an iterator that allows modifying each value.

Examples
let x = &mut [1, 2, 4];
for elem in x.iter_mut() {
    *elem += 2;
}
assert_eq!(x, &[3, 4, 6]);

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

Panics

Panics if size is 0.

Examples
let slice = ['r', 'u', 's', 't'];
let mut iter = slice.windows(2);
assert_eq!(iter.next().unwrap(), &['r', 'u']);
assert_eq!(iter.next().unwrap(), &['u', 's']);
assert_eq!(iter.next().unwrap(), &['s', 't']);
assert!(iter.next().is_none());

If the slice is shorter than size:

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

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

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

Panics

Panics if chunk_size is 0.

Examples
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.chunks(2);
assert_eq!(iter.next().unwrap(), &['l', 'o']);
assert_eq!(iter.next().unwrap(), &['r', 'e']);
assert_eq!(iter.next().unwrap(), &['m']);
assert!(iter.next().is_none());

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

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

Panics

Panics if chunk_size is 0.

Examples
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

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

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

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

Panics

Panics if chunk_size is 0.

Examples
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.chunks_exact(2);
assert_eq!(iter.next().unwrap(), &['l', 'o']);
assert_eq!(iter.next().unwrap(), &['r', 'e']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['m']);

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

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

Panics

Panics if chunk_size is 0.

Examples
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.chunks_exact_mut(2) {
    for elem in chunk.iter_mut() {
        *elem += count;
    }
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 0]);
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, assuming that there’s no remainder.

Safety

This may only be called when

  • The slice splits exactly into N-element chunks (aka self.len() % N == 0).
  • N != 0.
Examples
#![feature(slice_as_chunks)]
let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &[[char; 1]] =
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
let chunks: &[[char; 3]] =
    // SAFETY: The slice length (6) is a multiple of 3
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);

// These would be unsound:
// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowed
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, starting at the beginning of the slice, and a remainder slice with length strictly less than N.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(slice_as_chunks)]
let slice = ['l', 'o', 'r', 'e', 'm'];
let (chunks, remainder) = slice.as_chunks();
assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
assert_eq!(remainder, &['m']);
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, starting at the end of the slice, and a remainder slice with length strictly less than N.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(slice_as_chunks)]
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
🔬 This is a nightly-only experimental API. (array_chunks)

Returns an iterator over N elements of the slice at a time, starting at the beginning of the slice.

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

This method is the const generic equivalent of chunks_exact.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(array_chunks)]
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.array_chunks();
assert_eq!(iter.next().unwrap(), &['l', 'o']);
assert_eq!(iter.next().unwrap(), &['r', 'e']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['m']);
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, assuming that there’s no remainder.

Safety

This may only be called when

  • The slice splits exactly into N-element chunks (aka self.len() % N == 0).
  • N != 0.
Examples
#![feature(slice_as_chunks)]
let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &mut [[char; 1]] =
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked_mut() };
chunks[0] = ['L'];
assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);
let chunks: &mut [[char; 3]] =
    // SAFETY: The slice length (6) is a multiple of 3
    unsafe { slice.as_chunks_unchecked_mut() };
chunks[1] = ['a', 'x', '?'];
assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']);

// These would be unsound:
// let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5
// let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowed
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, starting at the beginning of the slice, and a remainder slice with length strictly less than N.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(slice_as_chunks)]
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

let (chunks, remainder) = v.as_chunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 9]);
🔬 This is a nightly-only experimental API. (slice_as_chunks)

Splits the slice into a slice of N-element arrays, starting at the end of the slice, and a remainder slice with length strictly less than N.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(slice_as_chunks)]
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

let (remainder, chunks) = v.as_rchunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);
🔬 This is a nightly-only experimental API. (array_chunks)

Returns an iterator over N elements of the slice at a time, starting at the beginning of the slice.

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

This method is the const generic equivalent of chunks_exact_mut.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(array_chunks)]
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.array_chunks_mut() {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 0]);
🔬 This is a nightly-only experimental API. (array_windows)

Returns an iterator over overlapping windows of N elements of a slice, starting at the beginning of the slice.

This is the const generic equivalent of windows.

If N is greater than the size of the slice, it will return no windows.

Panics

Panics if N is 0. This check will most probably get changed to a compile time error before this method gets stabilized.

Examples
#![feature(array_windows)]
let slice = [0, 1, 2, 3];
let mut iter = slice.array_windows();
assert_eq!(iter.next().unwrap(), &[0, 1]);
assert_eq!(iter.next().unwrap(), &[1, 2]);
assert_eq!(iter.next().unwrap(), &[2, 3]);
assert!(iter.next().is_none());

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

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

Panics

Panics if chunk_size is 0.

Examples
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());

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

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

Panics

Panics if chunk_size is 0.

Examples
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

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

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

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

Panics

Panics if chunk_size is 0.

Examples
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks_exact(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['l']);

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

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

Panics

Panics if chunk_size is 0.

Examples
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.rchunks_exact_mut(2) {
    for elem in chunk.iter_mut() {
        *elem += count;
    }
    count += 1;
}
assert_eq!(v, &[0, 2, 2, 1, 1]);
🔬 This is a nightly-only experimental API. (slice_group_by)

Returns an iterator over the slice producing non-overlapping runs of elements using the predicate to separate them.

The predicate is called on two elements following themselves, it means the predicate is called on slice[0] and slice[1] then on slice[1] and slice[2] and so on.

Examples
#![feature(slice_group_by)]

let slice = &[1, 1, 1, 3, 3, 2, 2, 2];

let mut iter = slice.group_by(|a, b| a == b);

assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
assert_eq!(iter.next(), Some(&[3, 3][..]));
assert_eq!(iter.next(), Some(&[2, 2, 2][..]));
assert_eq!(iter.next(), None);

This method can be used to extract the sorted subslices:

#![feature(slice_group_by)]

let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4];

let mut iter = slice.group_by(|a, b| a <= b);

assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..]));
assert_eq!(iter.next(), Some(&[2, 3][..]));
assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
assert_eq!(iter.next(), None);
🔬 This is a nightly-only experimental API. (slice_group_by)

Returns an iterator over the slice producing non-overlapping mutable runs of elements using the predicate to separate them.

The predicate is called on two elements following themselves, it means the predicate is called on slice[0] and slice[1] then on slice[1] and slice[2] and so on.

Examples
#![feature(slice_group_by)]

let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2];

let mut iter = slice.group_by_mut(|a, b| a == b);

assert_eq!(iter.next(), Some(&mut [1, 1, 1][..]));
assert_eq!(iter.next(), Some(&mut [3, 3][..]));
assert_eq!(iter.next(), Some(&mut [2, 2, 2][..]));
assert_eq!(iter.next(), None);

This method can be used to extract the sorted subslices:

#![feature(slice_group_by)]

let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4];

let mut iter = slice.group_by_mut(|a, b| a <= b);

assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..]));
assert_eq!(iter.next(), Some(&mut [2, 3][..]));
assert_eq!(iter.next(), Some(&mut [2, 3, 4][..]));
assert_eq!(iter.next(), None);

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

Panics

Panics if mid > len.

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

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

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

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

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

Panics

Panics if mid > len.

Examples
let mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.split_at_mut(2);
assert_eq!(left, [1, 0]);
assert_eq!(right, [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
🔬 This is a nightly-only experimental API. (slice_split_at_unchecked)

Divides one slice into two at an index, without doing bounds checking.

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

For a safe alternative see split_at.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used. The caller has to ensure that 0 <= mid <= self.len().

Examples
#![feature(slice_split_at_unchecked)]

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

unsafe {
   let (left, right) = v.split_at_unchecked(0);
   assert_eq!(left, []);
   assert_eq!(right, [1, 2, 3, 4, 5, 6]);
}

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

unsafe {
    let (left, right) = v.split_at_unchecked(6);
    assert_eq!(left, [1, 2, 3, 4, 5, 6]);
    assert_eq!(right, []);
}
🔬 This is a nightly-only experimental API. (slice_split_at_unchecked)

Divides one mutable slice into two at an index, without doing bounds checking.

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

For a safe alternative see split_at_mut.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used. The caller has to ensure that 0 <= mid <= self.len().

Examples
#![feature(slice_split_at_unchecked)]

let mut v = [1, 0, 3, 0, 5, 6];
// scoped to restrict the lifetime of the borrows
unsafe {
    let (left, right) = v.split_at_mut_unchecked(2);
    assert_eq!(left, [1, 0]);
    assert_eq!(right, [3, 0, 5, 6]);
    left[1] = 2;
    right[1] = 4;
}
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
🔬 This is a nightly-only experimental API. (split_array)

Divides one slice into an array and a remainder slice at an index.

The array will contain all indices from [0, N) (excluding the index N itself) and the slice will contain all indices from [N, len) (excluding the index len itself).

Panics

Panics if N > len.

Examples
#![feature(split_array)]

let v = &[1, 2, 3, 4, 5, 6][..];

{
   let (left, right) = v.split_array_ref::<0>();
   assert_eq!(left, &[]);
   assert_eq!(right, [1, 2, 3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<2>();
    assert_eq!(left, &[1, 2]);
    assert_eq!(right, [3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<6>();
    assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
    assert_eq!(right, []);
}
🔬 This is a nightly-only experimental API. (split_array)

Divides one mutable slice into an array and a remainder slice at an index.

The array will contain all indices from [0, N) (excluding the index N itself) and the slice will contain all indices from [N, len) (excluding the index len itself).

Panics

Panics if N > len.

Examples
#![feature(split_array)]

let mut v = &mut [1, 0, 3, 0, 5, 6][..];
let (left, right) = v.split_array_mut::<2>();
assert_eq!(left, &mut [1, 0]);
assert_eq!(right, [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
🔬 This is a nightly-only experimental API. (split_array)

Divides one slice into an array and a remainder slice at an index from the end.

The slice will contain all indices from [0, len - N) (excluding the index len - N itself) and the array will contain all indices from [len - N, len) (excluding the index len itself).

Panics

Panics if N > len.

Examples
#![feature(split_array)]

let v = &[1, 2, 3, 4, 5, 6][..];

{
   let (left, right) = v.rsplit_array_ref::<0>();
   assert_eq!(left, [1, 2, 3, 4, 5, 6]);
   assert_eq!(right, &[]);
}

{
    let (left, right) = v.rsplit_array_ref::<2>();
    assert_eq!(left, [1, 2, 3, 4]);
    assert_eq!(right, &[5, 6]);
}

{
    let (left, right) = v.rsplit_array_ref::<6>();
    assert_eq!(left, []);
    assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}
🔬 This is a nightly-only experimental API. (split_array)

Divides one mutable slice into an array and a remainder slice at an index from the end.

The slice will contain all indices from [0, len - N) (excluding the index N itself) and the array will contain all indices from [len - N, len) (excluding the index len itself).

Panics

Panics if N > len.

Examples
#![feature(split_array)]

let mut v = &mut [1, 0, 3, 0, 5, 6][..];
let (left, right) = v.rsplit_array_mut::<4>();
assert_eq!(left, [1, 0]);
assert_eq!(right, &mut [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);

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

Examples
let slice = [10, 40, 33, 20];
let mut iter = slice.split(|num| num % 3 == 0);

assert_eq!(iter.next().unwrap(), &[10, 40]);
assert_eq!(iter.next().unwrap(), &[20]);
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:

let slice = [10, 40, 33];
let mut iter = slice.split(|num| num % 3 == 0);

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

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

let slice = [10, 6, 33, 20];
let mut iter = slice.split(|num| num % 3 == 0);

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

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

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

for group in v.split_mut(|num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(v, [1, 40, 30, 1, 60, 1]);

Returns an iterator over subslices separated by elements that match pred. The matched element is contained in the end of the previous subslice as a terminator.

Examples
let slice = [10, 40, 33, 20];
let mut iter = slice.split_inclusive(|num| num % 3 == 0);

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

If the last element of the slice is matched, that element will be considered the terminator of the preceding slice. That slice will be the last item returned by the iterator.

let slice = [3, 10, 40, 33];
let mut iter = slice.split_inclusive(|num| num % 3 == 0);

assert_eq!(iter.next().unwrap(), &[3]);
assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
assert!(iter.next().is_none());

Returns an iterator over mutable subslices separated by elements that match pred. The matched element is contained in the previous subslice as a terminator.

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

for group in v.split_inclusive_mut(|num| *num % 3 == 0) {
    let terminator_idx = group.len()-1;
    group[terminator_idx] = 1;
}
assert_eq!(v, [10, 40, 1, 20, 1, 1]);

Returns 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
let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
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.

let v = &[0, 1, 1, 2, 3, 5, 8];
let mut it = v.rsplit(|n| *n % 2 == 0);
assert_eq!(it.next().unwrap(), &[]);
assert_eq!(it.next().unwrap(), &[3, 5]);
assert_eq!(it.next().unwrap(), &[1, 1]);
assert_eq!(it.next().unwrap(), &[]);
assert_eq!(it.next(), None);

Returns 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
let mut v = [100, 400, 300, 200, 600, 500];

let mut count = 0;
for group in v.rsplit_mut(|num| *num % 3 == 0) {
    count += 1;
    group[0] = count;
}
assert_eq!(v, [3, 400, 300, 2, 600, 1]);

Returns 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 slice.

Examples

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

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

for group in v.splitn(2, |num| *num % 3 == 0) {
    println!("{:?}", group);
}

Returns 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 slice.

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

for group in v.splitn_mut(2, |num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(v, [1, 40, 30, 1, 60, 50]);

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

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

Examples

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

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

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{:?}", group);
}

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

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

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

for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(s, [1, 40, 30, 20, 60, 1]);

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

Examples
let v = [10, 40, 30];
assert!(v.contains(&30));
assert!(!v.contains(&50));

If you do not have a &T, but some other value that you can compare with one (for example, String implements PartialEq<str>), you can use iter().any:

let v = [String::from("hello"), String::from("world")]; // slice of `String`
assert!(v.iter().any(|e| e == "hello")); // search with `&str`
assert!(!v.iter().any(|e| e == "hi"));

Returns true if needle is a prefix of the slice.

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

Always returns true if needle is an empty slice:

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

Returns true if needle is a suffix of the slice.

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

Always returns true if needle is an empty slice:

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

Returns a subslice with the prefix removed.

If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some. If prefix is empty, simply returns the original slice.

If the slice does not start with prefix, returns None.

Examples
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));

Returns a subslice with the suffix removed.

If the slice ends with suffix, returns the subslice before the suffix, wrapped in Some. If suffix is empty, simply returns the original slice.

If the slice does not end with suffix, returns None.

Examples
let v = &[10, 40, 30];
assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
assert_eq!(v.strip_suffix(&[50]), None);
assert_eq!(v.strip_suffix(&[50, 30]), None);

Binary searches this sorted slice 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. The index is chosen deterministically, but is subject to change in future versions of Rust. 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.

See also binary_search_by, binary_search_by_key, and partition_point.

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

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

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

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

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

Binary searches this sorted slice 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. The index is chosen deterministically, but is subject to change in future versions of Rust. 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.

See also binary_search, binary_search_by_key, and partition_point.

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

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

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

Binary searches this sorted slice with a key extraction function.

Assumes that the slice 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. The index is chosen deterministically, but is subject to change in future versions of Rust. 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.

See also binary_search, binary_search_by, and partition_point.

Examples

Looks up a series of four elements in a slice of pairs sorted by their second 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].

let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
         (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
         (1, 21), (2, 34), (4, 55)];

assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b),  Ok(9));
assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b),   Err(7));
assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
let r = s.binary_search_by_key(&1, |&(a, b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });

Sorts the slice, but might 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
let mut v = [-5, 4, 1, -3, 2];

v.sort_unstable();
assert!(v == [-5, -3, 1, 2, 4]);

Sorts the slice with a comparator function, but might 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 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 >.

For example, while f64 doesn’t implement Ord because NaN != NaN, we can use partial_cmp as our sort function when we know the slice doesn’t contain a NaN.

let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
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
let mut v = [5, 4, 1, 3, 2];
v.sort_unstable_by(|a, b| a.cmp(b));
assert!(v == [1, 2, 3, 4, 5]);

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

Sorts the slice with a key extraction function, but might 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
let mut v = [-5i32, 4, 1, -3, 2];

v.sort_unstable_by_key(|k| k.abs());
assert!(v == [1, 2, -3, 4, -5]);
👎 Deprecated since 1.49.0:

use the select_nth_unstable() instead

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

Reorder the slice such that the element at index is at its final sorted position.

👎 Deprecated since 1.49.0:

use select_nth_unstable_by() instead

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

Reorder the slice with a comparator function such that the element at index is at its final sorted position.

👎 Deprecated since 1.49.0:

use the select_nth_unstable_by_key() instead

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

Reorder the slice with a key extraction function such that the element at index is at its final sorted position.

Reorder the slice such that the element at index is at its final sorted position.

This reordering has the additional property that any value at position i < index will be less than or equal to any value at a position j > index. Additionally, this reordering is unstable (i.e. any number of equal elements may end up at position index), in-place (i.e. does not allocate), and O(n) worst-case. This function is also/ known as “kth element” in other libraries. It returns a triplet of the following values: all elements less than the one at the given index, the value at the given index, and all elements greater than the one at the given index.

Current implementation

The current algorithm is based on the quickselect portion of the same quicksort algorithm used for sort_unstable.

Panics

Panics when index >= len(), meaning it always panics on empty slices.

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

// Find the median
v.select_nth_unstable(2);

// We are only guaranteed the slice will be one of the following, based on the way we sort
// about the specified index.
assert!(v == [-3, -5, 1, 2, 4] ||
        v == [-5, -3, 1, 2, 4] ||
        v == [-3, -5, 1, 4, 2] ||
        v == [-5, -3, 1, 4, 2]);

Reorder the slice with a comparator function such that the element at index is at its final sorted position.

This reordering has the additional property that any value at position i < index will be less than or equal to any value at a position j > index using the comparator function. Additionally, this reordering is unstable (i.e. any number of equal elements may end up at position index), in-place (i.e. does not allocate), and O(n) worst-case. This function is also known as “kth element” in other libraries. It returns a triplet of the following values: all elements less than the one at the given index, the value at the given index, and all elements greater than the one at the given index, using the provided comparator function.

Current implementation

The current algorithm is based on the quickselect portion of the same quicksort algorithm used for sort_unstable.

Panics

Panics when index >= len(), meaning it always panics on empty slices.

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

// Find the median as if the slice were sorted in descending order.
v.select_nth_unstable_by(2, |a, b| b.cmp(a));

// We are only guaranteed the slice will be one of the following, based on the way we sort
// about the specified index.
assert!(v == [2, 4, 1, -5, -3] ||
        v == [2, 4, 1, -3, -5] ||
        v == [4, 2, 1, -5, -3] ||
        v == [4, 2, 1, -3, -5]);

Reorder the slice with a key extraction function such that the element at index is at its final sorted position.

This reordering has the additional property that any value at position i < index will be less than or equal to any value at a position j > index using the key extraction function. Additionally, this reordering is unstable (i.e. any number of equal elements may end up at position index), in-place (i.e. does not allocate), and O(n) worst-case. This function is also known as “kth element” in other libraries. It returns a triplet of the following values: all elements less than the one at the given index, the value at the given index, and all elements greater than the one at the given index, using the provided key extraction function.

Current implementation

The current algorithm is based on the quickselect portion of the same quicksort algorithm used for sort_unstable.

Panics

Panics when index >= len(), meaning it always panics on empty slices.

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

// Return the median as if the array were sorted according to absolute value.
v.select_nth_unstable_by_key(2, |a| a.abs());

// We are only guaranteed the slice will be one of the following, based on the way we sort
// about the specified index.
assert!(v == [1, 2, -3, 4, -5] ||
        v == [1, 2, -3, -5, 4] ||
        v == [2, 1, -3, 4, -5] ||
        v == [2, 1, -3, -5, 4]);
🔬 This is a nightly-only experimental API. (slice_partition_dedup)

Moves all consecutive repeated elements to the end of the slice according to the PartialEq trait implementation.

Returns two slices. The first contains no consecutive repeated elements. The second contains all the duplicates in no specified order.

If the slice is sorted, the first returned slice contains no duplicates.

Examples
#![feature(slice_partition_dedup)]

let mut slice = [1, 2, 2, 3, 3, 2, 1, 1];

let (dedup, duplicates) = slice.partition_dedup();

assert_eq!(dedup, [1, 2, 3, 2, 1]);
assert_eq!(duplicates, [2, 3, 1]);
🔬 This is a nightly-only experimental API. (slice_partition_dedup)

Moves all but the first of consecutive elements to the end of the slice satisfying a given equality relation.

Returns two slices. The first contains no consecutive repeated elements. The second contains all the duplicates in no specified order.

The same_bucket function is passed references to two elements from the slice 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 moved at the end of the slice.

If the slice is sorted, the first returned slice contains no duplicates.

Examples
#![feature(slice_partition_dedup)]

let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];

let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));

assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);
🔬 This is a nightly-only experimental API. (slice_partition_dedup)

Moves all but the first of consecutive elements to the end of the slice that resolve to the same key.

Returns two slices. The first contains no consecutive repeated elements. The second contains all the duplicates in no specified order.

If the slice is sorted, the first returned slice contains no duplicates.

Examples
#![feature(slice_partition_dedup)]

let mut slice = [10, 20, 21, 30, 30, 20, 11, 13];

let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10);

assert_eq!(dedup, [10, 20, 30, 20, 11]);
assert_eq!(duplicates, [21, 30, 13]);

Rotates the slice in-place such that the first mid elements of the slice move to the end while the last self.len() - mid elements move to the front. After calling rotate_left, the element previously at index mid will become the first element in the slice.

Panics

This function will panic if mid is greater than the length of the slice. Note that mid == self.len() does not panic and is a no-op rotation.

Complexity

Takes linear (in self.len()) time.

Examples
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
a.rotate_left(2);
assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);

Rotating a subslice:

let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
a[1..5].rotate_left(1);
assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']);

Rotates the slice in-place such that the first self.len() - k elements of the slice move to the end while the last k elements move to the front. After calling rotate_right, the element previously at index self.len() - k will become the first element in the slice.

Panics

This function will panic if k is greater than the length of the slice. Note that k == self.len() does not panic and is a no-op rotation.

Complexity

Takes linear (in self.len()) time.

Examples
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
a.rotate_right(2);
assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);

Rotate a subslice:

let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
a[1..5].rotate_right(1);
assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);

Fills self with elements by cloning value.

Examples
let mut buf = vec![0; 10];
buf.fill(1);
assert_eq!(buf, vec![1; 10]);

Fills self with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Examples
let mut buf = vec![1; 10];
buf.fill_with(Default::default);
assert_eq!(buf, vec![0; 10]);

Copies the elements from src into self.

The length of src must be the same as self.

Panics

This function will panic if the two slices have different lengths.

Examples

Cloning two elements from a slice into another:

let src = [1, 2, 3, 4];
let mut dst = [0, 0];

// Because the slices have to be the same length,
// we slice the source slice from four elements
// to two. It will panic if we don't do this.
dst.clone_from_slice(&src[2..]);

assert_eq!(src, [1, 2, 3, 4]);
assert_eq!(dst, [3, 4]);

Rust enforces that there can only be one mutable reference with no immutable references to a particular piece of data in a particular scope. Because of this, attempting to use clone_from_slice on a single slice will result in a compile failure:

ⓘ
let mut slice = [1, 2, 3, 4, 5];

slice[..2].clone_from_slice(&slice[3..]); // compile fail!

To work around this, we can use split_at_mut to create two distinct sub-slices from a slice:

let mut slice = [1, 2, 3, 4, 5];

{
    let (left, right) = slice.split_at_mut(2);
    left.clone_from_slice(&right[1..]);
}

assert_eq!(slice, [4, 5, 3, 4, 5]);

Copies all elements from src into self, using a memcpy.

The length of src must be the same as self.

If T does not implement Copy, use clone_from_slice.

Panics

This function will panic if the two slices have different lengths.

Examples

Copying two elements from a slice into another:

let src = [1, 2, 3, 4];
let mut dst = [0, 0];

// Because the slices have to be the same length,
// we slice the source slice from four elements
// to two. It will panic if we don't do this.
dst.copy_from_slice(&src[2..]);

assert_eq!(src, [1, 2, 3, 4]);
assert_eq!(dst, [3, 4]);

Rust enforces that there can only be one mutable reference with no immutable references to a particular piece of data in a particular scope. Because of this, attempting to use copy_from_slice on a single slice will result in a compile failure:

ⓘ
let mut slice = [1, 2, 3, 4, 5];

slice[..2].copy_from_slice(&slice[3..]); // compile fail!

To work around this, we can use split_at_mut to create two distinct sub-slices from a slice:

let mut slice = [1, 2, 3, 4, 5];

{
    let (left, right) = slice.split_at_mut(2);
    left.copy_from_slice(&right[1..]);
}

assert_eq!(slice, [4, 5, 3, 4, 5]);

Copies elements from one part of the slice to another part of itself, using a memmove.

src is the range within self to copy from. dest is the starting index of the range within self to copy to, which will have the same length as src. The two ranges may overlap. The ends of the two ranges must be less than or equal to self.len().

Panics

This function will panic if either range exceeds the end of the slice, or if the end of src is before the start.

Examples

Copying four bytes within a slice:

let mut bytes = *b"Hello, World!";

bytes.copy_within(1..5, 8);

assert_eq!(&bytes, b"Hello, Wello!");

Swaps all elements in self with those in other.

The length of other must be the same as self.

Panics

This function will panic if the two slices have different lengths.

Example

Swapping two elements across slices:

let mut slice1 = [0, 0];
let mut slice2 = [1, 2, 3, 4];

slice1.swap_with_slice(&mut slice2[2..]);

assert_eq!(slice1, [3, 4]);
assert_eq!(slice2, [1, 2, 0, 0]);

Rust enforces that there can only be one mutable reference to a particular piece of data in a particular scope. Because of this, attempting to use swap_with_slice on a single slice will result in a compile failure:

ⓘ
let mut slice = [1, 2, 3, 4, 5];
slice[..2].swap_with_slice(&mut slice[3..]); // compile fail!

To work around this, we can use split_at_mut to create two distinct mutable sub-slices from a slice:

let mut slice = [1, 2, 3, 4, 5];

{
    let (left, right) = slice.split_at_mut(2);
    left.swap_with_slice(&mut right[1..]);
}

assert_eq!(slice, [4, 5, 3, 1, 2]);

Transmute the slice to a slice of another type, ensuring alignment of the types is maintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middle slice of a new type, and the suffix slice. The method may make the middle slice the greatest length possible for a given type and input slice, but only your algorithm’s performance should depend on that, not its correctness. It is permissible for all of the input data to be returned as the prefix or suffix slice.

This method has no purpose when either input element T or output element U are zero-sized and will return the original slice without splitting anything.

Safety

This method is essentially a transmute with respect to the elements in the returned middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.

Examples

Basic usage:

unsafe {
    let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
    let (prefix, shorts, suffix) = bytes.align_to::<u16>();
    // less_efficient_algorithm_for_bytes(prefix);
    // more_efficient_algorithm_for_aligned_shorts(shorts);
    // less_efficient_algorithm_for_bytes(suffix);
}

Transmute the slice to a slice of another type, ensuring alignment of the types is maintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middle slice of a new type, and the suffix slice. The method may make the middle slice the greatest length possible for a given type and input slice, but only your algorithm’s performance should depend on that, not its correctness. It is permissible for all of the input data to be returned as the prefix or suffix slice.

This method has no purpose when either input element T or output element U are zero-sized and will return the original slice without splitting anything.

Safety

This method is essentially a transmute with respect to the elements in the returned middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.

Examples

Basic usage:

unsafe {
    let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
    let (prefix, shorts, suffix) = bytes.align_to_mut::<u16>();
    // less_efficient_algorithm_for_bytes(prefix);
    // more_efficient_algorithm_for_aligned_shorts(shorts);
    // less_efficient_algorithm_for_bytes(suffix);
}
🔬 This is a nightly-only experimental API. (portable_simd)

Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.

This is a safe wrapper around slice::align_to, so has the same weak postconditions as that method. You’re only assured that self.len() == prefix.len() + middle.len() * LANES + suffix.len().

Notably, all of the following are possible:

  • prefix.len() >= LANES.
  • middle.is_empty() despite self.len() >= 3 * LANES.
  • suffix.len() >= LANES.

That said, this is a safe method, so if you’re only writing safe code, then this can at most cause incorrect logic, not unsoundness.

Panics

This will panic if the size of the SIMD type is different from LANES times that of the scalar.

At the time of writing, the trait restrictions on Simd<T, LANES> keeps that from ever happening, as only power-of-two numbers of lanes are supported. It’s possible that, in the future, those restrictions might be lifted in a way that would make it possible to see panics from this method for something like LANES == 3.

Examples
#![feature(portable_simd)]

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    use std::simd::f32x4;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.horizontal_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);
🔬 This is a nightly-only experimental API. (portable_simd)

Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.

This is a safe wrapper around slice::align_to_mut, so has the same weak postconditions as that method. You’re only assured that self.len() == prefix.len() + middle.len() * LANES + suffix.len().

Notably, all of the following are possible:

  • prefix.len() >= LANES.
  • middle.is_empty() despite self.len() >= 3 * LANES.
  • suffix.len() >= LANES.

That said, this is a safe method, so if you’re only writing safe code, then this can at most cause incorrect logic, not unsoundness.

This is the mutable version of slice::as_simd; see that for examples.

Panics

This will panic if the size of the SIMD type is different from LANES times that of the scalar.

At the time of writing, the trait restrictions on Simd<T, LANES> keeps that from ever happening, as only power-of-two numbers of lanes are supported. It’s possible that, in the future, those restrictions might be lifted in a way that would make it possible to see panics from this method for something like LANES == 3.

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

Checks if the elements of this slice are sorted.

That is, for each element a and its following element b, a <= b must hold. If the slice yields exactly zero or one element, true is returned.

Note that if Self::Item is only PartialOrd, but not Ord, the above definition implies that this function returns false if any two consecutive items are not comparable.

Examples
#![feature(is_sorted)]
let empty: [i32; 0] = [];

assert!([1, 2, 2, 9].is_sorted());
assert!(![1, 3, 2, 4].is_sorted());
assert!([0].is_sorted());
assert!(empty.is_sorted());
assert!(![0.0, 1.0, f32::NAN].is_sorted());
🔬 This is a nightly-only experimental API. (is_sorted)

Checks if the elements of this slice are sorted using the given comparator function.

Instead of using PartialOrd::partial_cmp, this function uses the given compare function to determine the ordering of two elements. Apart from that, it’s equivalent to is_sorted; see its documentation for more information.

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

Checks if the elements of this slice are sorted using the given key extraction function.

Instead of comparing the slice’s elements directly, this function compares the keys of the elements, as determined by f. Apart from that, it’s equivalent to is_sorted; see its documentation for more information.

Examples
#![feature(is_sorted)]

assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));

Returns the index of the partition point according to the given predicate (the index of the first element of the second partition).

The slice is assumed to be partitioned according to the given predicate. This means that all elements for which the predicate returns true are at the start of the slice and all elements for which the predicate returns false are at the end. For example, [7, 15, 3, 5, 4, 12, 6] is a partitioned under the predicate x % 2 != 0 (all odd numbers are at the start, all even at the end).

If this slice is not partitioned, the returned result is unspecified and meaningless, as this method performs a kind of binary search.

See also binary_search, binary_search_by, and binary_search_by_key.

Examples
let v = [1, 2, 3, 3, 5, 6, 7];
let i = v.partition_point(|&x| x < 5);

assert_eq!(i, 4);
assert!(v[..i].iter().all(|&x| x < 5));
assert!(v[i..].iter().all(|&x| !(x < 5)));
🔬 This is a nightly-only experimental API. (slice_take)

Removes the subslice corresponding to the given range and returns a reference to it.

Returns None and does not modify the slice if the given range is out of bounds.

Note that this method only accepts one-sided ranges such as 2.. or ..6, but not 2..6.

Examples

Taking the first three elements of a slice:

#![feature(slice_take)]

let mut slice: &[_] = &['a', 'b', 'c', 'd'];
let mut first_three = slice.take(..3).unwrap();

assert_eq!(slice, &['d']);
assert_eq!(first_three, &['a', 'b', 'c']);

Taking the last two elements of a slice:

#![feature(slice_take)]

let mut slice: &[_] = &['a', 'b', 'c', 'd'];
let mut tail = slice.take(2..).unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(tail, &['c', 'd']);

Getting None when range is out of bounds:

#![feature(slice_take)]

let mut slice: &[_] = &['a', 'b', 'c', 'd'];

assert_eq!(None, slice.take(5..));
assert_eq!(None, slice.take(..5));
assert_eq!(None, slice.take(..=4));
let expected: &[char] = &['a', 'b', 'c', 'd'];
assert_eq!(Some(expected), slice.take(..4));
🔬 This is a nightly-only experimental API. (slice_take)

Removes the subslice corresponding to the given range and returns a mutable reference to it.

Returns None and does not modify the slice if the given range is out of bounds.

Note that this method only accepts one-sided ranges such as 2.. or ..6, but not 2..6.

Examples

Taking the first three elements of a slice:

#![feature(slice_take)]

let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
let mut first_three = slice.take_mut(..3).unwrap();

assert_eq!(slice, &mut ['d']);
assert_eq!(first_three, &mut ['a', 'b', 'c']);

Taking the last two elements of a slice:

#![feature(slice_take)]

let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
let mut tail = slice.take_mut(2..).unwrap();

assert_eq!(slice, &mut ['a', 'b']);
assert_eq!(tail, &mut ['c', 'd']);

Getting None when range is out of bounds:

#![feature(slice_take)]

let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];

assert_eq!(None, slice.take_mut(5..));
assert_eq!(None, slice.take_mut(..5));
assert_eq!(None, slice.take_mut(..=4));
let expected: &mut [_] = &mut ['a', 'b', 'c', 'd'];
assert_eq!(Some(expected), slice.take_mut(..4));
🔬 This is a nightly-only experimental API. (slice_take)

Removes the first element of the slice and returns a reference to it.

Returns None if the slice is empty.

Examples
#![feature(slice_take)]

let mut slice: &[_] = &['a', 'b', 'c'];
let first = slice.take_first().unwrap();

assert_eq!(slice, &['b', 'c']);
assert_eq!(first, &'a');
🔬 This is a nightly-only experimental API. (slice_take)

Removes the first element of the slice and returns a mutable reference to it.

Returns None if the slice is empty.

Examples
#![feature(slice_take)]

let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
let first = slice.take_first_mut().unwrap();
*first = 'd';

assert_eq!(slice, &['b', 'c']);
assert_eq!(first, &'d');
🔬 This is a nightly-only experimental API. (slice_take)

Removes the last element of the slice and returns a reference to it.

Returns None if the slice is empty.

Examples
#![feature(slice_take)]

let mut slice: &[_] = &['a', 'b', 'c'];
let last = slice.take_last().unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(last, &'c');
🔬 This is a nightly-only experimental API. (slice_take)

Removes the last element of the slice and returns a mutable reference to it.

Returns None if the slice is empty.

Examples
#![feature(slice_take)]

let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
let last = slice.take_last_mut().unwrap();
*last = 'd';

assert_eq!(slice, &['a', 'b']);
assert_eq!(last, &'d');

Checks if all bytes in this slice are within the ASCII range.

Checks that two slices are an ASCII case-insensitive match.

Same as to_ascii_lowercase(a) == to_ascii_lowercase(b), but without allocating and copying temporaries.

Converts this slice to its ASCII upper case equivalent in-place.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.

To return a new uppercased value without modifying the existing one, use to_ascii_uppercase.

Converts this slice to its ASCII lower case equivalent in-place.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.

To return a new lowercased value without modifying the existing one, use to_ascii_lowercase.

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

Returns an iterator that produces an escaped version of this slice, treating it as an ASCII string.

Examples
#![feature(inherent_ascii_escape)]

let s = b"0\t\r\n'\"\\\x9d";
let escaped = s.escape_ascii().to_string();
assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");

Sorts the slice.

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
let mut v = [-5, 4, 1, -3, 2];

v.sort();
assert!(v == [-5, -3, 1, 2, 4]);

Sorts the slice 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 >.

For example, while f64 doesn’t implement Ord because NaN != NaN, we can use partial_cmp as our sort function when we know the slice doesn’t contain a NaN.

let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);

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
let mut v = [5, 4, 1, 3, 2];
v.sort_by(|a, b| a.cmp(b));
assert!(v == [1, 2, 3, 4, 5]);

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

Sorts the slice 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
let mut v = [-5i32, 4, 1, -3, 2];

v.sort_by_key(|k| k.abs());
assert!(v == [1, 2, -3, 4, -5]);

Sorts the slice with a key extraction function.

During sorting, the key function is called at most once per element, by using temporary storage to remember the results of key evaluation. The order of calls to the key function is unspecified and may change in future versions of the standard library.

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

For simple key functions (e.g., functions that are property accesses or basic operations), sort_by_key is likely to be faster.

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.

In the worst case, the algorithm allocates temporary storage in a Vec<(K, usize)> the length of the slice.

Examples
let mut v = [-5i32, 4, 32, -3, 2];

v.sort_by_cached_key(|k| k.to_string());
assert!(v == [-3, -5, 2, 32, 4]);

Copies self into a new Vec.

Examples
let s = [10, 40, 30];
let x = s.to_vec();
// Here, `s` and `x` can be modified independently.
🔬 This is a nightly-only experimental API. (allocator_api)

Copies self into a new Vec with an allocator.

Examples
#![feature(allocator_api)]

use std::alloc::System;

let s = [10, 40, 30];
let x = s.to_vec_in(System);
// Here, `s` and `x` can be modified independently.

Creates a vector by repeating a slice n times.

Panics

This function will panic if the capacity would overflow.

Examples

Basic usage:

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

A panic upon overflow:

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

Flattens a slice of T into a single value Self::Output.

Examples
assert_eq!(["hello", "world"].concat(), "helloworld");
assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);

Flattens a slice of T into a single value Self::Output, placing a given separator between each.

Examples
assert_eq!(["hello", "world"].join(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);
👎 Deprecated since 1.3.0:

renamed to join

Flattens a slice of T into a single value Self::Output, placing a given separator between each.

Examples
assert_eq!(["hello", "world"].connect(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);

Returns a vector containing a copy of this slice where each byte is mapped to its ASCII upper case equivalent.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.

To uppercase the value in-place, use make_ascii_uppercase.

Returns a vector containing a copy of this slice where each byte is mapped to its ASCII lower case equivalent.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.

To lowercase the value in-place, use make_ascii_lowercase.

Trait Implementations

Performs the conversion.

Performs the conversion.

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. 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

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Executes the destructor for this 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

Performs the conversion.

Performs the conversion.

Performs the conversion.

Creates a value from an iterator. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

Performs the mutable indexing (container[index]) operation. Read more

Which kind of iterator are we turning this into?

The type of the elements being iterated over.

Creates an iterator from a value. Read more

Which kind of iterator are we turning this into?

The type of the elements being iterated over.

Creates an iterator from a value. Read more

Which kind of iterator are we turning this into?

The type of the elements being iterated over.

Creates an iterator from a value. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

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

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

This method tests greater than or equal to (for self and other) and is used by the >= operator. 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

Performs the conversion.

Performs the conversion.

Performs the conversion.

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.