Returns the total number of elements the vector can hold withoutreallocating.

§Examples

letmutvec: Vec<i32> = Vec::with_capacity(10);vec.push(42);assert!(vec.capacity() >=10);

A vector with zero-sized elements will always have a capacity of usize::MAX:

#[derive(Clone)]structZeroSized;fnmain() {assert_eq!(std::mem::size_of::<ZeroSized>(),0);letv =vec![ZeroSized;0];assert_eq!(v.capacity(), usize::MAX);}

Reserves capacity for at leastadditional more elements to be insertedin the givenVec<T>. The collection may reserve more space tospeculatively avoid frequent reallocations. After callingreserve,capacity will be greater than or equal toself.len() + additional.Does nothing if capacity is already sufficient.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1];vec.reserve(10);assert!(vec.capacity() >=11);

Reserves the minimum capacity for at leastadditional more elements tobe inserted in the givenVec<T>. Unlikereserve, this will notdeliberately over-allocate to speculatively avoid frequent allocations.After callingreserve_exact, capacity will be greater than or equal toself.len() + additional. Does nothing if the capacity is alreadysufficient.

Note that the allocator may give the collection more space than itrequests. Therefore, capacity can not be relied upon to be preciselyminimal. Preferreserve if future insertions are expected.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1];vec.reserve_exact(10);assert!(vec.capacity() >=11);

Tries to reserve capacity for at leastadditional more elements to be insertedin the givenVec<T>. The collection may reserve more space to speculatively avoidfrequent reallocations. After callingtry_reserve, capacity will begreater than or equal toself.len() + additional if it returnsOk(()). Does nothing if capacity is already sufficient. This methodpreserves the contents even if an error occurs.

§Errors

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

§Examples

