ty_map_gen 0.1.0

A type projecting map generator.
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

# ty_map_gen

[![Crates.io](https://img.shields.io/crates/v/ty_map_gen.svg)](https://crates.io/crates/ty_map_gen)
[![Docs](https://docs.rs/ty_map_gen/badge.svg)](https://docs.rs/ty_map_gen/latest/ty_map_gen/)

A type projecting map generator.

## Syntax

```rust
type_map!(
    /// Asset Map
    #[derive(Clone, Eq)]
    pub AssetMap where T [Asset] => Handle<T> [Clone + Eq] as HashMap
);
```

This creates a type that projects `T` (a generic) to `Handle<T>` (roughly):

```rust
pub struct AssetMap(HashMap<TypeId, Box<dyn Any>>)
```

with access methods (roughly):

```rust
fn get<T: Asset + 'static>(&self) -> Option<&Handle<T>> where Handle<T>: Clone + Eq {
    self.0.get(TypeId::of::<T>()).and_then(|v| v.downcast_ref())
}
```

Since all values stored in the map are `Clone` and `Eq`, they can be derived.

The `as HashMap` field accepts all structs that has the same api
as `HashMap`, this includes `BTreeMap` and third party types
like `FxHashMap` or `VecMap`. To specify a custom hasher, you must
define a new `type` with signature `Map<Key, Value>`.

## Bounds

Bounds (in braces `[]`) are optional in the macro. The bounds on the right hand side must be object safe,
excluding `Clone`, `PartialEq`, `Eq`, `Ord`, `PartialOrd`, `Hash` and `Serialize`,
which are special handled. Additionally only one trait from `std::cmp` is allowed to be specified.

## Methods and Implementations

By default these methods are generated by the macro:

`Default`, `new`, `is_empty`, `len`, `get`, `get_mut`, `insert`, `remove`, `clear`.

## Double Keys

```rust
type_map!(
    /// Asset Map
    #[derive(Clone, Eq)]
    pub AssetMap where (T, String) [Asset] => Handle<T> [Clone + Eq] as HashMap
);
```

This adds another key to the map, with access methods (roughly):

```rust
fn get<T: Asset + 'static>(&self, key: &Q) -> Option<&Handle<T>> where Handle<T>: Clone + Eq {
    self.0.get(&(TypeId::of::<T>(), key)).and_then(|v| v.downcast_ref())
}
```

## Performance

This crate has faster lookup (`get` and `get_mut`) than a naive implementation with `Box<dyn Any>`
since downcasting is unchecked.

## License

License under either of

Apache License, Version 2.0 (LICENSE-APACHE or <http://www.apache.org/licenses/LICENSE-2.0>)
MIT license (LICENSE-MIT or <http://opensource.org/licenses/MIT>)
at your option.

## Contribution

Contributions are welcome!

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.