# `cisness`
Crate containing a type to "live-witness" that two types are the same (["cismutable"][cismute]).
In particular, it lets you assert that a codepath will not actually be executed at runtime if the types are NOT the same (and panic if it does), which is useful for - for instance - checking types via [`TypeId`][typeid], and selecting operations with type-specific output where you want the type specificity can be transferred to the user.
The key structure you want to use this library, is [`LiveWitness`][live-witness]. Using it "bare" from this library is somewhat clunky, but it can be used to build better abstractions (the author is working on a small crate called `tisel` that isn't published yet that will use this as a basis).
## Example
Here's an example of how to use [`LiveWitness`][live-witness] to invoke a trait method that has an associated type that can be output. Of course, in such a simple case, this isn't very useful, but it is much more useful in other situations.
```rust
use cisness::LiveWitness;
use std::{collections::HashMap, any::{TypeId, Any}};
pub trait PartyMember {
type Age: core::fmt::Display;
fn get_age(&self) -> Self::Age;
}
#[derive(Debug, Clone)]
pub struct Human {
pub name: String,
pub age: u32,
}
impl PartyMember for Human {
type Age = u32;
fn get_age(&self) -> Self::Age {
self.age
}
}
#[derive(Debug, Clone)]
pub struct Dragon {
pub name: String
}
impl PartyMember for Dragon {
type Age = &'static str;
fn get_age(&self) -> Self::Age {
"Unknowable and Eldritch"
}
}
/// Party that stores the vocabulary "member" types in one hashmap dynamically.
/// Note that clearly, in this case, there are better ways to do it - but often that would not be the case.
#[derive(Default)]
pub struct AdventuringParty {
// Maps the `Member` type id to a vector of members of that type.
members: HashMap<TypeId, Box<dyn Any>>
}
impl AdventuringParty {
pub fn add_member<M: Any>(&mut self, member: M) {
let new_member_typeid = TypeId::of::<M>();
self.members
.entry(new_member_typeid)
.or_insert_with(|| Box::new(Vec::<M>::new()))
.downcast_mut::<Vec::<M>>()
.expect("<typeid> is mapped to Vec<type for typeid> and we just inited")
.push(member);
}
// Note here - the better way to do this specific example would be to put a trait criteria on
// the `M` generic requiring `Ord`, and doing downcasting. However, for illustration purposes, we'll
// be listing out supported types and manually implementing them, returning `None` for unorderable ages.
pub fn get_oldest_age_of_type<M: Any + PartyMember>(&self) -> Option<<M as PartyMember>::Age>
{
// Note that you could do this with `Any::downcast_ref`. However, that doesn't work if you can't
// get a value of `M`, and it doesn't work as well for more complex cases.
// To illustrate, we're going to use TypeId matching, even if for this case it would work better not to do that.
let type_id = TypeId::of::<M>();
match type_id {
t if t == TypeId::of::<Human>() => {
// Note here that we don't have to directly witness the type of the generic parameter, we can instead witness
// the output (if we know it), or a vector.
// In this case, we're asserting that we'll only run through this code if the output type is the same as
// `Option<Human::Age>` - this lets us do "magical" coercions that will panic if we've made an error.
let w = LiveWitness::<Option<<Human as PartyMember>::Age>, Option<M::Age>>::only_executed_if_same();
let output = self.members.get(&t)
.and_then(|v| v.downcast_ref::<Vec<Human>>())
.map(|v| v.iter().map(PartyMember::get_age).max()).flatten();
// Note here - our witness lets us turn this to the generic output, and will typecheck even if `M` != `Human` - because we don't go down
// this path, it's fine.
w.owned(output)
},
t if t == TypeId::of::<Dragon>() => {
let w = LiveWitness::<Option<<Dragon as PartyMember>::Age>, Option<M::Age>>::only_executed_if_same();
if !self.members.get(&t).is_some() { return None };
// Note how at no point here did we actually have to downcast any values.
let output = Some("[ELDRICH MEMETIC HAZARD]");
w.owned(output)
}
_ => None
}
}
}
```
## The Name
Yes, it's intentional. The author is trans 🏳️⚧️, and finds it funny.
[live-witness]: https://docs.rs/cisness/latest/cisness/struct.LiveWitness.html
[cismute]: https://docs.rs/cismute
[typeid]: https://doc.rust-lang.org/nightly/core/any/struct.TypeId.html