usestd::collections::TryReserveError;fnprocess_data(data:&[u32]) ->Result<Vec<u32>, TryReserveError> {letmutoutput = Vec::new();// Pre-reserve the memory, exiting if we can'toutput.try_reserve(data.len())?;// Now we know this can't OOM in the middle of our complex workoutput.extend(data.iter().map(|&val| {        val *2+5// very complicated}));Ok(output)}

Tries to reserve the minimum capacity for at leastadditionalelements to be inserted in the givenVec<T>. Unliketry_reserve,this will not deliberately over-allocate to speculatively avoid frequentallocations. After callingtry_reserve_exact, capacity will be greaterthan or equal toself.len() + additional if it returnsOk(()).Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than itrequests. Therefore, capacity can not be relied upon to be preciselyminimal. Prefertry_reserve if future insertions are expected.

§Errors

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

§Examples

usestd::collections::TryReserveError;fnprocess_data(data:&[u32]) ->Result<Vec<u32>, TryReserveError> {letmutoutput = Vec::new();// Pre-reserve the memory, exiting if we can'toutput.try_reserve_exact(data.len())?;// Now we know this can't OOM in the middle of our complex workoutput.extend(data.iter().map(|&val| {        val *2+5// very complicated}));Ok(output)}

Shrinks the capacity of the vector as much as possible.

The behavior of this method depends on the allocator, which may either shrink the vectorin-place or reallocate. The resulting vector might still have some excess capacity, just asis the case forwith_capacity. SeeAllocator::shrink for more details.

§Examples

letmutvec = Vec::with_capacity(10);vec.extend([1,2,3]);assert!(vec.capacity() >=10);vec.shrink_to_fit();assert!(vec.capacity() >=3);

Shrinks the capacity of the vector with a lower bound.

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

If the current capacity is less than the lower limit, this is a no-op.

§Examples

letmutvec = Vec::with_capacity(10);vec.extend([1,2,3]);assert!(vec.capacity() >=10);vec.shrink_to(4);assert!(vec.capacity() >=4);vec.shrink_to(0);assert!(vec.capacity() >=3);

Shortens the vector, keeping the firstlen elements and droppingthe rest.

Iflen is greater or equal to the vector’s current length, this hasno effect.

Thedrain method can emulatetruncate, but causes the excesselements to be returned instead of dropped.

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

§Examples

Truncating a five element vector to two elements:

letmutvec =vec![1,2,3,4,5];vec.truncate(2);assert_eq!(vec, [1,2]);

No truncation occurs whenlen is greater than the vector’s currentlength:

letmutvec =vec![1,2,3];vec.truncate(8);assert_eq!(vec, [1,2,3]);

Truncating whenlen == 0 is equivalent to calling theclearmethod.

letmutvec =vec![1,2,3];vec.truncate(0);assert_eq!(vec, []);

Extracts a slice containing the entire vector.

Equivalent to&s[..].

§Examples

usestd::io::{self, Write};letbuffer =vec![1,2,3,5,8];io::sink().write(buffer.as_slice()).unwrap();

Extracts a mutable slice of the entire vector.

Equivalent to&mut s[..].

§Examples

usestd::io::{self, Read};letmutbuffer =vec![0;3];io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();

Returns a raw pointer to the vector’s buffer, or a dangling raw pointervalid for zero sized reads if the vector didn’t allocate.

The caller must ensure that the vector outlives the pointer thisfunction returns, or else it will end up dangling.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 tois never written to (except inside anUnsafeCell) using this pointer or any pointerderived from it. If you need to mutate the contents of the slice, useas_mut_ptr.

This method guarantees that for the purpose of the aliasing model, this methoddoes not materialize a reference to the underlying slice, and thus the returned pointerwill remain valid when mixed with other calls toas_ptr,as_mut_ptr,andas_non_null.Note that calling other methods that materialize mutable references to the slice,or mutable references to specific elements you are planning on accessing through this pointer,as well as writing to those elements, may still invalidate this pointer.See the second example below for how this guarantee can be used.

§Examples

letx =vec![1,2,4];letx_ptr = x.as_ptr();unsafe{foriin0..x.len() {assert_eq!(*x_ptr.add(i),1<< i);    }}

Due to the aliasing guarantee, the following code is legal:

unsafe{letmutv =vec![0,1,2];letptr1 = v.as_ptr();let _= ptr1.read();letptr2 = v.as_mut_ptr().offset(2);    ptr2.write(2);// Notably, the write to `ptr2` did *not* invalidate `ptr1`    // because it mutated a different element:let _= ptr1.read();}

Returns a raw mutable pointer to the vector’s buffer, or a danglingraw pointer valid for zero sized reads if the vector didn’t allocate.

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

This method guarantees that for the purpose of the aliasing model, this methoddoes not materialize a reference to the underlying slice, and thus the returned pointerwill remain valid when mixed with other calls toas_ptr,as_mut_ptr,andas_non_null.Note that calling other methods that materialize references to the slice,or references to specific elements you are planning on accessing through this pointer,may still invalidate this pointer.See the second example below for how this guarantee can be used.

The method also guarantees that, as long asT is not zero-sized and the capacity isnonzero, the pointer may be passed intodealloc with a layout ofLayout::array::<T>(capacity) in order to deallocate the backing memory. If this is done,be careful not to run the destructor of theVec, as dropping it will result indouble-frees. Wrapping theVec in aManuallyDrop is the typical way to achieve this.

§Examples

// Allocate vector big enough for 4 elements.letsize =4;letmutx: Vec<i32> = Vec::with_capacity(size);letx_ptr = x.as_mut_ptr();// Initialize elements via raw pointer writes, then set length.unsafe{foriin0..size {*x_ptr.add(i) = iasi32;    }    x.set_len(size);}assert_eq!(&*x,&[0,1,2,3]);

Due to the aliasing guarantee, the following code is legal:

unsafe{letmutv =vec![0];letptr1 = v.as_mut_ptr();    ptr1.write(1);letptr2 = v.as_mut_ptr();    ptr2.write(2);// Notably, the write to `ptr2` did *not* invalidate `ptr1`:ptr1.write(3);}

Deallocating a vector usingBox (which usesdealloc internally):

usestd::mem::{ManuallyDrop, MaybeUninit};letmutv = ManuallyDrop::new(vec![0,1,2]);letptr = v.as_mut_ptr();letcapacity = v.capacity();letslice_ptr:*mut[MaybeUninit<i32>] =    std::ptr::slice_from_raw_parts_mut(ptr.cast(), capacity);drop(unsafe{ Box::from_raw(slice_ptr) });

Returns aNonNull pointer to the vector’s buffer, or a danglingNonNull pointer valid for zero sized reads if the vector didn’t allocate.

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

This method guarantees that for the purpose of the aliasing model, this methoddoes not materialize a reference to the underlying slice, and thus the returned pointerwill remain valid when mixed with other calls toas_ptr,as_mut_ptr,andas_non_null.Note that calling other methods that materialize references to the slice,or references to specific elements you are planning on accessing through this pointer,may still invalidate this pointer.See the second example below for how this guarantee can be used.

§Examples

#![feature(box_vec_non_null)]// Allocate vector big enough for 4 elements.letsize =4;letmutx: Vec<i32> = Vec::with_capacity(size);letx_ptr = x.as_non_null();// Initialize elements via raw pointer writes, then set length.unsafe{foriin0..size {        x_ptr.add(i).write(iasi32);    }    x.set_len(size);}assert_eq!(&*x,&[0,1,2,3]);

Due to the aliasing guarantee, the following code is legal:

#![feature(box_vec_non_null)]unsafe{letmutv =vec![0];letptr1 = v.as_non_null();    ptr1.write(1);letptr2 = v.as_non_null();    ptr2.write(2);// Notably, the write to `ptr2` did *not* invalidate `ptr1`:ptr1.write(3);}

Returns a reference to the underlying allocator.

Forces the length of the vector tonew_len.

This is a low-level operation that maintains none of the normalinvariants of the type. Normally changing the length of a vectoris done using one of the safe operations instead, such astruncate,resize,extend, orclear.

§Safety

• new_len must be less than or equal tocapacity().
• The elements atold_len..new_len must be initialized.

§Examples

Seespare_capacity_mut() for an example with safeinitialization of capacity elements and use of this method.

set_len() can be useful for situations in which the vectoris serving as a buffer for other code, particularly over FFI:

pub fnget_dictionary(&self) ->Option<Vec<u8>> {// Per the FFI method's docs, "32768 bytes is always enough".letmutdict = Vec::with_capacity(32_768);letmutdict_length =0;// SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:    // 1. `dict_length` elements were initialized.    // 2. `dict_length` <= the capacity (32_768)    // which makes `set_len` safe to call.unsafe{// Make the FFI call...letr = deflateGetDictionary(self.strm, dict.as_mut_ptr(),&mutdict_length);ifr == Z_OK {// ...and update the length to what was initialized.dict.set_len(dict_length);Some(dict)        }else{None}    }}

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

letmutvec =vec![vec![1,0,0],vec![0,1,0],vec![0,0,1]];// SAFETY:// 1. `old_len..0` is empty so no elements need to be initialized.// 2. `0 <= capacity` always holds whatever `capacity` is.unsafe{    vec.set_len(0);}

Normally, here, one would useclear instead to correctly dropthe contents and thus not leak memory.

Removes an element from the vector and returns it.

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

This does not preserve ordering of the remaining elements, but isO(1).If you need to preserve the element order, useremove instead.

§Panics

Panics ifindex is out of bounds.

§Examples

letmutv =vec!["foo","bar","baz","qux"];assert_eq!(v.swap_remove(1),"bar");assert_eq!(v, ["foo","qux","baz"]);assert_eq!(v.swap_remove(0),"foo");assert_eq!(v, ["baz","qux"]);

Inserts an element at positionindex within the vector, shifting allelements after it to the right.

§Panics

Panics ifindex > len.

§Examples

letmutvec =vec!['a','b','c'];vec.insert(1,'d');assert_eq!(vec, ['a','d','b','c']);vec.insert(4,'e');assert_eq!(vec, ['a','d','b','c','e']);

§Time complexity

TakesO(Vec::len) time. All items after the insertion index must beshifted to the right. In the worst case, all elements are shifted whenthe insertion index is 0.

Inserts an element at positionindex within the vector, shifting allelements after it to the right, and returning a reference to the newelement.

§Panics

Panics ifindex > len.

§Examples

#![feature(push_mut)]letmutvec =vec![1,3,5,9];letx = vec.insert_mut(3,6);*x +=1;assert_eq!(vec, [1,3,5,7,9]);

§Time complexity

TakesO(Vec::len) time. All items after the insertion index must beshifted to the right. In the worst case, all elements are shifted whenthe insertion index is 0.

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

Note: Because this shifts over the remaining elements, it has aworst-case performance ofO(n). If you don’t need the order of elementsto be preserved, useswap_remove instead. If you’d like to removeelements from the beginning of theVec, consider usingVecDeque::pop_front instead.

§Panics

Panics ifindex is out of bounds.

§Examples

letmutv =vec!['a','b','c'];assert_eq!(v.remove(1),'b');assert_eq!(v, ['a','c']);

Remove and return the element at positionindex within the vector,shifting all elements after it to the left, orNone if it does notexist.

Note: Because this shifts over the remaining elements, it has aworst-case performance ofO(n). If you’d like to removeelements from the beginning of theVec, consider usingVecDeque::pop_front instead.

§Examples

#![feature(vec_try_remove)]letmutv =vec![1,2,3];assert_eq!(v.try_remove(0),Some(1));assert_eq!(v.try_remove(2),None);

Retains only the elements specified by the predicate.

In other words, remove all elementse for whichf(&e) returnsfalse.This method operates in place, visiting each element exactly once in theoriginal order, and preserves the order of the retained elements.

§Examples

letmutvec =vec![1,2,3,4];vec.retain(|&x| x %2==0);assert_eq!(vec, [2,4]);

Because the elements are visited exactly once in the original order,external state may be used to decide which elements to keep.

letmutvec =vec![1,2,3,4,5];letkeep = [false,true,true,false,true];letmutiter = keep.iter();vec.retain(|_|*iter.next().unwrap());assert_eq!(vec, [2,3,5]);

Retains only the elements specified by the predicate, passing a mutable reference to it.

In other words, remove all elementse such thatf(&mut e) returnsfalse.This method operates in place, visiting each element exactly once in theoriginal order, and preserves the order of the retained elements.

§Examples

letmutvec =vec![1,2,3,4];vec.retain_mut(|x|if*x <=3{*x +=1;true}else{false});assert_eq!(vec, [2,3,4]);

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

If the vector is sorted, this removes all duplicates.

§Examples

letmutvec =vec![10,20,21,30,20];vec.dedup_by_key(|i|*i /10);assert_eq!(vec, [10,20,30,20]);

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

Thesame_bucket function is passed references to two elements from the vector andmust determine if the elements compare equal. The elements are passed in opposite orderfrom their order in the slice, so ifsame_bucket(a, b) returnstrue,a is removed.

If the vector is sorted, this removes all duplicates.

§Examples

letmutvec =vec!["foo","bar","Bar","baz","bar"];vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));assert_eq!(vec, ["foo","bar","baz","bar"]);

Appends an element to the back of a collection.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1,2];vec.push(3);assert_eq!(vec, [1,2,3]);

§Time complexity

Takes amortizedO(1) time. If the vector’s length would exceed itscapacity after the push,O(capacity) time is taken to copy thevector’s elements to a larger allocation. This expensive operation isoffset by thecapacityO(1) insertions it allows.

Appends an element and returns a reference to it if there is sufficient spare capacity,otherwise an error is returned with the element.

Unlikepush this method will not reallocate when there’s insufficient capacity.The caller should usereserve ortry_reserve to ensure that there is enough capacity.

§Examples

A manual, panic-free alternative toFromIterator:

#![feature(vec_push_within_capacity)]usestd::collections::TryReserveError;fnfrom_iter_fallible<T>(iter:implIterator<Item=T>) ->Result<Vec<T>, TryReserveError> {letmutvec = Vec::new();forvalueiniter {if letErr(value) = vec.push_within_capacity(value) {            vec.try_reserve(1)?;// this cannot fail, the previous line either returned or added at least 1 free slotlet _= vec.push_within_capacity(value);        }    }Ok(vec)}assert_eq!(from_iter_fallible(0..100),Ok(Vec::from_iter(0..100)));

§Time complexity

TakesO(1) time.

Appends an element to the back of a collection, returning a reference to it.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

#![feature(push_mut)]letmutvec =vec![1,2];letlast = vec.push_mut(3);assert_eq!(*last,3);assert_eq!(vec, [1,2,3]);letlast = vec.push_mut(3);*last +=1;assert_eq!(vec, [1,2,3,4]);

§Time complexity

Takes amortizedO(1) time. If the vector’s length would exceed itscapacity after the push,O(capacity) time is taken to copy thevector’s elements to a larger allocation. This expensive operation isoffset by thecapacityO(1) insertions it allows.

Removes the last element from a vector and returns it, orNone if itis empty.

If you’d like to pop the first element, consider usingVecDeque::pop_front instead.

§Examples

letmutvec =vec![1,2,3];assert_eq!(vec.pop(),Some(3));assert_eq!(vec, [1,2]);

§Time complexity

TakesO(1) time.

Removes and returns the last element from a vector if the predicatereturnstrue, orNone if the predicate returns false or the vectoris empty (the predicate will not be called in that case).

§Examples

letmutvec =vec![1,2,3,4];letpred = |x:&muti32|*x %2==0;assert_eq!(vec.pop_if(pred),Some(4));assert_eq!(vec, [1,2,3]);assert_eq!(vec.pop_if(pred),None);

Returns a mutable reference to the last item in the vector, orNone if it is empty.

§Examples

Basic usage:

#![feature(vec_peek_mut)]letmutvec = Vec::new();assert!(vec.peek_mut().is_none());vec.push(1);vec.push(5);vec.push(2);assert_eq!(vec.last(),Some(&2));if letSome(mutval) = vec.peek_mut() {*val =0;}assert_eq!(vec.last(),Some(&0));

Moves all the elements ofother intoself, leavingother empty.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1,2,3];letmutvec2 =vec![4,5,6];vec.append(&mutvec2);assert_eq!(vec, [1,2,3,4,5,6]);assert_eq!(vec2, []);

Removes the subslice indicated by the given range from the vector,returning a double-ended iterator over the removed subslice.

If the iterator is dropped before being fully consumed,it drops the remaining removed elements.

The returned iterator keeps a mutable borrow on the vector to optimizeits implementation.

§Panics

Panics if the range hasstart_bound > end_bound, or, if the range isbounded on either end and past the length of the vector.

§Leaking

If the returned iterator goes out of scope without being dropped (due tomem::forget, for example), the vector may have lost and leakedelements arbitrarily, including elements outside the range.

§Examples

letmutv =vec![1,2,3];letu: Vec<_> = v.drain(1..).collect();assert_eq!(v,&[1]);assert_eq!(u,&[2,3]);// A full range clears the vector, like `clear()` doesv.drain(..);assert_eq!(v,&[]);

Clears the vector, removing all values.

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

§Examples

letmutv =vec![1,2,3];v.clear();assert!(v.is_empty());

Returns the number of elements in the vector, also referred toas its ‘length’.

§Examples

leta =vec![1,2,3];assert_eq!(a.len(),3);

Returnstrue if the vector contains no elements.

§Examples

letmutv = Vec::new();assert!(v.is_empty());v.push(1);assert!(!v.is_empty());

Splits the collection into two at the given index.

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

• If you want to take ownership of the entire contents and capacity ofthe vector, seemem::take ormem::replace.
• If you don’t need the returned vector at all, seeVec::truncate.
• If you want to take ownership of an arbitrary subslice, or you don’tnecessarily want to store the removed items in a vector, seeVec::drain.

§Panics

Panics ifat > len.

§Examples

letmutvec =vec!['a','b','c'];letvec2 = vec.split_off(1);assert_eq!(vec, ['a']);assert_eq!(vec2, ['b','c']);

Resizes theVec in-place so thatlen is equal tonew_len.

Ifnew_len is greater thanlen, theVec is extended by thedifference, with each additional slot filled with the result ofcalling the closuref. The return values fromf will end upin theVec in the order they have been generated.

Ifnew_len is less thanlen, theVec is simply truncated.

This method uses a closure to create new values on every push. Ifyou’d ratherClone a given value, useVec::resize. If youwant to use theDefault trait to generate values, you canpassDefault::default as the second argument.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1,2,3];vec.resize_with(5, Default::default);assert_eq!(vec, [1,2,3,0,0]);letmutvec =vec![];letmutp =1;vec.resize_with(4, || { p*=2; p });assert_eq!(vec, [2,4,8,16]);

