Vec does not currently guarantee the order in which elements are dropped. The order has changed in the past and may change again.

Vec will not specifically overwrite any data that is removed from it, but also won't specifically preserve it. Its uninitialized memory is scratch space that it may use however it wants. It will generally just do whatever is most efficient or otherwise easy to implement. Do not rely on removed data to be erased for security purposes. Even if you drop a Vec , its buffer may simply be reused by another Vec . Even if you zero a Vec 's memory first, that may not actually happen because the optimizer does not consider this a side-effect that must be preserved. There is one case which we will not break, however: using unsafe code to write to the excess capacity, and then increasing the length to match, is always valid.

vec![x; n] , vec![a, b, c, d] , and Vec::with_capacity(n) , will all produce a Vec with exactly the requested capacity. If len == capacity , (as is the case for the vec! macro), then a Vec<T> can be converted to and from a Box<[T]> without reallocating or moving the elements.

Vec does not guarantee any particular growth strategy when reallocating when full, nor when reserve is called. The current strategy is basic and it may prove desirable to use a non-constant growth factor. Whatever strategy is used will of course guarantee O(1) amortized push .

push and insert will never (re)allocate if the reported capacity is sufficient. push and insert will (re)allocate if len == capacity . That is, the reported capacity is completely accurate, and can be relied on. It can even be used to manually free the memory allocated by a Vec if desired. Bulk insertion methods may reallocate, even when not necessary.

Vec will never automatically shrink itself, even if completely empty. This ensures no unnecessary allocations or deallocations occur. Emptying a Vec and then filling it back up to the same len should incur no calls to the allocator. If you wish to free up unused memory, use shrink_to_fit .

It would penalize the general case, incurring an additional branch on every access.

It would make it more difficult for unsafe code to correctly manipulate a Vec . The contents of a Vec wouldn't have a stable address if it were only moved, and it would be more difficult to determine if a Vec had actually allocated memory.

Vec will never perform a "small optimization" where elements are actually stored on the stack for two reasons:

If a Vec has allocated memory, then the memory it points to is on the heap (as defined by the allocator Rust is configured to use by default), and its pointer points to len initialized, contiguous elements in order (what you would see if you coerced it to a slice), followed by capacity - len logically uninitialized, contiguous elements.

However, the pointer may not actually point to allocated memory. In particular, if you construct a Vec with capacity 0 via Vec::new , vec![] , Vec::with_capacity(0) , or by calling shrink_to_fit on an empty Vec, it will not allocate memory. Similarly, if you store zero-sized types inside a Vec , it will not allocate space for them. Note that in this case the Vec may not report a capacity of 0. Vec will allocate if and only if mem::size_of::<T> () * capacity() > 0 . In general, Vec 's allocation details are very subtle — if you intend to allocate memory using a Vec and use it for something else (either to pass to unsafe code, or to build your own memory-backed collection), be sure to deallocate this memory by using from_raw_parts to recover the Vec and then dropping it.

Most fundamentally, Vec is and always will be a (pointer, capacity, length) triplet. No more, no less. The order of these fields is completely unspecified, and you should use the appropriate methods to modify these. The pointer will never be null, so this type is null-pointer-optimized.

Due to its incredibly fundamental nature, Vec makes a lot of guarantees about its design. This ensures that it's as low-overhead as possible in the general case, and can be correctly manipulated in primitive ways by unsafe code. Note that these guarantees refer to an unqualified Vec<T> . If additional type parameters are added (e.g., to support custom allocators), overriding their defaults may change the behavior.

For example, a vector with capacity 10 and length 0 would be an empty vector with space for 10 more elements. Pushing 10 or fewer elements onto the vector will not change its capacity or cause reallocation to occur. However, if the vector's length is increased to 11, it will have to reallocate, which can be slow. For this reason, it is recommended to use Vec::with_capacity whenever possible to specify how big the vector is expected to get.

The capacity of a vector is the amount of space allocated for any future elements that will be added onto the vector. This is not to be confused with the length of a vector, which specifies the number of actual elements within the vector. If a vector's length exceeds its capacity, its capacity will automatically be increased, but its elements will have to be reallocated.

