Struct uninit::out_ref::Out

#[repr(transparent)]
pub struct Out<'out, T: 'out + ?Sized>(_, _);

Wrapper expressing the semantics of &out T references

In other words, this has the semantics of &'out mut MaybeUninit<T> but for the ability to write garbage (MaybeUninit::uninit()) into it (else coercing &mut T to &out T = Out<T> would be unsound).

This means that the reference may point to uninitialized memory (or not), and thus that writes to the pointee will not call the .drop() destructor.

This type can be trivially constructed from:

• a &'out mut MaybeUninit<T> (main point of the type),

• a &'out mut T (to keep the ergonomics of being able to overwrite an already initialized value).

  • To avoid “accidentally” leaking memory in this second case, either T must be Copy (sufficient condition to prove there is no drop glue), or you must first call .manually_drop_mut() before the .as_out() “coercion”.

Implementations

impl<'out, T: 'out + ?Sized> Out<'out, T>

pub fn reborrow<'reborrow>( self: &'reborrow mut Out<'out, T> ) -> Out<'reborrow, T>where 'out: 'reborrow,

Reborrows the &out _ reference for a shorter lifetime.

pub fn r<'reborrow>(self: &'reborrow mut Out<'out, T>) -> Out<'reborrow, T>where 'out: 'reborrow,

Shorthand for .reborrow().

impl<'out, T: 'out> Out<'out, T>

