array_util

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

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so 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§