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

An empty slice returnstrue.

If this sliceis_ascii, returns it as a slice ofASCII characters, otherwise returnsNone.

Converts this slice of bytes into a slice of ASCII characters,without checking whether they’re valid.

§Safety

Every byte in the slice must be in0..=127, or else this is UB.

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

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

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

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

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

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

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

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

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

§Examples

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

Returns a byte slice with leading ASCII whitespace bytes removed.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!(b" \t hello world\n".trim_ascii_start(),b"hello world\n");assert_eq!(b"  ".trim_ascii_start(),b"");assert_eq!(b"".trim_ascii_start(),b"");

Returns a byte slice with trailing ASCII whitespace bytes removed.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!(b"\r hello world\n ".trim_ascii_end(),b"\r hello world");assert_eq!(b"  ".trim_ascii_end(),b"");assert_eq!(b"".trim_ascii_end(),b"");

Returns a byte slice with leading and trailing ASCII whitespace bytesremoved.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!(b"\r hello world\n ".trim_ascii(),b"hello world");assert_eq!(b"  ".trim_ascii(),b"");assert_eq!(b"".trim_ascii(),b"");

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

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

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

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

letmutslice = [1,2,3,4,5];{let(left, right) = slice.split_at_mut(2);    left.swap_with_slice(&mutright[1..]);}assert_eq!(slice, [4,5,3,1,2]);

Transmutes the slice to a slice of another type, ensuring alignment of the types ismaintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middleslice of a new type, and the suffix slice. The middle part will be as big as possible underthe given alignment constraint and element size.

This method has no purpose when either input elementT or output elementU arezero-sized and will return the original slice without splitting anything.

§Safety

This method is essentially atransmute with respect to the elements in the returnedmiddle slice, so all the usual caveats pertaining totransmute::<T, U> also apply here.

§Examples

Basic usage:

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

Transmutes the mutable slice to a mutable slice of another type, ensuring alignment of thetypes is maintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middleslice of a new type, and the suffix slice. The middle part will be as big as possible underthe given alignment constraint and element size.

This method has no purpose when either input elementT or output elementU arezero-sized and will return the original slice without splitting anything.

§Safety

This method is essentially atransmute with respect to the elements in the returnedmiddle slice, so all the usual caveats pertaining totransmute::<T, U> also apply here.

§Examples

Basic usage:

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

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

This is a safe wrapper aroundslice::align_to, so inherits the sameguarantees as that method.

§Panics

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

At the time of writing, the trait restrictions onSimd<T, LANES> keepsthat from ever happening, as only power-of-two numbers of lanes aresupported. It’s possible that, in the future, those restrictions mightbe lifted in a way that would make it possible to see panics from thismethod for something likeLANES == 3.

§Examples

#![feature(portable_simd)]usecore::simd::prelude::*;letshort =&[1,2,3];let(prefix, middle, suffix) = short.as_simd::<4>();assert_eq!(middle, []);// Not enough elements for anything in the middle// They might be split in any possible way between prefix and suffixletit = prefix.iter().chain(suffix).copied();assert_eq!(it.collect::<Vec<_>>(),vec![1,2,3]);fnbasic_simd_sum(x:&[f32]) -> f32 {usestd::ops::Add;let(prefix, middle, suffix) = x.as_simd();letsums = f32x4::from_array([        prefix.iter().copied().sum(),0.0,0.0,        suffix.iter().copied().sum(),    ]);letsums = middle.iter().copied().fold(sums, f32x4::add);    sums.reduce_sum()}letnumbers: Vec<f32> = (1..101).map(|x| xas _).collect();assert_eq!(basic_simd_sum(&numbers[1..99]),4949.0);

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

This is a safe wrapper aroundslice::align_to_mut, so inherits the sameguarantees as that method.

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

§Panics

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

At the time of writing, the trait restrictions onSimd<T, LANES> keepsthat from ever happening, as only power-of-two numbers of lanes aresupported. It’s possible that, in the future, those restrictions mightbe lifted in a way that would make it possible to see panics from thismethod for something likeLANES == 3.

Checks if the elements of this slice are sorted.

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