Returns the remaining spare capacity of the vector as a slice ofMaybeUninit<T>.

The returned slice can be used to fill the vector with data (e.g. byreading from a file) before marking the data as initialized using theset_len method.

§Examples

// Allocate vector big enough for 10 elements.letmutv = Vec::with_capacity(10);// Fill in the first 3 elements.letuninit = v.spare_capacity_mut();uninit[0].write(0);uninit[1].write(1);uninit[2].write(2);// Mark the first 3 elements of the vector as being initialized.unsafe{    v.set_len(3);}assert_eq!(&v,&[0,1,2]);

Returns vector content as a slice ofT, along with the remaining sparecapacity of the vector as a slice ofMaybeUninit<T>.

The returned spare capacity slice can be used to fill the vector with data(e.g. by reading from a file) before marking the data as initialized usingtheset_len method.

Note that this is a low-level API, which should be used with care foroptimization purposes. If you need to append data to aVecyou can usepush,extend,extend_from_slice,extend_from_within,insert,append,resize orresize_with, depending on your exact needs.

§Examples

#![feature(vec_split_at_spare)]letmutv =vec![1,1,2];// Reserve additional space big enough for 10 elements.v.reserve(10);let(init, uninit) = v.split_at_spare_mut();letsum = init.iter().copied().sum::<u32>();// Fill in the next 4 elements.uninit[0].write(sum);uninit[1].write(sum *2);uninit[2].write(sum *3);uninit[3].write(sum *4);// Mark the 4 elements of the vector as being initialized.unsafe{letlen = v.len();    v.set_len(len +4);}assert_eq!(&v,&[1,1,2,4,8,12,16]);

Resizes theVec in-place so thatlen is equal tonew_len.

Ifnew_len is greater thanlen, theVec is extended by thedifference, with each additional slot filled withvalue.Ifnew_len is less thanlen, theVec is simply truncated.

This method requiresT to implementClone,in order to be able to clone the passed value.If you need more flexibility (or want to rely onDefault instead ofClone), useVec::resize_with.If you only need to resize to a smaller size, useVec::truncate.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec!["hello"];vec.resize(3,"world");assert_eq!(vec, ["hello","world","world"]);letmutvec =vec!['a','b','c','d'];vec.resize(2,'_');assert_eq!(vec, ['a','b']);

Clones and appends all elements in a slice to theVec.

Iterates over the sliceother, clones each element, and then appendsit to thisVec. Theother slice is traversed in-order.

Note that this function is the same asextend,except that it also works with slice elements that are Clone but not Copy.If Rust gets specialization this function may be deprecated.

§Panics

Panics if the new capacity exceedsisize::MAXbytes.

§Examples

letmutvec =vec![1];vec.extend_from_slice(&[2,3,4]);assert_eq!(vec, [1,2,3,4]);

Given a rangesrc, clones a slice of elements in that range and appends it to the end.

src must be a range that can form a valid subslice of theVec.

§Panics

Panics if starting index is greater than the end index, if the index isgreater than the length of the vector, or if the new capacity exceedsisize::MAXbytes.

§Examples

letmutcharacters =vec!['a','b','c','d','e'];characters.extend_from_within(2..);assert_eq!(characters, ['a','b','c','d','e','c','d','e']);letmutnumbers =vec![0,1,2,3,4];numbers.extend_from_within(..2);assert_eq!(numbers, [0,1,2,3,4,0,1]);letmutstrings =vec![String::from("hello"), String::from("world"), String::from("!")];strings.extend_from_within(1..=2);assert_eq!(strings, ["hello","world","!","world","!"]);

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

If the vector is sorted, this removes all duplicates.

§Examples

letmutvec =vec![1,2,2,3,2];vec.dedup();assert_eq!(vec, [1,2,3,2]);

Creates a splicing iterator that replaces the specified range in the vectorwith the givenreplace_with iterator and yields the removed items.replace_with does not need to be the same length asrange.

range is removed even if theSplice iterator is not consumed before it is dropped.

It is unspecified how many elements are removed from the vectorif theSplice value is leaked.

The input iteratorreplace_with is only consumed when theSplice value is dropped.

This is optimal if:

• The tail (elements in the vector afterrange) is empty,
• orreplace_with yields fewer or equal elements thanrange’s length
• or the lower bound of itssize_hint() is exact.

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

§Panics

Panics if the range hasstart_bound > end_bound, or, if the range isbounded on either end and past the length of the vector.

§Examples

letmutv =vec![1,2,3,4];letnew = [7,8,9];letu: Vec<_> = v.splice(1..3, new).collect();assert_eq!(v, [1,7,8,9,4]);assert_eq!(u, [2,3]);

Usingsplice to insert new items into a vector efficiently at a specific positionindicated by an empty range:

letmutv =vec![1,5];letnew = [2,3,4];v.splice(1..1, new);assert_eq!(v, [1,2,3,4,5]);

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

If the closure returnstrue, the element is removed from the vectorand yielded. If the closure returnsfalse, or panics, the elementremains in the vector and will not be yielded.

Only elements that fall in the provided range are considered for extraction, but any elementsafter the range will still have to be moved if any element has been extracted.

If the returnedExtractIf is not exhausted, e.g. because it is dropped without iteratingor the iteration short-circuits, then the remaining elements will be retained.Useextract_if().for_each(drop) if you do not need the returned iterator,orretain_mut with a negated predicate if you also do not need to restrict the range.

Using this method is equivalent to the following code:

