Merge pull request #9 from rodrimati1992/1_7_0

1.7.0

Author: rodrimati1992

.github/workflows/rust.yml

@@ -17,14 +17,18 @@ jobs:
     strategy:
       max-parallel: 2
       matrix:
-        rust: [stable, beta, nightly, 1.61.0, 1.57.0]
+        rust: [stable, beta, nightly, 1.65.0, 1.61.0, 1.57.0]
 
     steps:
     - uses: actions/checkout@v2
     - name: enable-rust-1_61
       if: matrix.rust == '1.61.0'
       run: echo "rustv=rust_1_61" >> $GITHUB_ENV
 
+    - name: enable-rust-1_65
+      if: matrix.rust == '1.65.0'
+      run: echo "rustv=rust_1_65" >> $GITHUB_ENV
+
     - name: enable-rust-stable
       if: matrix.rust == 'stable' || matrix.rust == 'beta' || matrix.rust == 'nightly'
       run: echo "rustv=rust_stable" >> $GITHUB_ENV

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "typewit"
-version = "1.6.0"
+version = "1.7.0"
 authors = ["rodrimati1992 <rodrimatt1985@gmail.com>"]
 rust-version = "1.57.0"
 edition = "2021"
@@ -28,7 +28,9 @@ version = "1.0"
 [features]
 default = ["const_marker"]
 rust_1_61 = []
-rust_stable = ["rust_1_61"]
+# mostly for doc examples
+rust_1_65 = ["rust_1_61"]
+rust_stable = ["rust_1_65"]
 const_marker = []
 adt_const_marker = ["rust_stable","const_marker"]
 alloc = []

Changelog.md