In Rust, it's more common to pass slices as arguments rather than vectors when you just want to provide read access. The same goes for String and &str .

A Vec can be mutable. Slices, on the other hand, are read-only objects. To get a slice, use & . Example:

Use get and get_mut if you want to check whether the index is in the Vec .

However be careful: if you try to access an index which isn't in the Vec , your software will panic! You cannot do this:

The Vec type allows to access values by index, because it implements the Index trait. An example will be more explicit:

It can also initialize each element of a Vec<T> with a given value. This may be more efficient than performing allocation and initialization in separate steps, especially when initializing a vector of zeros:

The vec! macro is provided to make initialization more convenient:

This function is mainly useful for data that lives for the remainder of the program's life. Dropping the returned reference will cause a memory leak.

This function is similar to the leak function on Box .

Consumes and leaks the Vec , returning a mutable reference to the contents, &'a mut [T] . Note that the type T must outlive the chosen lifetime 'a . If the type has only static references, or none at all, then this may be chosen to be 'static .

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.

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

If new_len is greater than len , the Vec is extended by the difference, with each additional slot filled with the result of calling the closure f . The return values from f will end up in the Vec in the order they have been generated.

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

Returns a newly allocated vector containing the elements in the range [at, len) . After the call, the original vector will be left containing the elements [0, at) with its previous capacity unchanged.

Splits the collection into two at the given index.

#[must_use = "use `.truncate()` if you don't need the other half"]

Returns true if the vector contains no elements.

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

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

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

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

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

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

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

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

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

Appends an element to the back of a collection.

If the vector is sorted, this removes all duplicates.

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

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

If the vector is sorted, this removes all duplicates.

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

The exact order may be useful for tracking external state, like an index.

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

Retains only the elements specified by the predicate.

Panics if index is out of bounds.

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

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

Panics if index is out of bounds.

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

The removed element is replaced by the last element of the vector.

Removes an element from the vector and returns it.

Normally, here, one would use clear instead to correctly drop the contents and thus not leak memory.

While the following example is sound, there is a memory leak since the inner vectors were not freed prior to the set_len call:

This method can be useful for situations in which the vector is serving as a buffer for other code, particularly over FFI:

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a vector is done using one of the safe operations instead, such as truncate , resize , extend , or clear .

Forces the length of the vector to new_len .

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 .

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.

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

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

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

The drain method can emulate truncate , but causes the excess elements to be returned instead of dropped.

If len is greater than the vector's current length, this has no effect.

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

Note that this will drop any excess capacity.

Panics if the current capacity is smaller than the supplied minimum capacity.

The capacity will remain at least as large as both the length and the supplied value.

Shrinks the capacity of the vector with a lower bound.

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.

Shrinks the capacity of the vector as much as possible.

If the capacity overflows, or the allocator reports a failure, then an error is returned.

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

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

If the capacity overflows, or the allocator reports a failure, then an error is returned.

Tries to reserve capacity for at least additional more elements to be inserted in the given Vec<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.

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

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

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

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

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

Violating these may cause problems like corrupting the allocator's internal data structures. For example it is not safe to build a Vec<u8> from a pointer to a C char array with length size_t . It's also not safe to build one from a Vec<u16> and its length, because the allocator cares about the alignment, and these two types have different alignments. The buffer was allocated with alignment 2 (for u16 ), but after turning it into a Vec<u8> it'll be deallocated with alignment 1.

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

Creates a Vec<T> directly from the raw components of another vector.

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

Returns the raw pointer to the underlying data, the length of the vector (in elements), and the allocated capacity of the data (in elements). These are the same arguments in the same order as the arguments to from_raw_parts .

It is important to note that although the returned vector has the capacity specified, the vector will have a zero length. For an explanation of the difference between length and capacity, see Capacity and reallocation .

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

Constructs a new, empty Vec<T> with the specified capacity.

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

Note that this function is same as extend except that it is specialized to work with slices instead. If and when Rust gets specialization this function will likely be deprecated (but still available).

Iterates over the slice other , clones each element, and then appends it to this Vec . The other vector is traversed in-order.