letmuti = range.start;letend_items = vec.len() - range.end;whilei < vec.len() - end_items {ifsome_predicate(&mutvec[i]) {letval = vec.remove(i);// your code here}else{        i +=1;    }}

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

The iterator also lets you mutate the value of each element in theclosure, regardless of whether you choose to keep or remove it.

§Panics

Ifrange is out of bounds.

§Examples

Splitting a vector into even and odd values, reusing the original vector:

letmutnumbers =vec![1,2,3,4,5,6,8,9,11,13,14,15];letevens = numbers.extract_if(.., |x|*x %2==0).collect::<Vec<_>>();letodds = numbers;assert_eq!(evens,vec![2,4,6,8,14]);assert_eq!(odds,vec![1,3,5,9,11,13,15]);

Using the range argument to only process a part of the vector:

letmutitems =vec![0,0,0,0,0,0,0,1,2,1,2,1,2];letones = items.extract_if(7.., |x|*x ==1).collect::<Vec<_>>();assert_eq!(items,vec![0,0,0,0,0,0,0,2,2,2]);assert_eq!(ones.len(),3);

Returns the number of elements in the slice.

§Examples

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

Returnstrue if the slice has a length of 0.

§Examples

leta = [1,2,3];assert!(!a.is_empty());letb:&[i32] =&[];assert!(b.is_empty());

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

§Examples

letv = [10,40,30];assert_eq!(Some(&10), v.first());letw:&[i32] =&[];assert_eq!(None, w.first());

Returns a mutable reference to the first element of the slice, orNone if it is empty.

§Examples

letx =&mut[0,1,2];if letSome(first) = x.first_mut() {*first =5;}assert_eq!(x,&[5,1,2]);lety:&mut[i32] =&mut[];assert_eq!(None, y.first_mut());

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

§Examples

letx =&[0,1,2];if letSome((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, orNone if it is empty.

§Examples

letx =&mut[0,1,2];if letSome((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, orNone if it is empty.

§Examples

letx =&[0,1,2];if letSome((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, orNone if it is empty.

§Examples

letx =&mut[0,1,2];if letSome((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, orNone if it is empty.

§Examples

letv = [10,40,30];assert_eq!(Some(&30), v.last());letw:&[i32] =&[];assert_eq!(None, w.last());

Returns a mutable reference to the last item in the slice, orNone if it is empty.

§Examples

letx =&mut[0,1,2];if letSome(last) = x.last_mut() {*last =10;}assert_eq!(x,&[0,1,10]);lety:&mut[i32] =&mut[];assert_eq!(None, y.last_mut());

Returns an array reference to the firstN items in the slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letu = [10,40,30];assert_eq!(Some(&[10,40]), u.first_chunk::<2>());letv:&[i32] =&[10];assert_eq!(None, v.first_chunk::<2>());letw:&[i32] =&[];assert_eq!(Some(&[]), w.first_chunk::<0>());

Returns a mutable array reference to the firstN items in the slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&mut[0,1,2];if letSome(first) = x.first_chunk_mut::<2>() {    first[0] =5;    first[1] =4;}assert_eq!(x,&[5,4,2]);assert_eq!(None, x.first_chunk_mut::<4>());

Returns an array reference to the firstN items in the slice and the remaining slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&[0,1,2];if letSome((first, elements)) = x.split_first_chunk::<2>() {assert_eq!(first,&[0,1]);assert_eq!(elements,&[2]);}assert_eq!(None, x.split_first_chunk::<4>());

Returns a mutable array reference to the firstN items in the slice and the remainingslice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&mut[0,1,2];if letSome((first, elements)) = x.split_first_chunk_mut::<2>() {    first[0] =3;    first[1] =4;    elements[0] =5;}assert_eq!(x,&[3,4,5]);assert_eq!(None, x.split_first_chunk_mut::<4>());

Returns an array reference to the lastN items in the slice and the remaining slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&[0,1,2];if letSome((elements, last)) = x.split_last_chunk::<2>() {assert_eq!(elements,&[0]);assert_eq!(last,&[1,2]);}assert_eq!(None, x.split_last_chunk::<4>());

Returns a mutable array reference to the lastN items in the slice and the remainingslice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&mut[0,1,2];if letSome((elements, last)) = x.split_last_chunk_mut::<2>() {    last[0] =3;    last[1] =4;    elements[0] =5;}assert_eq!(x,&[5,3,4]);assert_eq!(None, x.split_last_chunk_mut::<4>());

Returns an array reference to the lastN items in the slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letu = [10,40,30];assert_eq!(Some(&[40,30]), u.last_chunk::<2>());letv:&[i32] =&[10];assert_eq!(None, v.last_chunk::<2>());letw:&[i32] =&[];assert_eq!(Some(&[]), w.last_chunk::<0>());

Returns a mutable array reference to the lastN items in the slice.

If the slice is not at leastN in length, this will returnNone.

§Examples

letx =&mut[0,1,2];if letSome(last) = x.last_chunk_mut::<2>() {    last[0] =10;    last[1] =20;}assert_eq!(x,&[0,10,20]);assert_eq!(None, x.last_chunk_mut::<4>());

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

• If given a position, returns a reference to the element at thatposition orNone if out of bounds.
• If given a range, returns the subslice corresponding to that range,orNone if out of bounds.

§Examples

letv = [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 thetype of index (seeget) orNone if the index is out of bounds.

§Examples

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

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

For a safe alternative seeget.

§Safety

Calling this method with an out-of-bounds index isundefined behavioreven if the resulting reference is not used.

You can think of this like.get(index).unwrap_unchecked(). It’s UBto call.get_unchecked(len), even if you immediately convert to apointer. And it’s UB to call.get_unchecked(..len + 1),.get_unchecked(..=len), or similar.

§Examples

letx =&[1,2,4];unsafe{assert_eq!(x.get_unchecked(1),&2);}

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

For a safe alternative seeget_mut.

§Safety

Calling this method with an out-of-bounds index isundefined behavioreven if the resulting reference is not used.

You can think of this like.get_mut(index).unwrap_unchecked(). It’sUB to call.get_unchecked_mut(len), even if you immediately convertto a pointer. And it’s UB to call.get_unchecked_mut(..len + 1),.get_unchecked_mut(..=len), or similar.

§Examples

letx =&mut[1,2,4];unsafe{letelem = 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 thisfunction returns, or else it will end up dangling.

The caller must also ensure that the memory the pointer (non-transitively) points tois never written to (except inside anUnsafeCell) using this pointer or any pointerderived from it. If you need to mutate the contents of the slice, useas_mut_ptr.

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

§Examples

letx =&[1,2,4];letx_ptr = x.as_ptr();unsafe{foriin0..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 thisfunction returns, or else it will end up dangling.

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

§Examples

letx =&mut[1,2,4];letx_ptr = x.as_mut_ptr();unsafe{foriin0..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 pointerpointsone past the last element of the slice. This way, an emptyslice is represented by two equal pointers, and the difference betweenthe two pointers represents the size of the slice.

Seeas_ptr for warnings on using these pointers. The end pointerrequires extra caution, as it does not point to a valid element in theslice.

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

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

leta = [1,2,3];letx =&a[1]as*const_;lety =&5as*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 pointerpointsone past the last element of the slice. This way, an emptyslice is represented by two equal pointers, and the difference betweenthe two pointers represents the size of the slice.

Seeas_mut_ptr for warnings on using these pointers. The endpointer requires extra caution, as it does not point to a valid elementin the slice.

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

Gets a reference to the underlying array.

IfN is not exactly equal to the length ofself, then this method returnsNone.

Gets a mutable reference to the slice’s underlying array.

IfN is not exactly equal to the length ofself, then this method returnsNone.

Swaps two elements in the slice.

Ifa equals tob, it’s guaranteed that elements won’t change value.

§Arguments

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

§Panics

Panics ifa orb are out of bounds.

§Examples

letmutv = ["a","b","c","d","e"];v.swap(2,4);assert!(v == ["a","b","e","d","c"]);

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

For a safe alternative seeswap.

§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 isundefined behavior.The caller has to ensure thata < self.len() andb < self.len().

§Examples

#![feature(slice_swap_unchecked)]letmutv = ["a","b","c","d"];// SAFETY: we know that 1 and 3 are both indices of the sliceunsafe{ v.swap_unchecked(1,3) };assert!(v == ["a","d","c","b"]);

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

§Examples

letmutv = [1,2,3];v.reverse();assert!(v == [3,2,1]);

Returns an iterator over the slice.

The iterator yields all items from start to end.

§Examples

letx =&[1,2,4];letmutiterator = 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.

The iterator yields all items from start to end.

§Examples

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

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

§Panics

Panics ifsize is zero.

§Examples

letslice = ['l','o','r','e','m'];letmutiter = slice.windows(3);assert_eq!(iter.next().unwrap(),&['l','o','r']);assert_eq!(iter.next().unwrap(),&['o','r','e']);assert_eq!(iter.next().unwrap(),&['r','e','m']);assert!(iter.next().is_none());

If the slice is shorter thansize:

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

Because theIterator trait cannot represent the required lifetimes,there is nowindows_mut analog towindows;[0,1,2].windows_mut(2).collect() would violatethe rules of references(though aLendingIterator analog is possible). You can sometimes useCell::as_slice_of_cells inconjunction withwindows instead:

usestd::cell::Cell;letmutarray = ['R','u','s','t',' ','2','0','1','5'];letslice =&mutarray[..];letslice_of_cells:&[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();forwinslice_of_cells.windows(3) {    Cell::swap(&w[0],&w[2]);}assert_eq!(array, ['s','t',' ','2','0','1','5','u','R']);

Returns an iterator overchunk_size elements of the slice at a time, starting at thebeginning of the slice.

The chunks are slices and do not overlap. Ifchunk_size does not divide the length of theslice, then the last chunk will not have lengthchunk_size.

Seechunks_exact for a variant of this iterator that returns chunks of always exactlychunk_size elements, andrchunks for the same iterator but starting at the end of theslice.

If yourchunk_size is a constant, consider usingas_chunks instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letslice = ['l','o','r','e','m'];letmutiter = 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 overchunk_size elements of the slice at a time, starting at thebeginning of the slice.

The chunks are mutable slices, and do not overlap. Ifchunk_size does not divide thelength of the slice, then the last chunk will not have lengthchunk_size.

Seechunks_exact_mut for a variant of this iterator that returns chunks of alwaysexactlychunk_size elements, andrchunks_mut for the same iterator but starting atthe end of the slice.

If yourchunk_size is a constant, consider usingas_chunks_mut instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;forchunkinv.chunks_mut(2) {foreleminchunk.iter_mut() {*elem += count;    }    count +=1;}assert_eq!(v,&[1,1,2,2,3]);

Returns an iterator overchunk_size elements of the slice at a time, starting at thebeginning of the slice.

The chunks are slices and do not overlap. Ifchunk_size does not divide the length of theslice, then the last up tochunk_size-1 elements will be omitted and can be retrievedfrom theremainder function of the iterator.

Due to each chunk having exactlychunk_size elements, the compiler can often optimize theresulting code better than in the case ofchunks.

Seechunks for a variant of this iterator that also returns the remainder as a smallerchunk, andrchunks_exact for the same iterator but starting at the end of the slice.

If yourchunk_size is a constant, consider usingas_chunks instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letslice = ['l','o','r','e','m'];letmutiter = 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 overchunk_size elements of the slice at a time, starting at thebeginning of the slice.

The chunks are mutable slices, and do not overlap. Ifchunk_size does not divide thelength of the slice, then the last up tochunk_size-1 elements will be omitted and can beretrieved from theinto_remainder function of the iterator.

Due to each chunk having exactlychunk_size elements, the compiler can often optimize theresulting code better than in the case ofchunks_mut.

Seechunks_mut for a variant of this iterator that also returns the remainder as asmaller chunk, andrchunks_exact_mut for the same iterator but starting at the end ofthe slice.

If yourchunk_size is a constant, consider usingas_chunks_mut instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;forchunkinv.chunks_exact_mut(2) {foreleminchunk.iter_mut() {*elem += count;    }    count +=1;}assert_eq!(v,&[1,1,2,2,0]);

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

This is the inverse operation toas_flattened.

As this isunsafe, consider whether you could useas_chunks oras_rchunks instead, perhaps via something likeif let (chunks, []) = slice.as_chunks() orlet (chunks, []) = slice.as_chunks() else { unreachable!() };.

§Safety

This may only be called when

• The slice splits exactly intoN-element chunks (akaself.len() % N == 0).
• N != 0.

§Examples

letslice:&[char] =&['l','o','r','e','m','!'];letchunks:&[[char;1]] =// SAFETY: 1-element chunks never have remainderunsafe{ slice.as_chunks_unchecked() };assert_eq!(chunks,&[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);letchunks:&[[char;3]] =// SAFETY: The slice length (6) is a multiple of 3unsafe{ 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

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

The remainder is meaningful in the division sense. Givenlet (chunks, remainder) = slice.as_chunks(), then:

• chunks.len() equalsslice.len() / N,
• remainder.len() equalsslice.len() % N, and
• slice.len() equalschunks.len() * N + remainder.len().

You can flatten the chunks back into a slice-of-T withas_flattened.

§Panics

Panics ifN is zero.

Note that this check is against a const generic parameter, not a runtimevalue, and thus a particular monomorphization will either always panicor it will never panic.

§Examples

letslice = ['l','o','r','e','m'];let(chunks, remainder) = slice.as_chunks();assert_eq!(chunks,&[['l','o'], ['r','e']]);assert_eq!(remainder,&['m']);

If you expect the slice to be an exact multiple, you can combinelet-else with an empty slice pattern:

letslice = ['R','u','s','t'];let(chunks, []) = slice.as_chunks::<2>()else{panic!("slice didn't have even length")};assert_eq!(chunks,&[['R','u'], ['s','t']]);

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

The remainder is meaningful in the division sense. Givenlet (remainder, chunks) = slice.as_rchunks(), then:

• remainder.len() equalsslice.len() % N,
• chunks.len() equalsslice.len() / N, and
• slice.len() equalschunks.len() * N + remainder.len().

You can flatten the chunks back into a slice-of-T withas_flattened.

§Panics

Panics ifN is zero.

Note that this check is against a const generic parameter, not a runtimevalue, and thus a particular monomorphization will either always panicor it will never panic.

§Examples

letslice = ['l','o','r','e','m'];let(remainder, chunks) = slice.as_rchunks();assert_eq!(remainder,&['l']);assert_eq!(chunks,&[['o','r'], ['e','m']]);

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

This is the inverse operation toas_flattened_mut.

As this isunsafe, consider whether you could useas_chunks_mut oras_rchunks_mut instead, perhaps via something likeif let (chunks, []) = slice.as_chunks_mut() orlet (chunks, []) = slice.as_chunks_mut() else { unreachable!() };.

§Safety

This may only be called when

• The slice splits exactly intoN-element chunks (akaself.len() % N == 0).
• N != 0.

§Examples

letslice:&mut[char] =&mut['l','o','r','e','m','!'];letchunks:&mut[[char;1]] =// SAFETY: 1-element chunks never have remainderunsafe{ slice.as_chunks_unchecked_mut() };chunks[0] = ['L'];assert_eq!(chunks,&[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);letchunks:&mut[[char;3]] =// SAFETY: The slice length (6) is a multiple of 3unsafe{ 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

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

The remainder is meaningful in the division sense. Givenlet (chunks, remainder) = slice.as_chunks_mut(), then:

• chunks.len() equalsslice.len() / N,
• remainder.len() equalsslice.len() % N, and
• slice.len() equalschunks.len() * N + remainder.len().

You can flatten the chunks back into a slice-of-T withas_flattened_mut.

§Panics

Panics ifN is zero.

Note that this check is against a const generic parameter, not a runtimevalue, and thus a particular monomorphization will either always panicor it will never panic.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;let(chunks, remainder) = v.as_chunks_mut();remainder[0] =9;forchunkinchunks {*chunk = [count;2];    count +=1;}assert_eq!(v,&[1,1,2,2,9]);

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

The remainder is meaningful in the division sense. Givenlet (remainder, chunks) = slice.as_rchunks_mut(), then:

• remainder.len() equalsslice.len() % N,
• chunks.len() equalsslice.len() / N, and
• slice.len() equalschunks.len() * N + remainder.len().

You can flatten the chunks back into a slice-of-T withas_flattened_mut.

§Panics

Panics ifN is zero.

Note that this check is against a const generic parameter, not a runtimevalue, and thus a particular monomorphization will either always panicor it will never panic.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;let(remainder, chunks) = v.as_rchunks_mut();remainder[0] =9;forchunkinchunks {*chunk = [count;2];    count +=1;}assert_eq!(v,&[9,1,1,2,2]);

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

This is the const generic equivalent ofwindows.

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

§Panics

Panics ifN is zero. This check will most probably get changed to a compile timeerror before this method gets stabilized.

§Examples

#![feature(array_windows)]letslice = [0,1,2,3];letmutiter = 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 overchunk_size elements of the slice at a time, starting at the endof the slice.

The chunks are slices and do not overlap. Ifchunk_size does not divide the length of theslice, then the last chunk will not have lengthchunk_size.

Seerchunks_exact for a variant of this iterator that returns chunks of always exactlychunk_size elements, andchunks for the same iterator but starting at the beginningof the slice.

If yourchunk_size is a constant, consider usingas_rchunks instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letslice = ['l','o','r','e','m'];letmutiter = 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 overchunk_size elements of the slice at a time, starting at the endof the slice.

The chunks are mutable slices, and do not overlap. Ifchunk_size does not divide thelength of the slice, then the last chunk will not have lengthchunk_size.

Seerchunks_exact_mut for a variant of this iterator that returns chunks of alwaysexactlychunk_size elements, andchunks_mut for the same iterator but starting at thebeginning of the slice.

If yourchunk_size is a constant, consider usingas_rchunks_mut instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;forchunkinv.rchunks_mut(2) {foreleminchunk.iter_mut() {*elem += count;    }    count +=1;}assert_eq!(v,&[3,2,2,1,1]);

Returns an iterator overchunk_size elements of the slice at a time, starting at theend of the slice.

The chunks are slices and do not overlap. Ifchunk_size does not divide the length of theslice, then the last up tochunk_size-1 elements will be omitted and can be retrievedfrom theremainder function of the iterator.

Due to each chunk having exactlychunk_size elements, the compiler can often optimize theresulting code better than in the case ofrchunks.

Seerchunks for a variant of this iterator that also returns the remainder as a smallerchunk, andchunks_exact for the same iterator but starting at the beginning of theslice.

If yourchunk_size is a constant, consider usingas_rchunks instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letslice = ['l','o','r','e','m'];letmutiter = 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 overchunk_size elements of the slice at a time, starting at the endof the slice.

The chunks are mutable slices, and do not overlap. Ifchunk_size does not divide thelength of the slice, then the last up tochunk_size-1 elements will be omitted and can beretrieved from theinto_remainder function of the iterator.

Due to each chunk having exactlychunk_size elements, the compiler can often optimize theresulting code better than in the case ofchunks_mut.

Seerchunks_mut for a variant of this iterator that also returns the remainder as asmaller chunk, andchunks_exact_mut for the same iterator but starting at the beginningof the slice.

If yourchunk_size is a constant, consider usingas_rchunks_mut instead, which willgive references to arrays of exactly that length, rather than slices.

§Panics

Panics ifchunk_size is zero.

§Examples

letv =&mut[0,0,0,0,0];letmutcount =1;forchunkinv.rchunks_exact_mut(2) {foreleminchunk.iter_mut() {*elem += count;    }    count +=1;}assert_eq!(v,&[0,2,2,1,1]);

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

The predicate is called for every pair of consecutive elements,meaning that it is called onslice[0] andslice[1],followed byslice[1] andslice[2], and so on.

§Examples

letslice =&[1,1,1,3,3,2,2,2];letmutiter = slice.chunk_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:

letslice =&[1,1,2,3,2,3,2,3,4];letmutiter = slice.chunk_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);

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

The predicate is called for every pair of consecutive elements,meaning that it is called onslice[0] andslice[1],followed byslice[1] andslice[2], and so on.

§Examples

letslice =&mut[1,1,1,3,3,2,2,2];letmutiter = slice.chunk_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:

letslice =&mut[1,1,2,3,2,3,2,3,4];letmutiter = slice.chunk_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) (excludingthe indexmid itself) and the second will contain allindices from[mid, len) (excluding the indexlen itself).

§Panics

Panics ifmid > len. For a non-panicking alternative seesplit_at_checked.

§Examples

letv = ['a','b','c'];{let(left, right) = v.split_at(0);assert_eq!(left, []);assert_eq!(right, ['a','b','c']);}{let(left, right) = v.split_at(2);assert_eq!(left, ['a','b']);assert_eq!(right, ['c']);}{let(left, right) = v.split_at(3);assert_eq!(left, ['a','b','c']);assert_eq!(right, []);}

Divides one mutable slice into two at an index.

The first will contain all indices from[0, mid) (excludingthe indexmid itself) and the second will contain allindices from[mid, len) (excluding the indexlen itself).

§Panics

Panics ifmid > len. For a non-panicking alternative seesplit_at_mut_checked.

§Examples

letmutv = [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]);

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

The first will contain all indices from[0, mid) (excludingthe indexmid itself) and the second will contain allindices from[mid, len) (excluding the indexlen itself).

For a safe alternative seesplit_at.

§Safety

Calling this method with an out-of-bounds index isundefined behavioreven if the resulting reference is not used. The caller has to ensure that0 <= mid <= self.len().

§Examples

letv = ['a','b','c'];unsafe{let(left, right) = v.split_at_unchecked(0);assert_eq!(left, []);assert_eq!(right, ['a','b','c']);}unsafe{let(left, right) = v.split_at_unchecked(2);assert_eq!(left, ['a','b']);assert_eq!(right, ['c']);}unsafe{let(left, right) = v.split_at_unchecked(3);assert_eq!(left, ['a','b','c']);assert_eq!(right, []);}

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

The first will contain all indices from[0, mid) (excludingthe indexmid itself) and the second will contain allindices from[mid, len) (excluding the indexlen itself).

For a safe alternative seesplit_at_mut.

§Safety

Calling this method with an out-of-bounds index isundefined behavioreven if the resulting reference is not used. The caller has to ensure that0 <= mid <= self.len().

§Examples

letmutv = [1,0,3,0,5,6];// scoped to restrict the lifetime of the borrowsunsafe{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]);

Divides one slice into two at an index, returningNone if the slice istoo short.

Ifmid ≤ len returns a pair of slices where the first will contain allindices from[0, mid) (excluding the indexmid itself) and thesecond will contain all indices from[mid, len) (excluding the indexlen itself).

Otherwise, ifmid > len, returnsNone.

§Examples

letv = [1, -2,3, -4,5, -6];{let(left, right) = v.split_at_checked(0).unwrap();assert_eq!(left, []);assert_eq!(right, [1, -2,3, -4,5, -6]);}{let(left, right) = v.split_at_checked(2).unwrap();assert_eq!(left, [1, -2]);assert_eq!(right, [3, -4,5, -6]);}{let(left, right) = v.split_at_checked(6).unwrap();assert_eq!(left, [1, -2,3, -4,5, -6]);assert_eq!(right, []);}assert_eq!(None, v.split_at_checked(7));

Divides one mutable slice into two at an index, returningNone if theslice is too short.

Ifmid ≤ len returns a pair of slices where the first will contain allindices from[0, mid) (excluding the indexmid itself) and thesecond will contain all indices from[mid, len) (excluding the indexlen itself).

Otherwise, ifmid > len, returnsNone.

§Examples

letmutv = [1,0,3,0,5,6];if letSome((left, right)) = v.split_at_mut_checked(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]);assert_eq!(None, v.split_at_mut_checked(7));

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

§Examples

letslice = [10,40,33,20];letmutiter = 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 itemreturned by the iterator. Similarly, if the last element in the sliceis matched, an empty slice will be the last item returned by theiterator:

letslice = [10,40,33];letmutiter = 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 bepresent between them:

letslice = [10,6,33,20];letmutiter = 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 thatmatchpred. The matched element is not contained in the subslices.

§Examples

letmutv = [10,40,30,20,60,50];forgroupinv.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 matchpred. The matched element is contained in the end of the previoussubslice as a terminator.

§Examples

letslice = [10,40,33,20];letmutiter = 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.

letslice = [3,10,40,33];letmutiter = 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 thatmatchpred. The matched element is contained in the previoussubslice as a terminator.

§Examples

letmutv = [10,40,30,20,60,50];forgroupinv.split_inclusive_mut(|num|*num %3==0) {letterminator_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 matchpred, starting at the end of the slice and working backwards.The matched element is not contained in the subslices.

§Examples

letslice = [11,22,33,0,44,55];letmutiter = 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 withsplit(), if the first or last element is matched, an emptyslice will be the first (or last) item returned by the iterator.

letv =&[0,1,1,2,3,5,8];letmutit = 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 thatmatchpred, starting at the end of the slice and workingbackwards. The matched element is not contained in the subslices.

§Examples

letmutv = [100,400,300,200,600,500];letmutcount =0;forgroupinv.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 matchpred, limited to returning at mostn items. The matched element isnot contained in the subslices.

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

§Examples

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

letv = [10,40,30,20,60,50];forgroupinv.splitn(2, |num|*num %3==0) {println!("{group:?}");}

Returns an iterator over mutable subslices separated by elements that matchpred, limited to returning at mostn items. The matched element isnot contained in the subslices.

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

§Examples

letmutv = [10,40,30,20,60,50];forgroupinv.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 matchpred limited to returning at mostn items. This starts at the end ofthe slice and works backwards. The matched element is not contained inthe subslices.

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

§Examples

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

letv = [10,40,30,20,60,50];forgroupinv.rsplitn(2, |num|*num %3==0) {println!("{group:?}");}

Returns an iterator over subslices separated by elements that matchpred limited to returning at mostn items. This starts at the end ofthe slice and works backwards. The matched element is not contained inthe subslices.

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

§Examples

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

Splits the slice on the first element that matches the specifiedpredicate.

If any matching elements are present in the slice, returns the prefixbefore the match and suffix after. The matching element itself is notincluded. If no elements match, returnsNone.

§Examples

#![feature(slice_split_once)]lets = [1,2,3,2,4];assert_eq!(s.split_once(|&x| x ==2),Some((&[1][..],&[3,2,4][..])));assert_eq!(s.split_once(|&x| x ==0),None);

Splits the slice on the last element that matches the specifiedpredicate.

If any matching elements are present in the slice, returns the prefixbefore the match and suffix after. The matching element itself is notincluded. If no elements match, returnsNone.

§Examples

#![feature(slice_split_once)]lets = [1,2,3,2,4];assert_eq!(s.rsplit_once(|&x| x ==2),Some((&[1,2,3][..],&[4][..])));assert_eq!(s.rsplit_once(|&x| x ==0),None);

Returnstrue if the slice contains an element with the given value.

This operation isO(n).

Note that if you have a sorted slice,binary_search may be faster.

§Examples

letv = [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 comparewith one (for example,String implementsPartialEq<str>), you canuseiter().any:

letv = [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"));

Returnstrue ifneedle is a prefix of the slice or equal to the slice.

§Examples

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

Always returnstrue ifneedle is an empty slice:

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

Returnstrue ifneedle is a suffix of the slice or equal to the slice.

§Examples

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

Always returnstrue ifneedle is an empty slice:

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

Returns a subslice with the prefix removed.

If the slice starts withprefix, returns the subslice after the prefix, wrapped inSome.Ifprefix is empty, simply returns the original slice. Ifprefix is equal to theoriginal slice, returns an empty slice.

If the slice does not start withprefix, returnsNone.

§Examples

letv =&[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(&[10,40,30]),Some(&[][..]));assert_eq!(v.strip_prefix(&[50]),None);assert_eq!(v.strip_prefix(&[10,50]),None);letprefix :&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 withsuffix, returns the subslice before the suffix, wrapped inSome.Ifsuffix is empty, simply returns the original slice. Ifsuffix is equal to theoriginal slice, returns an empty slice.

If the slice does not end withsuffix, returnsNone.

§Examples

letv =&[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(&[10,40,30]),Some(&[][..]));assert_eq!(v.strip_suffix(&[50]),None);assert_eq!(v.strip_suffix(&[50,30]),None);

Returns a subslice with the prefix and suffix removed.

If the slice starts withprefix and ends withsuffix, returns the subslice after theprefix and before the suffix, wrapped inSome.

If the slice does not start withprefix or does not end withsuffix, returnsNone.

§Examples

#![feature(strip_circumfix)]letv =&[10,50,40,30];assert_eq!(v.strip_circumfix(&[10],&[30]),Some(&[50,40][..]));assert_eq!(v.strip_circumfix(&[10],&[40,30]),Some(&[50][..]));assert_eq!(v.strip_circumfix(&[10,50],&[40,30]),Some(&[][..]));assert_eq!(v.strip_circumfix(&[50],&[30]),None);assert_eq!(v.strip_circumfix(&[10],&[40]),None);assert_eq!(v.strip_circumfix(&[],&[40,30]),Some(&[10,50][..]));assert_eq!(v.strip_circumfix(&[10,50],&[]),Some(&[40,30][..]));

Returns a subslice with the optional prefix removed.

If the slice starts withprefix, returns the subslice after the prefix. Ifprefixis empty or the slice does not start withprefix, simply returns the original slice.Ifprefix is equal to the original slice, returns an empty slice.

§Examples

#![feature(trim_prefix_suffix)]letv =&[10,40,30];// Prefix present - removes itassert_eq!(v.trim_prefix(&[10]),&[40,30][..]);assert_eq!(v.trim_prefix(&[10,40]),&[30][..]);assert_eq!(v.trim_prefix(&[10,40,30]),&[][..]);// Prefix absent - returns original sliceassert_eq!(v.trim_prefix(&[50]),&[10,40,30][..]);assert_eq!(v.trim_prefix(&[10,50]),&[10,40,30][..]);letprefix :&str ="he";assert_eq!(b"hello".trim_prefix(prefix.as_bytes()),b"llo".as_ref());

Returns a subslice with the optional suffix removed.

If the slice ends withsuffix, returns the subslice before the suffix. Ifsuffixis empty or the slice does not end withsuffix, simply returns the original slice.Ifsuffix is equal to the original slice, returns an empty slice.

§Examples

#![feature(trim_prefix_suffix)]letv =&[10,40,30];// Suffix present - removes itassert_eq!(v.trim_suffix(&[30]),&[10,40][..]);assert_eq!(v.trim_suffix(&[40,30]),&[10][..]);assert_eq!(v.trim_suffix(&[10,40,30]),&[][..]);// Suffix absent - returns original sliceassert_eq!(v.trim_suffix(&[50]),&[10,40,30][..]);assert_eq!(v.trim_suffix(&[50,30]),&[10,40,30][..]);

Binary searches this slice for a given element.If the slice is not sorted, the returned result is unspecified andmeaningless.

If the value is found thenResult::Ok is returned, containing theindex of the matching element. If there are multiple matches, then anyone of the matches could be returned. The index is chosendeterministically, but is subject to change in future versions of Rust.If the value is not found thenResult::Err is returned, containingthe index where a matching element could be inserted while maintainingsorted order.

See alsobinary_search_by,binary_search_by_key, andpartition_point.

§Examples

Looks up a series of four elements. The first is found, with auniquely determined position; the second and third are notfound; the fourth could match any position in[1, 4].

lets = [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));letr = s.binary_search(&1);assert!(matchr {Ok(1..=4) =>true,_=>false, });

If you want to find that wholerange of matching items, rather thanan arbitrary matching one, that can be done usingpartition_point:

lets = [0,1,1,1,1,2,3,5,8,13,21,34,55];letlow = s.partition_point(|x| x <&1);assert_eq!(low,1);lethigh = s.partition_point(|x| x <=&1);assert_eq!(high,5);letr = s.binary_search(&1);assert!((low..high).contains(&r.unwrap()));assert!(s[..low].iter().all(|&x| x <1));assert!(s[low..high].iter().all(|&x| x ==1));assert!(s[high..].iter().all(|&x| x >1));// For something not found, the "range" of equal items is emptyassert_eq!(s.partition_point(|x| x <&11),9);assert_eq!(s.partition_point(|x| x <=&11),9);assert_eq!(s.binary_search(&11),Err(9));

If you want to insert an item to a sorted vector, while maintainingsort order, consider usingpartition_point:

letmuts =vec![0,1,1,1,1,2,3,5,8,13,21,34,55];letnum =42;letidx = s.partition_point(|&x| x <= num);// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`// to shift less elements.s.insert(idx, num);assert_eq!(s, [0,1,1,1,1,2,3,5,8,13,21,34,42,55]);

Binary searches this slice with a comparator function.

The comparator function should return an order code that indicateswhether its argument isLess,Equal orGreater the desiredtarget.If the slice is not sorted or if the comparator function does notimplement an order consistent with the sort order of the underlyingslice, the returned result is unspecified and meaningless.

If the value is found thenResult::Ok is returned, containing theindex of the matching element. If there are multiple matches, then anyone of the matches could be returned. The index is chosendeterministically, but is subject to change in future versions of Rust.If the value is not found thenResult::Err is returned, containingthe index where a matching element could be inserted while maintainingsorted order.

See alsobinary_search,binary_search_by_key, andpartition_point.

§Examples

Looks up a series of four elements. The first is found, with auniquely determined position; the second and third are notfound; the fourth could match any position in[1, 4].

lets = [0,1,1,1,1,2,3,5,8,13,21,34,55];letseek =13;assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)),Ok(9));letseek =4;assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)),Err(7));letseek =100;assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)),Err(13));letseek =1;letr = s.binary_search_by(|probe| probe.cmp(&seek));assert!(matchr {Ok(1..=4) =>true,_=>false, });

Binary searches this slice with a key extraction function.

Assumes that the slice is sorted by the key, for instance withsort_by_key using the same key extraction function.If the slice is not sorted by the key, the returned result isunspecified and meaningless.

If the value is found thenResult::Ok is returned, containing theindex of the matching element. If there are multiple matches, then anyone of the matches could be returned. The index is chosendeterministically, but is subject to change in future versions of Rust.If the value is not found thenResult::Err is returned, containingthe index where a matching element could be inserted while maintainingsorted order.

See alsobinary_search,binary_search_by, andpartition_point.

§Examples

Looks up a series of four elements in a slice of pairs sorted bytheir second elements. The first is found, with a uniquelydetermined position; the second and third are not found; thefourth could match any position in[1, 4].

lets = [(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));letr = s.binary_search_by_key(&1, |&(a, b)| b);assert!(matchr {Ok(1..=4) =>true,_=>false, });

Sorts the slice in ascending orderwithout preserving the initial order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does notallocate), andO(n * log(n)) worst-case.

If the implementation ofOrd forT does not implement atotal order, the functionmay panic; even if the function exits normally, the resulting order of elements in the sliceis unspecified. See also the note on panicking below.

For example|a, b| (a - b).cmp(a) is a comparison function that is neither transitive norreflexive nor total,a < b < c < a witha = 1, b = 2, c = 3. For more information andexamples see theOrd documentation.

All original elements will remain in the slice and any possible modifications via interiormutability are observed in the input. Same is true if the implementation ofOrd forT panics.

Sorting types that only implementPartialOrd such asf32 andf64 requireadditional precautions. For example,f32::NAN != f32::NAN, which doesn’t fulfill thereflexivity requirement ofOrd. By using an alternative comparison function withslice::sort_unstable_by such asf32::total_cmp orf64::total_cmp that defines atotal order users can sort slices containing floating-point values. Alternatively, if allvalues in the slice are guaranteed to be in a subset for whichPartialOrd::partial_cmpforms atotal order, it’s possible to sort the slice withsort_unstable_by(|a, b| a.partial_cmp(b).unwrap()).

§Current implementation

The current implementation is based onipnsort by Lukas Bergdoll and Orson Peters, whichcombines the fast average case of quicksort with the fast worst case of heapsort, achievinglinear time on fully sorted and reversed inputs. On inputs with k distinct elements, theexpected time to sort the data isO(n * log(k)).

It is typically faster than stable sorting, except in a few special cases, e.g., when theslice is partially sorted.

§Panics

May panic if the implementation ofOrd forT does not implement atotal order, or iftheOrd implementation panics.

§Examples

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

Sorts the slice in ascending order with a comparison function,without preserving theinitial order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does notallocate), andO(n * log(n)) worst-case.

If the comparison functioncompare does not implement atotal order, the functionmay panic; even if the function exits normally, the resulting order of elements in the sliceis unspecified. See also the note on panicking below.

For example|a, b| (a - b).cmp(a) is a comparison function that is neither transitive norreflexive nor total,a < b < c < a witha = 1, b = 2, c = 3. For more information andexamples see theOrd documentation.

All original elements will remain in the slice and any possible modifications via interiormutability are observed in the input. Same is true ifcompare panics.

§Current implementation

The current implementation is based onipnsort by Lukas Bergdoll and Orson Peters, whichcombines the fast average case of quicksort with the fast worst case of heapsort, achievinglinear time on fully sorted and reversed inputs. On inputs with k distinct elements, theexpected time to sort the data isO(n * log(k)).

It is typically faster than stable sorting, except in a few special cases, e.g., when theslice is partially sorted.

§Panics

May panic if thecompare does not implement atotal order, or ifthecompare itself panics.

§Examples

letmutv = [4, -5,1, -3,2];v.sort_unstable_by(|a, b| a.cmp(b));assert_eq!(v, [-5, -3,1,2,4]);// reverse sortingv.sort_unstable_by(|a, b| b.cmp(a));assert_eq!(v, [4,2,1, -3, -5]);

Sorts the slice in ascending order with a key extraction function,without preservingthe initial order of equal elements.

This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does notallocate), andO(n * log(n)) worst-case.

If the implementation ofOrd forK does not implement atotal order, the functionmay panic; even if the function exits normally, the resulting order of elements in the sliceis unspecified. See also the note on panicking below.

For example|a, b| (a - b).cmp(a) is a comparison function that is neither transitive norreflexive nor total,a < b < c < a witha = 1, b = 2, c = 3. For more information andexamples see theOrd documentation.

All original elements will remain in the slice and any possible modifications via interiormutability are observed in the input. Same is true if the implementation ofOrd forK panics.

§Current implementation

The current implementation is based onipnsort by Lukas Bergdoll and Orson Peters, whichcombines the fast average case of quicksort with the fast worst case of heapsort, achievinglinear time on fully sorted and reversed inputs. On inputs with k distinct elements, theexpected time to sort the data isO(n * log(k)).

It is typically faster than stable sorting, except in a few special cases, e.g., when theslice is partially sorted.

§Panics

May panic if the implementation ofOrd forK does not implement atotal order, or iftheOrd implementation panics.

§Examples

letmutv = [4i32, -5,1, -3,2];v.sort_unstable_by_key(|k| k.abs());assert_eq!(v, [1,2, -3,4, -5]);

Reorders the slice such that the element atindex is at a sort-order position. Allelements beforeindex will be<= to this value, and all elements after will be>= toit.

This reordering is unstable (i.e. any element that compares equal to the nth element may endup at that position), in-place (i.e. does not allocate), and runs inO(n) time. Thisfunction is also known as “kth element” in other libraries.

Returns a triple that partitions the reordered slice:

• The unsorted subslice beforeindex, whose elements all satisfyx <= self[index].

• The element atindex.

• The unsorted subslice afterindex, whose elements all satisfyx >= self[index].

§Current implementation

The current algorithm is an introselect implementation based onipnsort by Lukas Bergdolland Orson Peters, which is also the basis forsort_unstable. The fallback algorithm isMedian of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtimefor all inputs.

§Panics

Panics whenindex >= len(), and so always panics on empty slices.

May panic if the implementation ofOrd forT does not implement atotal order.

§Examples

letmutv = [-5i32,4,2, -3,1];// Find the items `<=` to the median, the median itself, and the items `>=` to it.let(lesser, median, greater) = v.select_nth_unstable(2);assert!(lesser == [-3, -5] || lesser == [-5, -3]);assert_eq!(median,&mut1);assert!(greater == [4,2] || greater == [2,4]);// 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]);

Reorders the slice with a comparator function such that the element atindex is at asort-order position. All elements beforeindex will be<= to this value, and allelements after will be>= to it, according to the comparator function.

This reordering is unstable (i.e. any element that compares equal to the nth element may endup at that position), in-place (i.e. does not allocate), and runs inO(n) time. Thisfunction is also known as “kth element” in other libraries.

Returns a triple partitioning the reordered slice:

• The unsorted subslice beforeindex, whose elements all satisfycompare(x, self[index]).is_le().

• The element atindex.

• The unsorted subslice afterindex, whose elements all satisfycompare(x, self[index]).is_ge().

§Current implementation

The current algorithm is an introselect implementation based onipnsort by Lukas Bergdolland Orson Peters, which is also the basis forsort_unstable. The fallback algorithm isMedian of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtimefor all inputs.

§Panics

Panics whenindex >= len(), and so always panics on empty slices.

May panic ifcompare does not implement atotal order.

§Examples

letmutv = [-5i32,4,2, -3,1];// Find the items `>=` to the median, the median itself, and the items `<=` to it, by using// a reversed comparator.let(before, median, after) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));assert!(before == [4,2] || before == [2,4]);assert_eq!(median,&mut1);assert!(after == [-3, -5] || after == [-5, -3]);// 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]);

Reorders the slice with a key extraction function such that the element atindex is at asort-order position. All elements beforeindex will have keys<= to the key atindex,and all elements after will have keys>= to it.

This reordering is unstable (i.e. any element that compares equal to the nth element may endup at that position), in-place (i.e. does not allocate), and runs inO(n) time. Thisfunction is also known as “kth element” in other libraries.

Returns a triple partitioning the reordered slice:

• The unsorted subslice beforeindex, whose elements all satisfyf(x) <= f(self[index]).

• The element atindex.

• The unsorted subslice afterindex, whose elements all satisfyf(x) >= f(self[index]).

§Current implementation

The current algorithm is an introselect implementation based onipnsort by Lukas Bergdolland Orson Peters, which is also the basis forsort_unstable. The fallback algorithm isMedian of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtimefor all inputs.

§Panics

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

May panic ifK: Ord does not implement a total order.

§Examples

letmutv = [-5i32,4,1, -3,2];// Find the items `<=` to the absolute median, the absolute median itself, and the items// `>=` to it.let(lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());assert!(lesser == [1,2] || lesser == [2,1]);assert_eq!(median,&mut-3);assert!(greater == [4, -5] || greater == [-5,4]);// 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]);

Moves all consecutive repeated elements to the end of the slice according to thePartialEq 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)]letmutslice = [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]);

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

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