@@ -2,6 +2,10 @@ This is the changelog, summarising changes in each version(some minor changes ma
 
 # 1.0
 
+### 1.7.0
+
+Added `polymatch` macro.
+
 ### 1.6.0
 
 Added `"adt_const_marker"` feature.

README.md

@@ -7,7 +7,7 @@ This crate provides abstractions for creating
 [type witnesses](#what-are-type-witnesses).
 
 The inciting motivation for this crate is emulating trait polymorphism in `const fn`
-(as of 2023-07-31, it's not possible to call trait methods in const contexts on stable).
+(as of 2023-09-10, it's not possible to call trait methods in const contexts on stable).
 
 # What are type witnesses
 
@@ -27,7 +27,7 @@ which can coerce between a type parameter and as many types as there are variant
 ### Polymorphic function
 
 This demonstrates how one can write a return-type-polymorphic `const fn`
-(as of 2023-07-31, trait methods can't be called in const fns)
+(as of 2023-09-10, trait methods can't be called in const fns on stable)
 
 ```rust
 use typewit::{MakeTypeWitness, TypeEq};
@@ -75,7 +75,7 @@ typewit::simple_type_witness! {
 This function demonstrates const fn polymorphism
 and projecting [`TypeEq`] by implementing [`TypeFn`].
 
-(this example requires Rust 1.61.0, because of the `I: SliceIndex<T>,` bound)
+(this example requires Rust 1.71.0, because it uses `<[T]>::split_at` in a const context.
 ```rust
 use std::ops::Range;
 
@@ -154,6 +154,12 @@ typewit::type_fn! {
 
     impl<I: SliceIndex<T>> I => SliceIndexRet<I, T>
 }
+
+const fn slice_range<T>(slice: &[T], range: Range<usize>) -> &[T] {
+    let suffix = slice.split_at(range.start).1;
+    suffix.split_at(range.end - range.start).0
+}
+
 ```
 
 When the wrong type is passed for the index,
@@ -217,6 +223,156 @@ typewit::type_fn!{
     impl<const N: usize> Usize<N> => Arr<N>
 }
 ```
+### Builder
+
+Using a type witness to help encode a type-level enum,
+and to match on that type-level enum inside of a function.
+
+The type-level enum is used to track the initialization of fields in a builder.
+
+This example requires Rust 1.65.0, because it uses Generic Associated Types.
+```rust
+use typewit::HasTypeWitness;
+
+fn main() {
+    // all default fields
+    assert_eq!(
+        StructBuilder::new().build(), 
+        Struct{foo: "default value".into(), bar: vec![3, 5, 8]},
+    );
+
+    // defaulted bar field
+    assert_eq!(
+        StructBuilder::new().foo("hello").build(), 
+        Struct{foo: "hello".into(), bar: vec![3, 5, 8]},
+    );
+
+    // defaulted foo field
+    assert_eq!(
+        StructBuilder::new().bar([13, 21, 34]).build(), 
+        Struct{foo: "default value".into(), bar: vec![13, 21, 34]},
+    );
+
+    // all initialized fields
+    assert_eq!(
+        StructBuilder::new().foo("world").bar([55, 89]).build(), 
+        Struct{foo: "world".into(), bar: vec![55, 89]},
+    );
+}
+
+
+#[derive(Debug, PartialEq, Eq)]
+struct Struct {
+    foo: String,
+    bar: Vec<u32>,
+}
+
+struct StructBuilder<FooInit: InitState, BarInit: InitState> {
+    // If `FooInit` is `Uninit`, then this field is a `()`
+    // If `FooInit` is `Init`, then this field is a `String`
+    foo: BuilderField<FooInit, String>,
+
+    // If `BarInit` is `Uninit`, then this field is a `()`
+    // If `BarInit` is `Init`, then this field is a `Vec<u32>`
+    bar: BuilderField<BarInit, Vec<u32>>,
+}
+
+impl StructBuilder<Uninit, Uninit> {
+    pub const fn new() -> Self {
+        Self {
+            foo: (),
+            bar: (),
+        }
+    }
+}
+
+impl<FooInit: InitState, BarInit: InitState> StructBuilder<FooInit, BarInit> {
+    /// Sets the `foo` field
+    pub fn foo(self, foo: impl Into<String>) -> StructBuilder<Init, BarInit> {
+        StructBuilder {
+            foo: foo.into(),
+            bar: self.bar,
+        }
+    }
+
+    /// Sets the `bar` field
+    pub fn bar(self, bar: impl Into<Vec<u32>>) -> StructBuilder<FooInit, Init> {
+        StructBuilder {
+            foo: self.foo,
+            bar: bar.into(),
+        }
+    }
+
+    /// Builds `Struct`, 
+    /// providing default values for fields that haven't been set.
+    pub fn build(self) -> Struct {
+        typewit::type_fn! {
+            struct HelperFn<T>;
+            impl<I: InitState> I => BuilderField<I, T>
+        }
+
+        Struct {
+            // matching on the type-level `InitState` enum by using `InitWit`.
+            // `WITNESS` comes from the `HasTypeWitness` trait
+            foo: match FooInit::WITNESS {
+                // `te: TypeEq<FooInit, Init>`
+                InitWit::InitW(te) => {
+                    te.map(HelperFn::NEW) //: TypeEq<BuilderField<FooInit, String>, String>
+                      .to_right(self.foo)
+                }
+                InitWit::UninitW(_) => "default value".to_string(),
+            },
+            bar: match BarInit::WITNESS {
+                // `te: TypeEq<BarInit, Init>`
+                InitWit::InitW(te) => {
+                    te.map(HelperFn::NEW) //: TypeEq<BuilderField<BarInit, Vec<u32>>, Vec<u32>>
+                      .to_right(self.bar)
+                }
+                InitWit::UninitW(_) => vec![3, 5, 8],
+            },
+        }
+    }
+}
+
+// Emulates a type-level `enum InitState { Init, Uninit }`
+trait InitState: Sized + HasTypeWitness<InitWit<Self>> {
+    // How a builder represents an initialized/uninitialized field.
+    // If `Self` is `Uninit`, then this is `()`.
+    // If `Self` is `Init`, then this is `T`.
+    type BuilderField<T>;
+}
+
+// If `I` is `Uninit`, then this evaluates to `()`
+// If `I` is `Init`, then this evaluates to `T`
+type BuilderField<I, T> = <I as InitState>::BuilderField::<T>;
+
+// Emulates a type-level `InitState::Init` variant.
+// Marks a field as initialized.
+enum Init {}
+
+impl InitState for Init {
+    type BuilderField<T> = T;
+}
+
+// Emulates a type-level `InitState::Uninit` variant
+// Marks a field as uninitialized.
+enum Uninit {}
+
+impl InitState for Uninit {
+    type BuilderField<T> = ();
+}
+
+typewit::simple_type_witness! {
+    // Declares `enum InitWit<__Wit>`, a type witness.
+    // (the `__Wit` type parameter is implicitly added after all generics)
+    enum InitWit {
+        // This variant requires `__Wit == Init`
+        InitW = Init,
+        // This variant requires `__Wit == Uninit`
+        UninitW = Uninit,
+    }
+}
+```
 
 
 # Cargo features

src/const_marker/const_witnesses.rs

@@ -31,6 +31,7 @@ use crate::{
 ///         impl<const B: bool> Bool<B> => Incrementor<B>
 ///     }
 /// 
+///     // The example below this one shows how to write this match more concisely
 ///     match BoolWit::MAKE {
 ///         // `bw: TypeEq<Bool<B>, Bool<true>>`
 ///         BoolWit::True(bw) => {
@@ -76,6 +77,49 @@ use crate::{
 /// 
 /// ```
 /// 
+/// ### Using `polymatch` for conciseness
+/// 
+/// The [`polymatch`](crate::polymatch) macro can be used to 
+/// more concisely implement the `call_next` function.
+/// 
+/// ```
+/// # use typewit::{const_marker::{Bool, BoolWit}, MakeTypeWitness};
+/// # 
+/// const fn call_next<const B: bool>(incrementor: Incrementor<B>) -> Incrementor<B> {
+///     typewit::type_fn! {
+///         struct IncrementorFn;
+///         impl<const B: bool> Bool<B> => Incrementor<B>
+///     }
+/// 
+///     // expands to a match with two arms, 
+///     // one for `BoolWit::True` and one for `BoolWit::False`,
+///     // copying the expression to the right of the `=>` to both arms.
+///     typewit::polymatch! {BoolWit::MAKE;
+///         BoolWit::True(bw) | BoolWit::False(bw) => {
+///             let te = bw.project::<IncrementorFn>();
+///             te.to_left(te.to_right(incrementor).next())
+///         }
+///     }
+/// }
+/// # 
+/// # #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// # struct Incrementor<const GO_UP: bool>(usize);
+/// # 
+/// # const GO_UP: bool = true;
+/// # const GO_DOWN: bool = false;
+/// # 
+/// # impl Incrementor<GO_DOWN> {
+/// #     #[track_caller]
+/// #     pub const fn next(self) -> Self { unimplemented!() }
+/// # }
+/// # 
+/// # impl Incrementor<GO_UP> {
+/// #     pub const fn next(self) -> Self { unimplemented!() }
+/// # }
+/// ```
+/// 
+/// ### What happens without `BoolWit`
+/// 
 /// If the `call_next` function was defined like this:
 /// ```rust,compile_fail
 /// # use typewit::{const_marker::{Bool, BoolWit}, MakeTypeWitness};