pub fn write(self: Out<'out, T>, value: T) -> &'out mut T

Write a value into the pointee, returning an .assume_init()-ed reference to it.

Guarantees (that unsafe code may rely on)

After the function returns, the pointee is guaranteed to have been initialized; it is thus sound to use that property to manually assume_init() it or any chunk of such items.

pub fn replace(self: Out<'out, T>, value: T) -> (MaybeUninit<T>, &'out mut T)

Similar to .write(), but getting the previous value back. Such previous value may or may not be initialized.

Guarantees (that unsafe code may rely on)

• After the function returns, the pointee is guaranteed to have been initialized; it is thus sound to use that property to manually assume_init() it or any chunk of such items.

• there is no such guarantee regarding the previous value, which is thus only sound to assume_init() if the pointee already was (before the call to .replace()).

pub fn as_mut_ptr(self: &mut Out<'out, T>) -> *mut T

Returns a raw mutable pointer to the pointee.

Guarantees (that unsafe code may rely on)

• The returned pointer does point to the pointee, meaning that if such returned pointer is used to .write() to the pointee, then it is safe to assume_init() it.

• The returned pointer is non null, well-aligned, and writeable.

  It is also technically readable:

  • you can read a MaybeUninit<T> out of it after .cast()ing it,

  • otherwise, except when sound to assume_init(), the obtained pointer cannot be used to read the value : T of the pointee!

pub unsafe fn assume_init(self: Out<'out, T>) -> &'out mut T

Upgrades the &out _ (write-only) reference to a read-writeable &mut _.

Safety

Don’t be lured by the &mut reference: Rust validity invariants imply that an &mut reference is only sound to produce if it points to an initialized value; it is otherwise instant UB. See MaybeUninit::assume_init for more info about it. Thus:

• The pointee must have been initialized.

This is a validity invariant, meaning that UB does happen from just calling that function to produce an ill-formed reference, even if the obtained reference is “never actually used”.

Counterexample

The following program exhibits Undefined Behavior:

use ::uninit::prelude::*;

let mut x = MaybeUninit::uninit();
let _unused: &mut u8 = unsafe {
    x   .as_out()
        .assume_init() // UB!
};

pub unsafe fn as_mut_uninit(self: Out<'out, T>) -> &'out mut MaybeUninit<T>

Upgrades the &out _ (write-valid-values-only) reference to a &mut MaybeUninit<_> (write-anything) reference.

Safety

• The obtained reference cannot be used to write garbage (MaybeUninit::uninit()) into the pointee.

  This means that it can thus not be fed to opaque APIs!!

• Exception: if the given &out reference has originated from a &mut MaybeUninit<_>, then calling .as_mut_uninit() is a sound way to make the trip back.

This is a safety invariant (i.e., even if it is never “instant” UB to produce such a value, it does break the safety invariant of &mut MaybeUninit<_> (that of being allowed to write MaybeUninit::uninit() garbage into the pointee), so UB can happen afterwards). This is different than .assume_init() soundness relying on a validity invariant, meaning that UB does happen from just calling that function to produce an ill-formed reference, even if the obtained reference is never actually used.

Counter-example

The following code is Undefined Behavior:

use ::uninit::prelude::*;

let mut my_box = Box::new(42);
let at_my_box: Out<'_, Box<i32>> =
    my_box
        .manually_drop_mut()
        .as_out()
;
// Overwrite `my_box` with uninitialized bytes / garbage content.
unsafe {
    *at_my_box.as_mut_uninit() = MaybeUninit::uninit();
}
// Runs the destructor for a `Box<i32>` using a garbage pointer that
// may thus point anywhere in memory!
drop(my_box)

A function from an external library must always be seen as opaque (unless its documentation makes implementation-detail guarantees, such as this very crate does), so one cannot rely on its implementation (unless the lib is open source AND you pin-point to that version of the crate, either through version = "=x.y.z" or through git = ..., rev = ... in Cargo.toml).

// `fn zeroize (out: &'_ mut MaybeUninit<u8>) -> &'_ mut u8;`
// The author of the crate says it uses that `out` reference to write
// `0` to the pointee.
use ::some_lib::zeroize;

let mut x = 42;
let at_x = x.as_out();
// Unsound! The lib implementation is free to write
// `MaybeUninit::uninit()` garbage to the pointee!
zeroize(unsafe { at_x.as_mut_uninit() });

impl<'out, T: 'out> Out<'out, [T]>

pub fn from_out(out: Out<'out, T>) -> Out<'out, [T]>

Converts a single item out reference into a 1-long out slice.

This is the &out version of slice::from_ref and slice::from_mut.

pub fn as_ptr(&self) -> *const T

Obtains a read-only non-NULL and well-aligned raw pointer to a potentially uninitialized T.

Unless maybe with interior mutability through raw pointers, there is no case where using this function is more useful than going through <[MaybeUninit<_>]>::assume_init_by_ref().

Worse, the lack of unsafe-ty of the method (ignoring the one needed to use the pointer) and its “boring” name may lead to code read-dereferencing the pointer (which implicitly assume_init()s it) without having ensured the soundness of such (implicit) assume_init().

pub fn as_mut_ptr(&mut self) -> *mut T

Returns a raw mutable pointer to the pointee.

See Out::as_mut_ptr for more info regarding safety and guarantees.

pub unsafe fn as_mut_uninit(self: Out<'out, [T]>) -> &'out mut [MaybeUninit<T>]

Upgrades the &out _ (write-valid-values-only) reference to a &mut MaybeUninit<_> (write-anything) reference.

See Out::as_mut_uninit for more info regarding safety.

pub fn get_out<Index>(self: Out<'out, [T]>, idx: Index) -> Option<Index::Output>where Index: UsizeOrRange<'out, T>,

Main indexing operation on an &out [_].

The type Index of idx may be:

• a usize, and then Index::Output is a Out<T> reference to a single element.

• a Range<usize> (e.g., a .. b), and then Index::Output is a Out<[T]> reference to a subslice.

Example

use ::uninit::prelude::*;

let src: &[u8] = b"Hello, World!";
// Stack-allocate an uninitialized buffer.
let mut buf = uninit_array![u8; 256];
// copy `src` into this stack allocated buffer, effectively initializing it.
let buf: &mut [u8] =
    // buf[.. src.len()].as_out()
    buf.as_out().get_out(.. src.len()).unwrap()
        .copy_from_slice(src)
;
assert_eq!(buf, b"Hello, World!");
buf[7 ..].copy_from_slice(b"Earth!");
assert_eq!(buf, b"Hello, Earth!");

pub unsafe fn get_unchecked_out<Index>( self: Out<'out, [T]>, idx: Index ) -> Index::Outputwhere Index: UsizeOrRange<'out, T>,

Same as .get_out(), but with the bound check being elided.

Safety

The given idx mut be in bounds:

• if idx: usize, then idx must be < self.len().

• if idx is an upper-bounded range (e.g., .. b, a ..= b), then the upper bound (b in the example) must be < self.len().

• etc.

See .get_unchecked_mut() for more info about the safety of such call.

pub fn as_uninit(self: Out<'out, [T]>) -> &'out [MaybeUninit<T>]

Downgrades the Out<'_, [T]> slice into a &'_ [MaybeUninit<T>].

This leads to a read-only¹ “unreadable” slice which is thus only useful for accessing &'_ [] metadata, mainly the length of the slice.

In practice, calling this function explicitely is not even needed given that Out<'_, [T]> : Deref<Target = [MaybeUninit<T>], so one can do:

use ::uninit::prelude::*;

let mut backing_array = uninit_array![_; 42];
let buf: Out<'_, [u8]> = backing_array.as_out();
assert_eq!(buf.len(), 42); // no need to `.r().as_uninit()`

¹ Unless Interior Mutability is involved; speaking of which:

Interior Mutability

The whole design of Out references is to forbid any non-unsafe API that would allow writing MaybeUninit::uninit() garbage into the pointee. So, for instance, this crate does not offer any API like:

use ::core::{cell::Cell, mem::MaybeUninit};

// /!\ This is UNSOUND when combined with the `::uninit` crate!
fn swap_mb_uninit_and_cell<T> (
    p: &'_ MaybeUninit<Cell<T>>,
) -> &'_ Cell<MaybeUninit<T>>
{
    unsafe {
        // Safety: both `Cell` and `MaybeUninit` are `#[repr(transparent)]`
        ::core::mem::transmute(p)
    }
}

Indeed, if both such non-unsafe API and the uninit crate were present, then one could trigger UB with:

let mut x = [Cell::new(42)];
let at_mb_uninit_cell: &'_ MaybeUninit<Cell<u8>> =
    &x.as_out().as_uninit()[0]
;
swap_mb_uninit_and_cell(at_mb_uninit_cell)
    .set(MaybeUninit::uninit()) // UB!
;

The author of the crate believes that such UB is the responsibility of the one who defined swap_mb_uninit_and_cell, and that in general that function is unsound: MaybeUninit-ness and interior mutability do not commute!

• the Safety annotation in the given example only justifies that it is not breaking any layout-based validity invariants, but it is actually impossible to semantically prove that it is safe for these properties to commute.

If you are strongly convinced of the opposite, please file an issue (if there isn’t already one: since this question is not that clear the author is very likely to create an issue themself).

pub unsafe fn assume_all_init(self: Out<'out, [T]>) -> &'out mut [T]

Upgrades the &out [_] (write-only) reference to a read-writeable &mut [_].

Safety

Don’t be lured by the &mut reference: Rust validity invariants imply that an &mut reference is only sound to produce if it points to initialized values; it is otherwise instant UB. See MaybeUninit::assume_init for more info about it. Thus:

• The pointee(s) must have been initialized.

This is a validity invariant, meaning that UB does happen from just calling that function to produce an ill-formed reference, even if the obtained reference is “never actually used”.

pub fn copy_from_slice( self: Out<'out, [T]>, source_slice: &[T] ) -> &'out mut [T]where T: Copy,

Initialize the buffer with a copy from another (already initialized) buffer.

It returns a read-writable slice to the initialized bytes for convenience (automatically assume_init-ed).

Panic

The function panics if the slices’ lengths are not equal.

Guarantees (that unsafe code may rely on)

A non-panic!king return from this function guarantees that the input slice has been (successfully) initialized, and that it is thus then sound to .assume_init().

It also guarantees that the returned slice does correspond to the input slice (e.g., for [crate::ReadIntoUninit]’s safety guarantees).

Example

use ::uninit::prelude::*;

let mut array = uninit_array![_; 13];
assert_eq!(
    array.as_out().copy_from_slice(b"Hello, World!"),
    b"Hello, World!",
);
// we can thus soundly `assume_init` our array:
let array = unsafe {
    mem::transmute::<
        [MaybeUninit<u8>; 13],
        [            u8 ; 13],
    >(array)
};
assert_eq!(
    array,
    *b"Hello, World!",
);

pub fn init_with( self: Out<'out, [T]>, iterable: impl IntoIterator<Item = T> ) -> &'out mut [T]

Fills the buffer with values from up to the first self.len() elements of an iterable.

Guarantees (that unsafe code may rely on)

A non-panicking return from this function guarantees that the first k values of the buffer have been initialized and are thus sound to .assume_init(), where k, the numbers of elements that iterable has yielded (capped at self.len()), is the length of the returned buffer.

pub fn iter_out<'reborrow>( self: &'reborrow mut Out<'out, [T]> ) -> IterOut<'reborrow, T>

.reborrow().into_iter()

pub fn split_at_out( self: Out<'out, [T]>, idx: usize ) -> (Out<'out, [T]>, Out<'out, [T]>)

Same as .split_at_mut(), but with &out [_] references.

Panic

Panics if idx > len.

Methods from Deref<Target = [MaybeUninit<T>]>

pub fn is_ascii(&self) -> bool

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

pub fn as_ascii(&self) -> Option<&[AsciiChar]>

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

If this slice is_ascii, returns it as a slice of ASCII characters, otherwise returns None.

pub unsafe fn as_ascii_unchecked(&self) -> &[AsciiChar]

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

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 in 0..=127, or else this is UB.

pub fn eq_ignore_ascii_case(&self, other: &[u8]) -> bool

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

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

pub fn escape_ascii(&self) -> EscapeAscii<'_>

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

Examples

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

pub fn trim_ascii_start(&self) -> &[u8]

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

Returns a byte slice with leading ASCII whitespace bytes removed.

‘Whitespace’ refers to the definition used by u8::is_ascii_whitespace.

Examples

#![feature(byte_slice_trim_ascii)]

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

pub fn trim_ascii_end(&self) -> &[u8]

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

Returns a byte slice with trailing ASCII whitespace bytes removed.

‘Whitespace’ refers to the definition used by u8::is_ascii_whitespace.

Examples

#![feature(byte_slice_trim_ascii)]

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

pub fn trim_ascii(&self) -> &[u8]

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

Returns a byte slice with leading and trailing ASCII whitespace bytes removed.

‘Whitespace’ refers to the definition used by u8::is_ascii_whitespace.

Examples

#![feature(byte_slice_trim_ascii)]

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

pub fn len(&self) -> usize

Returns the number of elements in the slice.

Examples

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

pub fn is_empty(&self) -> bool

Returns true if the slice has a length of 0.

Examples

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

pub fn first(&self) -> Option<&T>

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

Examples

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

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

pub fn split_first(&self) -> Option<(&T, &[T])>

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

Examples

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

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

pub fn split_last(&self) -> Option<(&T, &[T])>

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

Examples

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

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

pub fn last(&self) -> Option<&T>

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

Examples

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

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

pub fn first_chunk<const N: usize>(&self) -> Option<&[T; N]>

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

Returns the first N elements of the slice, or None if it has fewer than N elements.

Examples

#![feature(slice_first_last_chunk)]

let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());

pub fn split_first_chunk<const N: usize>(&self) -> Option<(&[T; N], &[T])>

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

Returns the first N elements of the slice and the remainder, or None if it has fewer than N elements.

Examples

#![feature(slice_first_last_chunk)]

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

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

pub fn split_last_chunk<const N: usize>(&self) -> Option<(&[T; N], &[T])>

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

Returns the last N elements of the slice and the remainder, or None if it has fewer than N elements.

Examples

#![feature(slice_first_last_chunk)]

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

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

pub fn last_chunk<const N: usize>(&self) -> Option<&[T; N]>

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

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

Examples

#![feature(slice_first_last_chunk)]

let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());

pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>where I: SliceIndex<[T]>,

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

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

Examples

let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));

pub unsafe fn get_unchecked<I>( &self, index: I ) -> &<I as SliceIndex<[T]>>::Outputwhere I: SliceIndex<[T]>,

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

For a safe alternative see get.

Safety

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

Examples

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

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

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the slice’s buffer.

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

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

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

Examples

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

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

pub fn as_ptr_range(&self) -> Range<*const T>

Returns the two raw pointers spanning the slice.

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

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

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

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

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

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

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the slice.

The iterator yields all items from start to end.

Examples

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

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

pub fn windows(&self, size: usize) -> Windows<'_, T>

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

Panics

Panics if size is 0.

Examples

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

If the slice is shorter than size:

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

There’s no windows_mut, as that existing would let safe code violate the “only one &mut at a time to the same thing” rule. However, you can sometimes use Cell::as_slice_of_cells in conjunction with windows to accomplish something similar:

use std::cell::Cell;

let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
let slice = &mut array[..];
let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
for w in slice_of_cells.windows(3) {
    Cell::swap(&w[0], &w[2]);
}
assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);

pub fn chunks(&self, chunk_size: usize) -> Chunks<'_, T>

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See chunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size elements, and rchunks for the same iterator but starting at the end of the slice.

Panics

Panics if chunk_size is 0.

Examples

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

pub fn chunks_exact(&self, chunk_size: usize) -> ChunksExact<'_, T>

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

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

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks.

See chunks for a variant of this iterator that also returns the remainder as a smaller chunk, and rchunks_exact for the same iterator but starting at the end of the slice.

Panics

Panics if chunk_size is 0.

Examples

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

pub unsafe fn as_chunks_unchecked<const N: usize>(&self) -> &[[T; N]]

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

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

Safety

This may only be called when

• The slice splits exactly into N-element chunks (aka self.len() % N == 0).
• N != 0.

Examples

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

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

pub fn as_chunks<const N: usize>(&self) -> (&[[T; N]], &[T])

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

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

Panics

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

Examples

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

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

#![feature(slice_as_chunks)]
let slice = ['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']]);

pub fn as_rchunks<const N: usize>(&self) -> (&[T], &[[T; N]])

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

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

Panics

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

Examples

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

pub fn array_chunks<const N: usize>(&self) -> ArrayChunks<'_, T, N>

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

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

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

This method is the const generic equivalent of chunks_exact.

Panics

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

Examples

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

pub fn array_windows<const N: usize>(&self) -> ArrayWindows<'_, T, N>

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

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

This is the const generic equivalent of windows.

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

Panics

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

Examples

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

pub fn rchunks(&self, chunk_size: usize) -> RChunks<'_, T>

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

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See rchunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size elements, and chunks for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

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

pub fn rchunks_exact(&self, chunk_size: usize) -> RChunksExact<'_, T>

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

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

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of rchunks.

See rchunks for a variant of this iterator that also returns the remainder as a smaller chunk, and chunks_exact for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

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

pub fn group_by<F>(&self, pred: F) -> GroupBy<'_, T, F>where F: FnMut(&T, &T) -> bool,

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

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

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

Examples

#![feature(slice_group_by)]

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

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

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

This method can be used to extract the sorted subslices:

#![feature(slice_group_by)]

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

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

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

pub fn split_at(&self, mid: usize) -> (&[T], &[T])

Divides one slice into two at an index.

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

Panics

Panics if mid > len.

Examples

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

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

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

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

pub unsafe fn split_at_unchecked(&self, mid: usize) -> (&[T], &[T])

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

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

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

For a safe alternative see split_at.

Safety

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

Examples

#![feature(slice_split_at_unchecked)]

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

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

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

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

pub fn split_array_ref<const N: usize>(&self) -> (&[T; N], &[T])

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

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

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

Panics

Panics if N > len.

Examples

#![feature(split_array)]

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

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

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

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

pub fn rsplit_array_ref<const N: usize>(&self) -> (&[T], &[T; N])

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

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

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

Panics

Panics if N > len.

Examples

#![feature(split_array)]

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

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

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

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

pub fn split<F>(&self, pred: F) -> Split<'_, T, F>where F: FnMut(&T) -> bool,

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

Examples

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

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

If the first element is matched, an empty slice will be the first item returned by the iterator. Similarly, if the last element in the slice is matched, an empty slice will be the last item returned by the iterator:

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

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

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

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

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

pub fn split_inclusive<F>(&self, pred: F) -> SplitInclusive<'_, T, F>where F: FnMut(&T) -> bool,

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

Examples

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

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

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

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

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

pub fn rsplit<F>(&self, pred: F) -> RSplit<'_, T, F>where F: FnMut(&T) -> bool,

Returns an iterator over subslices separated by elements that match pred, starting at the end of the slice and working backwards. The matched element is not contained in the subslices.

Examples

let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
assert_eq!(iter.next(), None);

As with split(), if the first or last element is matched, an empty slice will be the first (or last) item returned by the iterator.

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

pub fn splitn<F>(&self, n: usize, pred: F) -> SplitN<'_, T, F>where F: FnMut(&T) -> bool,

Returns an iterator over subslices separated by elements that match pred, limited to returning at most n items. The matched element is not contained in the subslices.

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

Examples

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

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

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

pub fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<'_, T, F>where F: FnMut(&T) -> bool,

Returns an iterator over subslices separated by elements that match pred limited to returning at most n items. This starts at the end of the slice and works backwards. The matched element is not contained in the subslices.

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

Examples

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

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

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

pub fn contains(&self, x: &T) -> boolwhere T: PartialEq<T>,

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

This operation is O(n).

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

Examples

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

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

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

pub fn starts_with(&self, needle: &[T]) -> boolwhere T: PartialEq<T>,

Returns true if needle is a prefix of the slice.

Examples

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

Always returns true if needle is an empty slice:

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

pub fn ends_with(&self, needle: &[T]) -> boolwhere T: PartialEq<T>,

Returns true if needle is a suffix of the slice.

Examples

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

Always returns true if needle is an empty slice:

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

pub fn strip_prefix<P>(&self, prefix: &P) -> Option<&[T]>where P: SlicePattern<Item = T> + ?Sized, T: PartialEq<T>,

Returns a subslice with the prefix removed.

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

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

Examples

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

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

pub fn strip_suffix<P>(&self, suffix: &P) -> Option<&[T]>where P: SlicePattern<Item = T> + ?Sized, T: PartialEq<T>,

Returns a subslice with the suffix removed.

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

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

Examples

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

pub fn binary_search(&self, x: &T) -> Result<usize, usize>where T: Ord,

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

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. The index is chosen deterministically, but is subject to change in future versions of Rust. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search_by, binary_search_by_key, and partition_point.

Examples

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

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

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

If you want to find that whole range of matching items, rather than an arbitrary matching one, that can be done using partition_point:

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

let low = s.partition_point(|x| x < &1);
assert_eq!(low, 1);
let high = s.partition_point(|x| x <= &1);
assert_eq!(high, 5);
let r = 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 empty
assert_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 maintaining sort order, consider using partition_point:

let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x < num);
// The above is equivalent to `let idx = s.binary_search(&num).unwrap_or_else(|x| x);`
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);

pub fn binary_search_by<'a, F>(&'a self, f: F) -> Result<usize, usize>where F: FnMut(&'a T) -> Ordering,

Binary searches this slice with a comparator function.

The comparator function should return an order code that indicates whether its argument is Less, Equal or Greater the desired target. If the slice is not sorted or if the comparator function does not implement an order consistent with the sort order of the underlying slice, the returned result is unspecified and meaningless.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. The index is chosen deterministically, but is subject to change in future versions of Rust. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search, binary_search_by_key, and partition_point.

Examples

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

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

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

pub fn binary_search_by_key<'a, B, F>( &'a self, b: &B, f: F ) -> Result<usize, usize>where F: FnMut(&'a T) -> B, B: Ord,

Binary searches this slice with a key extraction function.

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

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. The index is chosen deterministically, but is subject to change in future versions of Rust. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search, binary_search_by, and partition_point.

Examples

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

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

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

pub unsafe fn align_to<U>(&self) -> (&[T], &[U], &[T])

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

This method splits the slice into three distinct slices: prefix, correctly aligned middle slice of a new type, and the suffix slice. How exactly the slice is split up is not specified; the middle part may be smaller than necessary. However, if this fails to return a maximal middle part, that is because code is running in a context where performance does not matter, such as a sanitizer attempting to find alignment bugs. Regular code running in a default (debug or release) execution will return a maximal middle part.

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

Safety

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

Examples

Basic usage:

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

pub fn as_simd<const LANES: usize>(&self) -> (&[T], &[Simd<T, LANES>], &[T])where Simd<T, LANES>: AsRef<[T; LANES]>, T: SimdElement, LaneCount<LANES>: SupportedLaneCount,

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

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

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

Notably, all of the following are possible:

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

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

Panics

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

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

Examples

#![feature(portable_simd)]
use core::simd::SimdFloat;

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

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

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

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);

pub fn is_sorted(&self) -> boolwhere T: PartialOrd<T>,

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

Checks if the elements of this slice are sorted.

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

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

Examples

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

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

pub fn is_sorted_by<'a, F>(&'a self, compare: F) -> boolwhere F: FnMut(&'a T, &'a T) -> Option<Ordering>,

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

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

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

pub fn is_sorted_by_key<'a, F, K>(&'a self, f: F) -> boolwhere F: FnMut(&'a T) -> K, K: PartialOrd<K>,

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

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

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

Examples

#![feature(is_sorted)]

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

pub fn partition_point<P>(&self, pred: P) -> usizewhere P: FnMut(&T) -> bool,

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

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

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

See also binary_search, binary_search_by, and binary_search_by_key.

Examples

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

assert_eq!(i, 4);
assert!(v[..i].iter().all(|&x| x < 5));
assert!(v[i..].iter().all(|&x| !(x < 5)));

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

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

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

let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.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]);