Clones and appends all elements in a slice to the Vec .

This method requires T to implement Clone , in order to be able to clone the passed value. If you need more flexibility (or want to rely on Default instead of Clone ), use resize_with .

If new_len is greater than len , the Vec is extended by the difference, with each additional slot filled with value . If new_len is less than len , the Vec is simply truncated.

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

This method uses Default to create new values on every push. If you'd rather Clone a given value, use resize .

If new_len is greater than len , the Vec is extended by the difference, with each additional slot filled with Default::default() . If new_len is less than len , the Vec is simply truncated.

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

This is moving towards being removed in favor of .resize_with(Default::default) . If you disagree, please comment in the tracking issue.

If the vector is sorted, this removes all duplicates.

Removes consecutive repeated elements in the vector according to the PartialEq trait implementation.

This method will be removed soon.

Removes the first instance of item from the vector if the item exists.

Removing the first item equal to a needle is already easily possible with iterators and the current Vec methods. Furthermore, having a method for one particular case of removal (linear search, only the first item, no swap remove) but not for others is inconsistent. This method will be removed soon.

Splitting an array into evens and odds, reusing the original allocation:

Note that drain_filter also lets you mutate every element in the filter closure, regardless of whether you choose to keep or remove it.

But drain_filter is easier to use. drain_filter is also more efficient, because it can backshift the elements of the array in bulk.

Using this method is equivalent to the following code:

If the closure returns true, then the element is removed and yielded. If the closure returns false, the element will remain in the vector and will not be yielded by the iterator.

Creates an iterator which uses a closure to determine if an element should be removed.

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

Otherwise, a temporary vector is allocated and the tail is moved twice.

The input iterator replace_with is only consumed when the Splice value is dropped.

It is unspecified how many elements are removed from the vector if the Splice value is leaked.

The element range is removed even if the iterator is not consumed until the end.

Creates a splicing iterator that replaces the specified range in the vector with the given replace_with iterator and yields the removed items. replace_with does not need to be the same length as range .

pub const fn len(&self) -> usize [src]

Returns the number of elements in the slice. Examples let a = [ 1 , 2 , 3 ]; assert_eq ! ( a . len (), 3 ); Run

pub const fn is_empty(&self) -> bool [src]

Returns true if the slice has a length of 0. Examples let a = [ 1 , 2 , 3 ]; assert ! ( ! a . is_empty ()); Run

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 ()); Run

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

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

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

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

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

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 ()); Run

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

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 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 )); Run

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

Returns a reference to an element or subslice, without doing bounds checking. This is generally not recommended, use with caution! Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used. For a safe alternative see get . Examples let x = & [ 1 , 2 , 4 ]; unsafe { assert_eq ! ( x . get_unchecked ( 1 ), & 2 ); } Run

Returns a mutable reference to an element or subslice, without doing bounds checking. This is generally not recommended, use with caution! Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used. For a safe alternative see get_mut . Examples let x = & mut [ 1 , 2 , 4 ]; unsafe { let elem = x . get_unchecked_mut ( 1 ); * elem = 13 ; } assert_eq ! ( x , & [ 1 , 13 , 4 ]); Run

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

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

🔬 This is a nightly-only experimental API. ( slice_ptr_range #65807) This is a nightly-only experimental API. (

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: #![ feature ( slice_ptr_range )] 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 )); Run

🔬 This is a nightly-only experimental API. ( slice_ptr_range #65807) This is a nightly-only experimental API. (

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

pub fn swap(&mut self, a: usize, b: usize) [src]

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" ]; v . swap ( 1 , 3 ); assert ! ( v = = [ "a" , "d" , "c" , "b" ]); Run

pub fn reverse(&mut self) [src]

Reverses the order of elements in the slice, in place. Examples let mut v = [ 1 , 2 , 3 ]; v . reverse (); assert ! ( v = = [ 3 , 2 , 1 ]); Run

pub fn iter(&self) -> Iter<T> [src]

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 ); Run

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

pub fn windows(&self, size: usize) -> Windows<T> [src]

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 ()); Run If the slice is shorter than size : let slice = [ 'f' , 'o' , 'o' ]; let mut iter = slice . windows ( 4 ); assert ! ( iter . next (). is_none ()); Run

