Trait array_util::SliceExt

source · 
pub trait SliceExt {
    // Required methods
    fn array_chunks_ext<const N: usize>(&self) -> ArrayChunks<'_, Self::T, N> ⓘ;
    fn array_chunks_mut_ext<const N: usize>(
        &mut self
    ) -> ArrayChunksMut<'_, Self::T, N> ⓘ;
    fn as_chunks_ext<const N: usize>(&self) -> (&[[Self::T; N]], &[Self::T]);
    unsafe fn as_chunks_unchecked_ext<const N: usize>(&self) -> &[[Self::T; N]];
    fn as_chunks_mut_ext<const N: usize>(
        &mut self
    ) -> (&mut [[Self::T; N]], &mut [Self::T]);
    unsafe fn as_chunks_unchecked_mut_ext<const N: usize>(
        &mut self
    ) -> &mut [[Self::T; N]];
    fn as_rchunks_ext<const N: usize>(&self) -> (&[Self::T], &[[Self::T; N]]);
    fn as_rchunks_mut_ext<const N: usize>(
        &mut self
    ) -> (&mut [Self::T], &mut [[Self::T; N]]);
}
Expand description

A helper extension trait for slices

Required Methods§

source

fn array_chunks_ext<const N: usize>(&self) -> ArrayChunks<'_, Self::T, N> ⓘ

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
use array_util::SliceExt;

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

fn array_chunks_mut_ext<const N: usize>( &mut self ) -> ArrayChunksMut<'_, Self::T, N> ⓘ

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

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

This method is the const generic equivalent of chunks_exact_mut.

§Panics

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

§Examples
use array_util::SliceExt;

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

for chunk in v.array_chunks_mut_ext() {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 0]);
source

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

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
use array_util::SliceExt;

let slice = ['l', 'o', 'r', 'e', 'm'];
let (chunks, remainder) = slice.as_chunks_ext();
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:

use array_util::SliceExt;

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

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

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
use array_util::SliceExt;

let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &[[char; 1]] =
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked_ext() };
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_ext() };
assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);

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

fn as_chunks_mut_ext<const N: usize>( &mut self ) -> (&mut [[Self::T; N]], &mut [Self::T])

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
use array_util::SliceExt;

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

let (chunks, remainder) = v.as_chunks_mut_ext();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 9]);
source

unsafe fn as_chunks_unchecked_mut_ext<const N: usize>( &mut self ) -> &mut [[Self::T; N]]

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
use array_util::SliceExt;

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

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

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

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
use array_util::SliceExt;

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

fn as_rchunks_mut_ext<const N: usize>( &mut self ) -> (&mut [Self::T], &mut [[Self::T; N]])

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
use array_util::SliceExt;

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

let (remainder, chunks) = v.as_rchunks_mut_ext();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source§

impl<T> SliceExt for [T]

source§

fn array_chunks_ext<const N: usize>(&self) -> ArrayChunks<'_, Self::T, N> ⓘ

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
use array_util::SliceExt;

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

fn array_chunks_mut_ext<const N: usize>( &mut self ) -> ArrayChunksMut<'_, Self::T, N> ⓘ

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

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

This method is the const generic equivalent of chunks_exact_mut.

§Panics

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

§Examples
use array_util::SliceExt;

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

for chunk in v.array_chunks_mut_ext() {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 0]);
source§

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

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
use array_util::SliceExt;

let slice = ['l', 'o', 'r', 'e', 'm'];
let (chunks, remainder) = slice.as_chunks_ext();
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:

use array_util::SliceExt;

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

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

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
use array_util::SliceExt;

let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &[[char; 1]] =
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked_ext() };
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_ext() };
assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);

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

fn as_chunks_mut_ext<const N: usize>( &mut self ) -> (&mut [[Self::T; N]], &mut [Self::T])

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
use array_util::SliceExt;

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

let (chunks, remainder) = v.as_chunks_mut_ext();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 9]);
source§

unsafe fn as_chunks_unchecked_mut_ext<const N: usize>( &mut self ) -> &mut [[Self::T; N]]

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
use array_util::SliceExt;

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

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

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

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
use array_util::SliceExt;

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

fn as_rchunks_mut_ext<const N: usize>( &mut self ) -> (&mut [Self::T], &mut [[Self::T; N]])

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
use array_util::SliceExt;

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

let (remainder, chunks) = v.as_rchunks_mut_ext();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);

Implementors§