pub fn flatten(&self) -> &[T]

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

Takes a &[[T; N]], and flattens it to a &[T].

Panics

This panics if the length of the resulting slice would overflow a usize.

This is only possible when flattening a slice of arrays of zero-sized types, and thus tends to be irrelevant in practice. If size_of::<T>() > 0, this will never panic.

Examples

#![feature(slice_flatten)]

assert_eq!([[1, 2, 3], [4, 5, 6]].flatten(), &[1, 2, 3, 4, 5, 6]);

assert_eq!(
    [[1, 2, 3], [4, 5, 6]].flatten(),
    [[1, 2], [3, 4], [5, 6]].flatten(),
);

let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []];
assert!(slice_of_empty_arrays.flatten().is_empty());

let empty_slice_of_arrays: &[[u32; 10]] = &[];
assert!(empty_slice_of_arrays.flatten().is_empty());

pub fn as_str(&self) -> &str

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

Views this slice of ASCII characters as a UTF-8 str.

pub fn as_bytes(&self) -> &[u8]

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

Views this slice of ASCII characters as a slice of u8 bytes.

Trait Implementations

impl<'out, T: Debug + 'out + ?Sized> Debug for Out<'out, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'out, T: 'out> Default for Out<'out, [T]>

This can be useful to get a Out<'long ...> out of a &'short mut Out<'long ...> by mem::replace-ing with a Out::default() (e.g., to implement an Iterator).