pub fn chunks(&self, chunk_size: usize) -> Chunks<T> [src]

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 ()); Run

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

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' ]); Run

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

pub fn rchunks(&self, chunk_size: usize) -> RChunks<T> 1.31.0 [src]

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 ()); Run

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

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' ]); Run

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

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 ! ( left = = []); assert ! ( right = = [ 1 , 2 , 3 , 4 , 5 , 6 ]); } { let ( left , right ) = v . split_at ( 2 ); assert ! ( left = = [ 1 , 2 ]); assert ! ( right = = [ 3 , 4 , 5 , 6 ]); } { let ( left , right ) = v . split_at ( 6 ); assert ! ( left = = [ 1 , 2 , 3 , 4 , 5 , 6 ]); assert ! ( right = = []); } Run

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 ! ( left = = [ 1 , 0 ]); assert ! ( right = = [ 3 , 0 , 5 , 6 ]); left [ 1 ] = 2 ; right [ 1 ] = 4 ; } assert ! ( v = = [ 1 , 2 , 3 , 4 , 5 , 6 ]); Run

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 ()); Run 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 ()); Run 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 ()); Run

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

🔬 This is a nightly-only experimental API. ( split_inclusive #72360) This is a nightly-only experimental API. (

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 #![ feature ( split_inclusive )] 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 ()); Run 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. #![ feature ( split_inclusive )] 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 ()); Run

🔬 This is a nightly-only experimental API. ( split_inclusive #72360) This is a nightly-only experimental API. (

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 #![ feature ( split_inclusive )] 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 ]); Run

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 ); Run 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 ); Run

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

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

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

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

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

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 )); Run If you do not have an &T , but just an &U such that T: Borrow<U> (e.g. String: Borrow<str> ), you can use iter().any : let v = [ String :: from ( "hello" ), String :: from ( "world" )]; assert ! ( v . iter (). any ( | e | e = = "hello" )); assert ! ( ! v . iter (). any ( | e | e = = "hi" )); Run

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 ])); Run 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 ( & [])); Run

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 ])); Run 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 ( & [])); Run

#[must_use = "returns the subslice without modifying the original"] pub fn strip_prefix(&self, prefix: &[T]) -> Option<&[T]>

T: whereT: PartialEq , [src]

🔬 This is a nightly-only experimental API. ( slice_strip #73413) This is a nightly-only experimental API. (

Returns a subslice with the prefix removed. This method returns None if slice does not start with prefix . Also it returns the original slice if prefix is an empty slice. Examples #![ feature ( slice_strip )] 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 ); Run

#[must_use = "returns the subslice without modifying the original"] pub fn strip_suffix(&self, suffix: &[T]) -> Option<&[T]>

T: whereT: PartialEq , [src]

🔬 This is a nightly-only experimental API. ( slice_strip #73413) This is a nightly-only experimental API. (

Returns a subslice with the suffix removed. This method returns None if slice does not end with suffix . Also it returns the original slice if suffix is an empty slice Examples #![ feature ( slice_strip )] 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 ); Run

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. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order. Examples Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4] . 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 , }); Run 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 ]); Run

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. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order. Examples Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4] . 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 , }); Run

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. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order. Examples Looks up a series of four elements 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 , }); Run

Sorts the slice, but may not preserve the order of equal elements. This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(n * log(n)) worst-case. Current implementation The current algorithm is based on pattern-defeating quicksort by Orson Peters, which combines the fast average case of randomized quicksort with the fast worst case of heapsort, while achieving linear time on slices with certain patterns. It uses some randomization to avoid degenerate cases, but with a fixed seed to always provide deterministic behavior. It is typically faster than stable sorting, except in a few special cases, e.g., when the slice consists of several concatenated sorted sequences. Examples let mut v = [ - 5 , 4 , 1 , - 3 , 2 ]; v . sort_unstable (); assert ! ( v = = [ - 5 , - 3 , 1 , 2 , 4 ]); Run

