pieces of pieces of longer pieces piecefully for pieces of rust
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Cargo.toml | 9 | ||||
| -rw-r--r-- | LICENSE | 21 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -rw-r--r-- | src/lib.rs | 66 |
5 files changed, 102 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..96ef6c0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/target +Cargo.lock diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..b0c4cd4 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "pieced" +version = "0.1.0" +edition = "2021" +categories = ["no-std"] +license = "MIT" +keywords = ["chunk", "piece"] +repository = "https://github.com/bend-n/pieced" +description = "[T]::as_chunks in stable rust" @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023-now bendn + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f42d71 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +# pieced + +[`as_chunks`](https://github.com/rust-lang/rust/issues/74985) in stable rust, today! +piecefully piece your slices in piece.
\ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..6fe4036 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,66 @@ +#![no_std] +/// Splits the slice into a slice of `N`-element arrays, +/// starting at the beginning of the slice, +/// and a rest slice with length strictly less than `N`. +/// +/// # Panics +/// +/// Panics if `N` is 0. +/// # Examples +/// +/// ``` +/// let slice = ['l', 'o', 'r', 'e', 'm']; +/// let (chunks, rest) = pieced::as_with_rest(&slice); +/// assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]); +/// assert_eq!(rest, &['m']); +/// ``` +/// +/// If you expect the slice to be an exact multiple, you can combine +/// `let`-`else` with an empty slice pattern (or use [`as_exact`]): +/// ``` +/// let slice = ['R', 'u', 's', 't']; +/// let (chunks, []) = pieced::as_with_rest(&slice) else { +/// panic!("slice didn't have even length") +/// }; +/// assert_eq!(chunks, &[['R', 'u'], ['s', 't']]); +/// ``` +pub const fn as_with_rest<T, const N: usize>(slice: &[T]) -> (&[[T; N]], &[T]) { + assert!(N != 0, "chunk size must be non-zero"); + let len = slice.len() / N; + let (multiple_of_n, remainder) = slice.split_at(len * N); + let new_len = multiple_of_n.len() / N; + // SAFETY: We cast a slice of `new_len * N` elements into + // a slice of `new_len` many `N` elements chunks. + ( + unsafe { core::slice::from_raw_parts(multiple_of_n.as_ptr().cast(), new_len) }, + remainder, + ) +} + +/// Splits the slice into a slice of `N`-element arrays, assuming that there's no remainder. +/// +/// # Panics +/// +/// Panics when +/// - The slice splits exactly into `N`-element chunks (aka `self.len() % N == 0`). +/// - `N != 0`. +/// +/// # Examples +/// +/// ``` +/// let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!']; +/// let chunks: &[[char; 1]] = pieced::as_exact(slice); +/// assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]); +/// let chunks: &[[char; 3]] = pieced::as_exact(slice); +/// assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]); +/// ``` +pub const fn as_exact<T, const N: usize>(slice: &[T]) -> &[[T; N]] { + assert!( + N != 0 && slice.len() % N == 0, + "pieced::as_exact requires `N != 0` and the slice to split exactly into `N`-element chunks", + ); + let new_len = slice.len() / N; + // SAFETY: We cast a slice of `new_len * N` elements into + // a slice of `new_len` many `N` elements chunks. + unsafe { core::slice::from_raw_parts(slice.as_ptr().cast(), new_len) } +} |