Note that ifSelf::Item is onlyPartialOrd, but notOrd, the above definitionimplies that this function returnsfalse if any two consecutive items are notcomparable.

§Examples

letempty: [i32;0] = [];assert!([1,2,2,9].is_sorted());assert!(![1,3,2,4].is_sorted());assert!([0].is_sorted());assert!(empty.is_sorted());assert!(![0.0,1.0, f32::NAN].is_sorted());

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

Instead of usingPartialOrd::partial_cmp, this function uses the givencomparefunction to determine whether two elements are to be considered in sorted order.

§Examples

assert!([1,2,2,9].is_sorted_by(|a, b| a <= b));assert!(![1,2,2,9].is_sorted_by(|a, b| a < b));assert!([0].is_sorted_by(|a, b|true));assert!([0].is_sorted_by(|a, b|false));letempty: [i32;0] = [];assert!(empty.is_sorted_by(|a, b|false));assert!(empty.is_sorted_by(|a, b|true));

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

Instead of comparing the slice’s elements directly, this function compares the keys of theelements, as determined byf. Apart from that, it’s equivalent tois_sorted; see itsdocumentation for more information.

§Examples

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

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

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

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

See alsobinary_search,binary_search_by, andbinary_search_by_key.

§Examples

letv = [1,2,3,3,5,6,7];leti = v.partition_point(|&x| x <5);assert_eq!(i,4);assert!(v[..i].iter().all(|&x| x <5));assert!(v[i..].iter().all(|&x| !(x <5)));

If all elements of the slice match the predicate, including if the sliceis empty, then the length of the slice will be returned:

leta = [2,4,8];assert_eq!(a.partition_point(|x| x <&100), a.len());leta: [i32;0] = [];assert_eq!(a.partition_point(|x| x <&100),0);

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

letmuts =vec![0,1,1,1,1,2,3,5,8,13,21,34,55];letnum =42;letidx = s.partition_point(|&x| x <= num);s.insert(idx, num);assert_eq!(s, [0,1,1,1,1,2,3,5,8,13,21,34,42,55]);

Removes the subslice corresponding to the given rangeand returns a reference to it.

ReturnsNone and does not modify the slice if the givenrange is out of bounds.

Note that this method only accepts one-sided ranges such as2.. or..6, but not2..6.

§Examples

Splitting off the first three elements of a slice:

letmutslice:&[_] =&['a','b','c','d'];letmutfirst_three = slice.split_off(..3).unwrap();assert_eq!(slice,&['d']);assert_eq!(first_three,&['a','b','c']);

Splitting off a slice starting with the third element:

letmutslice:&[_] =&['a','b','c','d'];letmuttail = slice.split_off(2..).unwrap();assert_eq!(slice,&['a','b']);assert_eq!(tail,&['c','d']);

GettingNone whenrange is out of bounds:

letmutslice:&[_] =&['a','b','c','d'];assert_eq!(None, slice.split_off(5..));assert_eq!(None, slice.split_off(..5));assert_eq!(None, slice.split_off(..=4));letexpected:&[char] =&['a','b','c','d'];assert_eq!(Some(expected), slice.split_off(..4));

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

ReturnsNone and does not modify the slice if the givenrange is out of bounds.

Note that this method only accepts one-sided ranges such as2.. or..6, but not2..6.

§Examples

Splitting off the first three elements of a slice:

letmutslice:&mut[_] =&mut['a','b','c','d'];letmutfirst_three = slice.split_off_mut(..3).unwrap();assert_eq!(slice,&mut['d']);assert_eq!(first_three,&mut['a','b','c']);

Splitting off a slice starting with the third element:

letmutslice:&mut[_] =&mut['a','b','c','d'];letmuttail = slice.split_off_mut(2..).unwrap();assert_eq!(slice,&mut['a','b']);assert_eq!(tail,&mut['c','d']);

GettingNone whenrange is out of bounds:

letmutslice:&mut[_] =&mut['a','b','c','d'];assert_eq!(None, slice.split_off_mut(5..));assert_eq!(None, slice.split_off_mut(..5));assert_eq!(None, slice.split_off_mut(..=4));letexpected:&mut[_] =&mut['a','b','c','d'];assert_eq!(Some(expected), slice.split_off_mut(..4));