Thesame_bucket function is passed references to two elements from the slice andmust determine if the elements compare equal. The elements are passed in opposite orderfrom their order in the slice, so ifsame_bucket(a, b) returnstrue,a is movedat the end of the slice.

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

§Examples

#![feature(slice_partition_dedup)]letmutslice = ["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"]);

Moves all but the first of consecutive elements to the end of the slice that resolveto 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)]letmutslice = [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 firstmid elements of theslice move to the end while the lastself.len() - mid elements move tothe front.

After callingrotate_left, the element previously at indexmid willbecome the first element in the slice.

§Panics

This function will panic ifmid is greater than the length of theslice. Note thatmid == self.len() doesnot panic and is a no-oprotation.

§Complexity

Takes linear (inself.len()) time.

§Examples

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

Rotating a subslice:

letmuta = ['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 firstself.len() - kelements of the slice move to the end while the lastk elements moveto the front.

After callingrotate_right, the element previously at indexself.len() - k will become the first element in the slice.

§Panics

This function will panic ifk is greater than the length of theslice. Note thatk == self.len() doesnot panic and is a no-oprotation.

§Complexity

Takes linear (inself.len()) time.

§Examples

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

Rotating a subslice:

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

Fillsself with elements by cloningvalue.

§Examples

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

Fillsself with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d ratherClone a given value, usefill. If you want to use theDefaulttrait to generate values, you can passDefault::default as theargument.

§Examples

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

Copies the elements fromsrc intoself.

The length ofsrc must be the same asself.

§Panics

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

§Examples

Cloning two elements from a slice into another:

letsrc = [1,2,3,4];letmutdst = [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 noimmutable references to a particular piece of data in a particularscope. Because of this, attempting to useclone_from_slice on asingle slice will result in a compile failure:

letmutslice = [1,2,3,4,5];slice[..2].clone_from_slice(&slice[3..]);// compile fail!

To work around this, we can usesplit_at_mut to create two distinctsub-slices from a slice:

letmutslice = [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 fromsrc intoself, using a memcpy.

The length ofsrc must be the same asself.

IfT does not implementCopy, useclone_from_slice.

§Panics

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

§Examples

Copying two elements from a slice into another:

letsrc = [1,2,3,4];letmutdst = [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 noimmutable references to a particular piece of data in a particularscope. Because of this, attempting to usecopy_from_slice on asingle slice will result in a compile failure:

letmutslice = [1,2,3,4,5];slice[..2].copy_from_slice(&slice[3..]);// compile fail!

To work around this, we can usesplit_at_mut to create two distinctsub-slices from a slice:

letmutslice = [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 withinself to copy from.dest is the startingindex of the range withinself to copy to, which will have the samelength assrc. The two ranges may overlap. The ends of the two rangesmust be less than or equal toself.len().

§Panics

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

§Examples

Copying four bytes within a slice:

letmutbytes =*b"Hello, World!";bytes.copy_within(1..5,8);assert_eq!(&bytes,b"Hello, Wello!");

Swaps all elements inself with those inother.

The length ofother must be the same asself.

§Panics

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

§Example

Swapping two elements across slices:

letmutslice1 = [0,0];letmutslice2 = [1,2,3,4];slice1.swap_with_slice(&mutslice2[2..]);assert_eq!(slice1, [3,4]);assert_eq!(slice2, [1,2,0,0]);