fn default() -> Self

Returns the “default value” for a type.

impl<'out, T: 'out> Deref for Out<'out, [T]>

Deref into [MaybeUninit<T>] to get access to the slice length related getters.

type Target = [MaybeUninit<T>]

The resulting type after dereferencing.

fn deref(&self) -> &[MaybeUninit<T>]

Dereferences the value.

impl<'out, T: 'out> From<&'out mut [ManuallyDrop<T>]> for Out<'out, [T]>

fn from(slice: &'out mut [ManuallyDrop<T>]) -> Out<'out, [T]>

Converts to this type from the input type.

impl<'out, T: 'out> From<&'out mut [MaybeUninit<T>]> for Out<'out, [T]>

fn from(slice: &'out mut [MaybeUninit<T>]) -> Out<'out, [T]>

Converts to this type from the input type.

impl<'out, T> From<&'out mut [T]> for Out<'out, [T]>where T: Copy + 'out,

fn from(slice: &'out mut [T]) -> Out<'out, [T]>

Converts to this type from the input type.

impl<'out, T: 'out> From<&'out mut ManuallyDrop<T>> for Out<'out, T>

For non-Copy types, explicitely transmuting the mut reference into one that points to a ManuallyDrop is required, so as to express how likely it is that memory be leaked. This can be safely achieved by using the ManuallyDropMut helper.

fn from(p: &'out mut ManuallyDrop<T>) -> Out<'out, T>

Converts to this type from the input type.

impl<'out, T: 'out> From<&'out mut MaybeUninit<T>> for Out<'out, T>

fn from(p: &'out mut MaybeUninit<T>) -> Out<'out, T>

Converts to this type from the input type.

impl<'out, T> From<&'out mut T> for Out<'out, T>where T: Copy + 'out,

fn from(p: &'out mut T) -> Out<'out, T>

Converts to this type from the input type.

impl<'out, 'inner: 'out, T: 'inner> IntoIterator for &'out mut Out<'inner, [T]>

type Item = Out<'out, T>

The type of the elements being iterated over.

type IntoIter = IterOut<'out, T>

Which kind of iterator are we turning this into?

fn into_iter(self: &'out mut Out<'inner, [T]>) -> IterOut<'out, T>

Creates an iterator from a value.

impl<'out, T: 'out> IntoIterator for Out<'out, [T]>

type Item = Out<'out, T>

The type of the elements being iterated over.

type IntoIter = IterOut<'out, T>

Which kind of iterator are we turning this into?

fn into_iter(self: Out<'out, [T]>) -> IterOut<'out, T>

Creates an iterator from a value.

impl<'out, T: ?Sized + 'out> Send for Out<'out, T>where &'out mut T: Send,

impl<'out, T: ?Sized + 'out> Sync for Out<'out, T>where &'out mut T: Sync,