diff --git a/Cargo.toml b/Cargo.toml index 48ab100..7ccccf7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,6 +9,9 @@ description = "Iterator of fixed length" keywords = ["iterator", "array", "data-structure", "zip"] categories = ["rust-patterns", "no-std"] +[badges] +maintenance = { status = "experimental" } + # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [features] diff --git a/README.md b/README.md index 9bbf1bb..541114c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# iter_fixed +![Maintenance](https://img.shields.io/badge/maintenance-experimental-blue.svg) [![crates.io](https://img.shields.io/crates/v/iter_fixed.svg)](https://crates.io/crates/iter_fixed) [![docs.rs](https://docs.rs/iter_fixed/badge.svg)](https://docs.rs/iter_fixed/) @@ -8,70 +8,64 @@ ![Nightly](https://github.com/usbalbin/iter_fixed/actions/workflows/nightly.yml/badge.svg) ![Miri](https://github.com/usbalbin/iter_fixed/actions/workflows/miri.yml/badge.svg) -*This project is inspired by @leonardo-m 's idea https://github.com/rust-lang/rust/issues/80094#issuecomment-749260428* - -**This code is currently very experimental, type names, function names, trait bounds etc. are all very much subject to change. +# iter_fixed Provides a type and traits for turning collections of fixed size, like arrays, -into `IteratorFixed` which can be used a bit like an ordinary `Iterator` but +into [`IteratorFixed`] which can be used a bit like an ordinary [`Iterator`] but with a compile time guaranteed length. This enables us to turn them back into collections of fixed size without having to perform unnecessary checks during run time. -Just like [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html), [`IteratorFixed`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html) provides methods like: - -###### Works on stable rust -* [`map`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.map) -* [`inspect`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.inspect) -* [`enumerate`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.enumerate) -* [`zip`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.zip) -* [`rev`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.rev) -* [`copied`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.copied) -* [`cloned`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.cloned) - -###### Requires nightly compiler -* [`skip`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.skip) -* [`step_by`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.step_by) -* [`chain`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.chain) -* [`take`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.take) -* [`flatten`](https://docs.rs/iter_fixed/latest/iter_fixed/struct.IteratorFixed.html#method.flatten) +[`IteratorFixed`] provides on stable methods like `map`, `inspect`, `enumerate`, + `zip`, `rev`, `copied`, `cloned`, with nightly `skip`, `step_by`, `chain`, `take`, + `flatten`. -however it does not and will never be able to support methods like `filter` or `take_while` which will affect the length during runtime. - -## no_std - -This crate should work without the full standard library +However it does not and will never be able to support methods like + `filter` or `take_while` which will affect the length during runtime. -# Examples +## ⚠️ Experimental +*This code is currently very experimental, type names, function names, trait bounds etc. are all very much subject to change.* -## Toy example +## Origin +*This project is inspired by @leonardo-m 's idea * +## Examples: ```rust -// zip together two arrays of length 4, turn the elements wise sums of the -// two middle elements into an array of size 2 -let res: [_; 2] = [1, 2, 3, 4] +// simply reverse an Array +let rev_array: [_; 4] = [1, 3, 2, 7] .into_iter_fixed() - .zip([4, 3, 2, 1]) - .map(|(a, b)| a + b) - .skip::<1>() - .take::<2>() + .rev() .collect(); +assert_eq!(rev_array, [7, 2, 3, 1]); -assert_eq!(res, [5, 5]); +// .. and compute sum with values of a second array multiplied by 10 +let sum_array: [_; 4] = rev_array + .into_iter_fixed() + .zip([4,1,3,7]) + .map(|(a, b)| a + (b * 10)) + .collect(); +assert_eq!(sum_array, [47, 12, 33, 71]); ``` -## Vector -see [examples/vector.rs](https://github.com/usbalbin/iter_fixed/blob/master/examples/vector.rs) +You can also take a look at examples : [`matrix.rs`] and [`vector.rs`] + +[`matrix.rs`]: source/examples/matrix.rs +[`vector.rs`]: source/examples/vector.rs + -## Matrix +Current version: 0.3.1 + +## no_std + +This crate should work without the full standard library -see [examples/matrix.rs](https://github.com/usbalbin/iter_fixed/blob/master/examples/matrix.rs) +Some additional info here -# License +# License : MIT OR Apache-2.0 `iter_fixed` is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-APACHE, and LICENSE-MIT for details. -### Contribution +## Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in iter_fixed by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/README.tpl b/README.tpl new file mode 100644 index 0000000..e55665e --- /dev/null +++ b/README.tpl @@ -0,0 +1,30 @@ +{{badges}} + +[![crates.io](https://img.shields.io/crates/v/iter_fixed.svg)](https://crates.io/crates/iter_fixed) +[![docs.rs](https://docs.rs/iter_fixed/badge.svg)](https://docs.rs/iter_fixed/) +[![dependency status](https://deps.rs/crate/iter_fixed/0.3.0/status.svg)](https://deps.rs/crate/iter_fixed/0.3.0) + +![Stable](https://github.com/usbalbin/iter_fixed/actions/workflows/stable.yml/badge.svg) +![Nightly](https://github.com/usbalbin/iter_fixed/actions/workflows/nightly.yml/badge.svg) +![Miri](https://github.com/usbalbin/iter_fixed/actions/workflows/miri.yml/badge.svg) + +# {{crate}} + +{{readme}} + +Current version: {{version}} + +## no_std + +This crate should work without the full standard library + +Some additional info here + +# License : {{license}} +`iter_fixed` is distributed under the terms of both the MIT license and +the Apache License (Version 2.0). + +See LICENSE-APACHE, and LICENSE-MIT for details. + +## Contribution +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in iter_fixed by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/src/lib.rs b/src/lib.rs index ab1b0f6..db3dfbc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,46 @@ +//! Provides a type and traits for turning collections of fixed size, like arrays, +//! into [`IteratorFixed`] which can be used a bit like an ordinary [`Iterator`] but +//! with a compile time guaranteed length. This enables us to turn them back into +//! collections of fixed size without having to perform unnecessary checks during +//! run time. +//! +//! [`IteratorFixed`] provides on stable methods like `map`, `inspect`, `enumerate`, +//! `zip`, `rev`, `copied`, `cloned`, with nightly `skip`, `step_by`, `chain`, `take`, +//! `flatten`. +//! +//! However it does not and will never be able to support methods like +//! `filter` or `take_while` which will affect the length during runtime. +//! +//! # ⚠️ Experimental +//! *This code is currently very experimental, type names, function names, trait bounds etc. are all very much subject to change.* +//! +//! # Origin +//! *This project is inspired by @leonardo-m 's idea * +//! +//! # Examples: +//! ``` +//! # use crate::iter_fixed::IntoIteratorFixed; +//! // simply reverse an Array +//! let rev_array: [_; 4] = [1, 3, 2, 7] +//! .into_iter_fixed() +//! .rev() +//! .collect(); +//! assert_eq!(rev_array, [7, 2, 3, 1]); +//! +//! // .. and compute sum with values of a second array multiplied by 10 +//! let sum_array: [_; 4] = rev_array +//! .into_iter_fixed() +//! .zip([4,1,3,7]) +//! .map(|(a, b)| a + (b * 10)) +//! .collect(); +//! assert_eq!(sum_array, [47, 12, 33, 71]); +//! ``` +//! +//! You can also take a look at examples : [`matrix.rs`] and [`vector.rs`] +//! +//! [`matrix.rs`]: source/examples/matrix.rs +//! [`vector.rs`]: source/examples/vector.rs +//! #![no_std] #![allow(stable_features)] #![cfg_attr(feature = "nightly_features", allow(incomplete_features))] @@ -26,21 +69,27 @@ pub use into::IntoIteratorFixed; /// length. This enables us to turn them back into collections of fixed size without having to /// perform unnecessary checks during run time. /// -/// Just like Iterator, `IteratorFixed` provides a lot of methods like: -/// -/// * `map` -/// * `inspect` -/// * `skip` -/// * `step_by` -/// * `chain` -/// * `enumerate` -/// * `take` -/// * `zip` -/// * `rev` -/// * `copied` -/// * `cloned` +/// Just like [`Iterator`], [`IteratorFixed`] provides a lot of methods like: +/// - available on stable rust: +/// [`map`], [`inspect`], [`enumerate`], [`zip`], [`rev`], [`copied`], [`cloned`] +/// +/// - requires nightly compiler and enable `nightly_features`: +/// [`skip`], [`step_by`], [`chain`], [`take`], [`flatten`] /// /// however it does not support methods like `filter` or `take_while` which will affect the length during runtime. +/// +/// [`map`]: IteratorFixed::map +/// [`inspect`]: IteratorFixed::inspect +/// [`enumerate`]: IteratorFixed::enumerate +/// [`zip`]: IteratorFixed::zip +/// [`rev`]: IteratorFixed::rev +/// [`copied`]: IteratorFixed::copied +/// [`cloned`]: IteratorFixed::cloned +/// [`skip`]: IteratorFixed::skip +/// [`step_by`]: IteratorFixed::step_by +/// [`chain`]: IteratorFixed::chain +/// [`take`]: IteratorFixed::take +/// [`flatten`]: IteratorFixed::flatten pub struct IteratorFixed { inner: I, }