romap 0.4.0

A trait for read-only-maps
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
95
96
97
98
99
100
101

#![cfg_attr(not(feature = "std"), no_std)]
#![allow(rustdoc::redundant_explicit_links)]
//! The [`RoMap`](RoMap) trait describes a read-only-map.
//! It is intended to allow library authors more flexibility in the types they accept.
//!
//! This crate includes combinators and implementations for common containers.
//!
//! ```rust
//! # use std::collections::{BTreeMap, HashMap};
//! use romap::{deref_value, project_value, union, RoMap};
//! # struct Cat;
//! # struct Dog;
//! # trait Pet:'static{}
//! # impl Pet for Dog{}
//! # impl Pet for Cat{}
//!
//! trait MyPetListTrait {
//!     fn cats(&self) -> impl RoMap<str, Cat>;
//!     fn dogs(&self) -> impl RoMap<str, Dog>;
//!     fn all_pets(&self) -> impl RoMap<str, dyn Pet> {
//!         union(
//!             project_value(self.cats(), |p| p as &dyn Pet),
//!             project_value(self.dogs(), |p| p as &dyn Pet),
//!         )
//!     }
//! }
//!
//! struct MyPetListImpl {
//!     cats: HashMap<String, Cat>,
//!     dogs: BTreeMap<&'static str, Box<Dog>>,
//! }
//!
//! impl MyPetListTrait for MyPetListImpl {
//!     fn cats(&self) -> impl RoMap<str, Cat> {
//!         &self.cats
//!     }
//!
//!     fn dogs(&self) -> impl RoMap<str, Dog> {
//!         deref_value(&self.dogs)
//!     }
//! }
//! ```

pub use discard_values::discard_values;
pub use empty::Empty;
pub use filter::{filter_key, filter_kv};
pub use union::union;
pub use value_projection::{deref_value, project_value};
mod discard_values;
mod filter;

/// The concrete combinator types
pub mod structs {
    pub use crate::discard_values::DiscardValues;
    pub use crate::filter::{FilterKey, FilterKv};
    pub use crate::union::Union;
}
mod either;
mod empty;
mod option;
#[cfg(feature = "std")]
mod std_maps;
#[cfg(feature = "test_utils")]
pub mod test_utils;
mod union;
mod value_projection;

/// A read-only-map.
pub trait RoMap<'a, K: 'a + ?Sized, V: 'a + ?Sized>: 'a + Copy {
    /// If true, then all iterators returned by methods of this trait return elements sorted by their keys.
    const ITER_ORDER_SORTED: bool = false;

    fn contains_key(self, k: &K) -> bool {
        self.get_key(k).is_some()
    }
    fn get(self, k: &K) -> Option<&'a V> {
        Some(self.get_key_value(k)?.1)
    }
    fn get_key(self, k: &K) -> Option<&'a K> {
        Some(self.get_key_value(k)?.0)
    }
    fn get_key_value(self, k: &K) -> Option<(&'a K, &'a V)>;

    fn is_empty(self) -> bool {
        self.len() == 0
    }

    fn len(self) -> usize {
        self.keys().count()
    }

    fn keys(self) -> impl 'a + Iterator<Item = &'a K> {
        self.iter().map(|(k, _)| k)
    }
    /// Values are returned in an arbitrary order, not necessarily the same order as returned by [keys](Self::keys).
    /// If [ITER_ORDER_SORTED](Self::ITER_ORDER_SORTED) is true, values are guaranteed to be ordered by their keys.
    fn values(self) -> impl 'a + Iterator<Item = &'a V> {
        self.iter().map(|(_, v)| v)
    }
    fn iter(self) -> impl 'a + Iterator<Item = (&'a K, &'a V)>;
}