Sorts the slice with a comparator function, but may not preserve the order of equal elements. This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(n * log(n)) worst-case. The comparator function must define a total ordering for the elements in the 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 ]); Run 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 ]); v . sort_unstable_by ( | a , b | b . cmp ( a )); assert ! ( v = = [ 5 , 4 , 3 , 2 , 1 ]); Run

Sorts the slice with a key extraction function, but may not preserve the order of equal elements. This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate), and O(m * n * log(n)) worst-case, where the key function is O(m) . Current implementation The current algorithm is based on pattern-defeating quicksort by Orson Peters, which combines the fast average case of randomized quicksort with the fast worst case of heapsort, while achieving linear time on slices with certain patterns. It uses some randomization to avoid degenerate cases, but with a fixed seed to always provide deterministic behavior. Due to its key calling strategy, sort_unstable_by_key is likely to be slower than sort_by_cached_key in cases where the key function is expensive. Examples let mut v = [ - 5i32 , 4 , 1 , - 3 , 2 ]; v . sort_unstable_by_key ( | k | k . abs ()); assert ! ( v = = [ 1 , 2 , - 3 , 4 , - 5 ]); Run

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

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 #![ feature ( slice_partition_at_index )] let mut v = [ - 5i32 , 4 , 1 , - 3 , 2 ]; v . partition_at_index ( 2 ); 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 ]); Run

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

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 #![ feature ( slice_partition_at_index )] let mut v = [ - 5i32 , 4 , 1 , - 3 , 2 ]; v . partition_at_index_by ( 2 , | a , b | b . cmp ( a )); 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 ]); Run

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

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 #![ feature ( slice_partition_at_index )] let mut v = [ - 5i32 , 4 , 1 , - 3 , 2 ]; v . partition_at_index_by_key ( 2 , | a | a . abs ()); 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 ]); Run

🔬 This is a nightly-only experimental API. ( slice_partition_dedup #54279) This is a nightly-only experimental API. (

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

🔬 This is a nightly-only experimental API. ( slice_partition_dedup #54279) This is a nightly-only experimental API. (

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" ]); Run

🔬 This is a nightly-only experimental API. ( slice_partition_dedup #54279) This is a nightly-only experimental API. (

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

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' ]); Run 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' ]); Run

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' ]); Run 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' ]); Run

🔬 This is a nightly-only experimental API. ( slice_fill #70758) This is a nightly-only experimental API. (

Fills self with elements by cloning value . Examples #![ feature ( slice_fill )] let mut buf = vec ! [ 0 ; 10 ]; buf . fill ( 1 ); assert_eq ! ( buf , vec ! [ 1 ; 10 ]); Run

Copies the elements from src into self . The length of src must be the same as self . If T implements Copy , it can be more performant to use copy_from_slice . 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 ]; dst . clone_from_slice ( & src [ 2 ..]); assert_eq ! ( src , [ 1 , 2 , 3 , 4 ]); assert_eq ! ( dst , [ 3 , 4 ]); Run 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: ⓘ This example deliberately fails to compile let mut slice = [ 1 , 2 , 3 , 4 , 5 ]; slice [.. 2 ]. clone_from_slice ( & slice [ 3 ..]); Run 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 ]); Run

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 ]; dst . copy_from_slice ( & src [ 2 ..]); assert_eq ! ( src , [ 1 , 2 , 3 , 4 ]); assert_eq ! ( dst , [ 3 , 4 ]); Run 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: ⓘ This example deliberately fails to compile let mut slice = [ 1 , 2 , 3 , 4 , 5 ]; slice [.. 2 ]. copy_from_slice ( & slice [ 3 ..]); Run 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 ]); Run

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!" ); Run

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 ]); Run 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: ⓘ This example deliberately fails to compile let mut slice = [ 1 , 2 , 3 , 4 , 5 ]; slice [.. 2 ]. swap_with_slice ( & mut slice [ 3 ..]); Run 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 ]); Run

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 > (); } Run

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 > (); } Run

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

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 ()); Run

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

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 #53485) new API

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 ())); Run

🔬 This is a nightly-only experimental API. ( partition_point #73831) new API