Removes the first element of the slice and returns a referenceto it.

ReturnsNone if the slice is empty.

§Examples

letmutslice:&[_] =&['a','b','c'];letfirst = slice.split_off_first().unwrap();assert_eq!(slice,&['b','c']);assert_eq!(first,&'a');

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

ReturnsNone if the slice is empty.

§Examples

letmutslice:&mut[_] =&mut['a','b','c'];letfirst = slice.split_off_first_mut().unwrap();*first ='d';assert_eq!(slice,&['b','c']);assert_eq!(first,&'d');

Removes the last element of the slice and returns a referenceto it.

ReturnsNone if the slice is empty.

§Examples

letmutslice:&[_] =&['a','b','c'];letlast = slice.split_off_last().unwrap();assert_eq!(slice,&['a','b']);assert_eq!(last,&'c');

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

ReturnsNone if the slice is empty.

§Examples

letmutslice:&mut[_] =&mut['a','b','c'];letlast = slice.split_off_last_mut().unwrap();*last ='d';assert_eq!(slice,&['a','b']);assert_eq!(last,&'d');

Returns mutable references to many indices at once, without doing any checks.

An index can be either ausize, aRange or aRangeInclusive. Notethat this method takes an array, so all indices must be of the same type.If passed an array ofusizes this method gives back an array of mutable referencesto single elements, while if passed an array of ranges it gives back an array ofmutable references to slices.

For a safe alternative seeget_disjoint_mut.

§Safety

Calling this method with overlapping or out-of-bounds indices isundefined behavioreven if the resulting references are not used.

§Examples

letx =&mut[1,2,4];unsafe{let[a, b] = x.get_disjoint_unchecked_mut([0,2]);*a*=10;*b*=100;}assert_eq!(x,&[10,2,400]);unsafe{let[a, b] = x.get_disjoint_unchecked_mut([0..1,1..3]);    a[0] =8;    b[0] =88;    b[1] =888;}assert_eq!(x,&[8,88,888]);unsafe{let[a, b] = x.get_disjoint_unchecked_mut([1..=2,0..=0]);    a[0] =11;    a[1] =111;    b[0] =1;}assert_eq!(x,&[1,11,111]);

Returns mutable references to many indices at once.

An index can be either ausize, aRange or aRangeInclusive. Notethat this method takes an array, so all indices must be of the same type.If passed an array ofusizes this method gives back an array of mutable referencesto single elements, while if passed an array of ranges it gives back an array ofmutable references to slices.

Returns an error if any index is out-of-bounds, or if there are overlapping indices.An empty range is not considered to overlap if it is located at the beginning or atthe end of another range, but is considered to overlap if it is located in the middle.

This method does a O(n^2) check to check that there are no overlapping indices, so be carefulwhen passing many indices.

§Examples

letv =&mut[1,2,3];if letOk([a, b]) = v.get_disjoint_mut([0,2]) {*a =413;*b =612;}assert_eq!(v,&[413,2,612]);if letOk([a, b]) = v.get_disjoint_mut([0..1,1..3]) {    a[0] =8;    b[0] =88;    b[1] =888;}assert_eq!(v,&[8,88,888]);if letOk([a, b]) = v.get_disjoint_mut([1..=2,0..=0]) {    a[0] =11;    a[1] =111;    b[0] =1;}assert_eq!(v,&[1,11,111]);

Returns the index that an element reference points to.

ReturnsNone ifelement does not point to the start of an element within the slice.

This method is useful for extending slice iterators likeslice::split.

Note that this uses pointer arithmetic anddoes not compare elements.To find the index of an element via comparison, use.iter().position() instead.

§Panics

Panics ifT is zero-sized.

§Examples

Basic usage:

#![feature(substr_range)]letnums:&[u32] =&[1,7,1,1];letnum =&nums[2];assert_eq!(num,&1);assert_eq!(nums.element_offset(num),Some(2));

ReturningNone with an unaligned element:

#![feature(substr_range)]letarr:&[[u32;2]] =&[[0,1], [2,3]];letflat_arr:&[u32] = arr.as_flattened();letok_elm:&[u32;2] = flat_arr[0..2].try_into().unwrap();letweird_elm:&[u32;2] = flat_arr[1..3].try_into().unwrap();assert_eq!(ok_elm,&[0,1]);assert_eq!(weird_elm,&[1,2]);assert_eq!(arr.element_offset(ok_elm),Some(0));// Points to element 0assert_eq!(arr.element_offset(weird_elm),None);// Points between element 0 and 1

Returns the range of indices that a subslice points to.

ReturnsNone ifsubslice does not point within the slice or if it is not aligned with theelements in the slice.

This methoddoes not compare elements. Instead, this method finds the location in the slice thatsubslice was obtained from. To find the index of a subslice via comparison, instead use.windows().position().

This method is useful for extending slice iterators likeslice::split.

Note that this may return a false positive (eitherSome(0..0) orSome(self.len()..self.len()))ifsubslice has a length of zero and points to the beginning or end of another, separate, slice.

§Panics

Panics ifT is zero-sized.

§Examples

Basic usage:

#![feature(substr_range)]letnums =&[0,5,10,0,0,5];letmutiter = nums    .split(|t|*t ==0)    .map(|n| nums.subslice_range(n).unwrap());assert_eq!(iter.next(),Some(0..0));assert_eq!(iter.next(),Some(1..3));assert_eq!(iter.next(),Some(4..4));assert_eq!(iter.next(),Some(5..6));

Creates an iterator over the contiguous valid UTF-8 ranges of thisslice, and the non-UTF-8 fragments in between.

See theUtf8Chunk type for documentation of the items yielded by this iterator.

§Examples

This function formats arbitrary but mostly-UTF-8 bytes into Rust sourcecode in the form of a C-string literal (c"...").

