typewit_gce 0.1.1

for coercing between equal types with generic const arguments
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

[![Rust](https://github.com/rodrimati1992/typewit_gce/workflows/Rust/badge.svg)](https://github.com/rodrimati1992/typewit_gce/actions)
[![crates-io](https://img.shields.io/crates/v/typewit_gce.svg)](https://crates.io/crates/typewit_gce)
[![api-docs](https://docs.rs/typewit_gce/badge.svg)](https://docs.rs/typewit_gce/*)

For coercing between equal types that use Generic Const Expressions as arguments.

Generic Const Expressions: 
const expresions that use generic parameters from the surrounding item.
To use as generic arguments, this currently requires the [`generic_const_exprs`]
unstable feature.

# Example

Currently (2025-10-13), 
rustc does not allow using a generic `[T; N * M]` where `[T; M * N]` is expected,
so this code:
```rust
#![feature(generic_const_exprs)]

assert_eq!(generate_array::<2>(), [0, 1, 0, 1, 0, 1]);

fn generate_array<const N: usize>() -> [u8; 3 * N] 
where
    [(); N * 3]:
{
    generate_array_b::<N>()
}

fn generate_array_b<const N: usize>() -> [u8; N * 3] {
    std::array::from_fn(|i| (i % N) as u8)
}
```
fails to compile with this error:
```text
error[E0308]: mismatched types
  --> src/lib.rs:23:5
   |
12 |     generate_array_b::<N>()
   |     ^^^^^^^^^^^^^^^^^^^^^^^ expected `3 * N`, found `N * 3`
   |
   = note: expected constant `3 * N`
              found constant `N * 3`
```

Because the compiler can't prove that most equivalent expressions are equal,
this library provides the [`gce_int_eq`] macro for
the purpose of enabling some coercions between equal const-generic types:
```rust
#![feature(generic_const_exprs)]

use typewit_gce::{TypeEq, gce_int_eq};


assert_eq!(generate_array::<2>(), [0, 1, 0, 1, 0, 1]);


fn generate_array<const N: usize>() -> [u8; 3 * N] 
where
    [(); N * 3]:
{
    // a proof that `[u8; N * 3] == [u8; 3 * N]`, 
    // which allows coercing between the two types
    let coercer: TypeEq<[u8; N * 3], [u8; 3 * N]> = 
        TypeEq::NEW.in_array(gce_int_eq!(N * 3, 3 * N));
    
    // coerces `[u8; N * 3]` to the equivalent `[u8; 3 * N]`
    coercer.to_right(generate_array_b::<N>())
}

fn generate_array_b<const N: usize>() -> [u8; N * 3] {
    std::array::from_fn(|i| (i % N) as u8)
}
```
the above code compiles and runs without errors.
Of note is that this does not require additional bounds relative to the original code!


# Reexports

This library reexports all items from `typewit = "1.14.0"`

# No-std support

`typewit_gce` is `#![no_std]`, it can be used anywhere Rust can be used.

# Minimum Supported Rust Version

`typewit_gce` requires Rust nightly due to being made for use with the
[`generic_const_exprs`] feature.


[`generic_const_exprs`
]: https://doc.rust-lang.org/unstable-book/language-features/generic-const-exprs.html
[`gce_int_eq`]: https://docs.rs/typewit_gce/latest/typewit_gce/macro.gce_int_eq.html