Crate certain_map

Certain Map

A typed map that ensures the existence of an item.

What Problem Does It Solve

In Rust, Service abstractions are commonly used for modular structure design, for example tower-service or service-async. Services are layered, and the Request/Response types may vary across different layers. When components across layers have data dependencies, particularly indirect ones, passing all required information by modifying the Request/Response type becomes challenging. If the number of variables to be passed fluctuates, we must redefine a struct to accommodate these changes. This requires implementing conversion functions and data extraction functions for these structs, which can be tedious and can clutter the code. Typically, we avoid this by using HashMap or TypeMap to manage information that needs to be passed across Services.

However, this approach has a significant drawback: we cannot ensure at compile time that the key-value pair required by subsequent components has been set when it is read. This can lead to unnecessary error handling branches in our program or panic in certain scenarios. This crate transforms the struct type when keys are inserted or removed, ensuring the existence of some values at compile-time.

If you need to pass information between multiple stages using a structure, this crate is ideal for you.

It upholds the promise: if it compiles, it works.

Internal workings

pub type EmptyContext = Context<::certain_map::Vacancy, ::certain_map::Vacancy>;
pub type FullContext =
    Context<::certain_map::Occupied<PeerAddr>, ::certain_map::Occupied<Option<RemoteAddr>>>;
#[derive(Debug, Clone)]
pub struct Context<_CMT_0, _CMT_1> {
    peer_addr: _CMT_0,
    remote_addr: _CMT_1,
}

// `ParamSet for PeerAddr will not compile if it has 
// been previously set.
impl<_CMT_0, _CMT_1> ::certain_map::ParamSet<PeerAddr> for Context<_CMT_0, _CMT_1> {
    type Transformed = Context<::certain_map::Occupied<PeerAddr>, _CMT_1>;
    #[inline]
    fn param_set(self, item: PeerAddr) -> Self::Transformed {
        Context {
            peer_addr: ::certain_map::Occupied(item),
            remote_addr: self.remote_addr,
        }
    }
}

// `ParamRef<PeerAddr>` trait bound will not compile for maps
// where it hasn't been set with `ParamSet<PeerAdr>.
impl<_CMT_1> ::certain_map::ParamRef<PeerAddr>
    for Context<::certain_map::Occupied<PeerAddr>, _CMT_1>
{
    #[inline]
    fn param_ref(&self) -> &PeerAddr {
        &self.peer_addr.0
    }
}

Usage

use certain_map::{certain_map, Param, ParamRef, ParamRemove, ParamSet, ParamTake};

struct UserName(String);

#[derive(Copy, Clone)]
struct UserAge(u8);

certain_map! {
    pub struct MyCertainMap {
        name: UserName,
        #[ensure(Clone)]
        age: UserAge,
    }
}

fn main() {
    let meta = MyCertainMap::new();

    // The following line fails to compile since there's no UserName in the map.
    // log_username(&meta);

    let meta = meta.param_set(UserName("ihciah".to_string()));
    // Now we can get it with certainty.
    log_username(&meta);

    let (meta, removed) = ParamTake::<UserName>::param_take(meta);
    assert_eq!(removed.0, "ihciah");
    // The following line fails to compile since the UserName is removed.
    // log_username(&meta);

    // We can also remove a type no matter if it exist.
    let meta = ParamRemove::<UserName>::param_remove(meta);

    let meta = meta.param_set(UserAge(24));
    // We can get ownership of fields with #[ensure(Clone)]
    log_age(&meta);
}

fn log_username<T: ParamRef<UserName>>(meta: &T) {
    println!("username: {}", meta.param_ref().0);
}

fn log_age<T: Param<UserAge>>(meta: &T) {
    println!("user age: {}", meta.param().0);
}

Macros

• certain_map
  Re-export macro.

Structs

• Occupied
  Represents an occupied slot in a certain_map slot.
• Vacancy
  Represents a vacant slot in a certain map.

Traits

• Param
  Item of type T has been set in a certain_map slot.
• ParamMaybeMut
  Item of type T may have been set in a certain_map slot and returns Option<&mut T>.
• ParamMaybeRef
  Item of type T may have been set in a certain_map slot and returns Option<&T>
• ParamMut
  Item of type T has been set in a certain_map slot and returns a mutable reference.
• ParamRef
  Item of type T has been set in a certain_map slot and returns a reference.
• ParamRemove
  Item of type T can be removed certain_map slot irrespective of it having been set before.
• ParamSet
  Item of type T is vacant in certain_map slot.
• ParamTake
  Item of type T has been set in certain_map slot and can be removed from the slot, leaving it vacant.