usestd::fmt::Writeas _;pub fncstr_literal(bytes:&[u8]) -> String {letmutrepr = String::new();    repr.push_str("c\"");forchunkinbytes.utf8_chunks() {forchinchunk.valid().chars() {// Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters.write!(repr,"{}", ch.escape_debug()).unwrap();        }forbyteinchunk.invalid() {write!(repr,"\\x{:02X}", byte).unwrap();        }    }    repr.push('"');    repr}fnmain() {letlit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07");letexpected =stringify!(c"\xFErris the 🦀\u{7}");assert_eq!(lit, expected);}

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

This sort is stable (i.e., does not reorder equal elements) 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.

When applicable, unstable sorting is preferred because it is generally faster than stablesorting and it doesn’t allocate auxiliary memory. Seesort_unstable. The exception are partially sorted slices, whichmay be better served withslice::sort.

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_by such asf32::total_cmp orf64::total_cmp that defines atotalorder users can sort slices containing floating-point values. Alternatively, if all valuesin the slice are guaranteed to be in a subset for whichPartialOrd::partial_cmp forms atotal order, it’s possible to sort the slice withsort_by(|a, b| a.partial_cmp(b).unwrap()).

§Current implementation

The current implementation is based ondriftsort by Orson Peters and Lukas Bergdoll, whichcombines the fast average case of quicksort with the fast worst case and partial rundetection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputswith k distinct elements, the expected time to sort the data isO(n * log(k)).

The auxiliary memory allocation behavior depends on the input length. Short slices arehandled without allocation, medium sized slices allocateself.len() and beyond that itclamps atself.len() / 2.

§Panics

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

All safe functions on slices preserve the invariant that even if the function panics, alloriginal elements will remain in the slice and any possible modifications via interiormutability are observed in the input. This ensures that recovery code (for instance insideof aDrop or following acatch_unwind) will still have access to all the originalelements. For instance, if the slice belongs to aVec, theVec::drop method will be ableto dispose of all contained elements.

§Examples

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

Sorts the slice in ascending order with a comparison function, preserving initial order ofequal elements.

This sort is stable (i.e., does not reorder equal elements) andO(n * log(n))worst-case.

If the comparison functioncompare does not implement atotal order, the function maypanic; even if the function exits normally, the resulting order of elements in the slice isunspecified. 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.

§Current implementation

The current implementation is based ondriftsort by Orson Peters and Lukas Bergdoll, whichcombines the fast average case of quicksort with the fast worst case and partial rundetection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputswith k distinct elements, the expected time to sort the data isO(n * log(k)).

The auxiliary memory allocation behavior depends on the input length. Short slices arehandled without allocation, medium sized slices allocateself.len() and beyond that itclamps atself.len() / 2.

§Panics

May panic ifcompare does not implement atotal order, or ifcompare itself panics.

All safe functions on slices preserve the invariant that even if the function panics, alloriginal elements will remain in the slice and any possible modifications via interiormutability are observed in the input. This ensures that recovery code (for instance insideof aDrop or following acatch_unwind) will still have access to all the originalelements. For instance, if the slice belongs to aVec, theVec::drop method will be ableto dispose of all contained elements.

§Examples

letmutv = [4, -5,1, -3,2];v.sort_by(|a, b| a.cmp(b));assert_eq!(v, [-5, -3,1,2,4]);// reverse sortingv.sort_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, preserving initial orderof equal elements.

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

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.

§Current implementation

The current implementation is based ondriftsort by Orson Peters and Lukas Bergdoll, whichcombines the fast average case of quicksort with the fast worst case and partial rundetection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputswith k distinct elements, the expected time to sort the data isO(n * log(k)).

The auxiliary memory allocation behavior depends on the input length. Short slices arehandled without allocation, medium sized slices allocateself.len() and beyond that itclamps atself.len() / 2.

§Panics

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

All safe functions on slices preserve the invariant that even if the function panics, alloriginal elements will remain in the slice and any possible modifications via interiormutability are observed in the input. This ensures that recovery code (for instance insideof aDrop or following acatch_unwind) will still have access to all the originalelements. For instance, if the slice belongs to aVec, theVec::drop method will be ableto dispose of all contained elements.

§Examples

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

Sorts the slice in ascending order with a key extraction function, preserving initial orderof equal elements.

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

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

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 simple key functions (e.g., functions that are property accesses or basic operations),sort_by_key is likely to be faster.

§Current implementation

The current implementation is based oninstruction-parallel-network sort by LukasBergdoll, which combines the fast average case of randomized quicksort with the fast worstcase of heapsort, while achieving linear time on fully sorted and reversed inputs. AndO(k * log(n)) wherek is the number of distinct elements in the input. It leveragessuperscalar out-of-order execution capabilities commonly found in CPUs, to efficientlyperform the operation.

In the worst case, the algorithm allocates temporary storage in aVec<(K, usize)> thelength of the slice.

§Panics

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

All safe functions on slices preserve the invariant that even if the function panics, alloriginal elements will remain in the slice and any possible modifications via interiormutability are observed in the input. This ensures that recovery code (for instance insideof aDrop or following acatch_unwind) will still have access to all the originalelements. For instance, if the slice belongs to aVec, theVec::drop method will be ableto dispose of all contained elements.

§Examples

letmutv = [4i32, -5,1, -3,2,10];// Strings are sorted by lexicographical order.v.sort_by_cached_key(|k| k.to_string());assert_eq!(v, [-3, -5,1,10,2,4]);

Copiesself into a newVec.

§Examples

lets = [10,40,30];letx = s.to_vec();// Here, `s` and `x` can be modified independently.

Copiesself into a newVec with an allocator.

§Examples

#![feature(allocator_api)]usestd::alloc::System;lets = [10,40,30];letx = s.to_vec_in(System);// Here, `s` and `x` can be modified independently.

Creates a vector by copying a slicen times.

§Panics

This function will panic if the capacity would overflow.

§Examples

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

A panic upon overflow:

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

Flattens a slice ofT into a single valueSelf::Output.

§Examples

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

Flattens a slice ofT into a single valueSelf::Output, placing agiven separator between each.

§Examples

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

Flattens a slice ofT into a single valueSelf::Output, placing agiven separator between each.

§Examples

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

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

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

To uppercase the value in-place, usemake_ascii_uppercase.

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

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

To lowercase the value in-place, usemake_ascii_lowercase.