strflags 0.3.0

A string-enum and string-flags with fixed variants that can also accept arbitrary data.
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

# strflags

A string-enum and string-flags with fixed variants that can also accept arbitrary data.

This is more extensible than traditional enums, bitflags or enumset,
while being more ergonomic and more typo-resiliant than a set of strings like `HashSet<String>`.

## Example

```rust
pub str_flags! {
    #[derive(PartialOrd)]
    pub Color: [
        Red,
        Green,
        DarkBlue,
    ]
}
```

### This Generates

`pub struct Color(..)`

And consts:

* `pub const Red: Color = "red";`
* `pub const Green: Color = "green";`
* `pub const DarkBlue: Color = "darkblue";`

**Note:** The implementation is not `&'static str` and subject to change.

### And auto implements

* `Debug`, `Clone`, `Eq`, `Hash`
* `Display`
* `FromStr`
* `Borrow<str>`
* `AsRef<str>`
* `PartialEq<impl AsRef<str>>`
* `Into<Flags<Self>>`
* `BitOr<Output = Flags<Self>>`
* `Serialize`, with the `serde` feature enabled
* `Deserialize`, with the `serde` feature enabled

### `str_enum!()`

use the `str_enum!()` macro to opt out of flags related features.

### Flags

You can create a `Flags<Color>` like this.

```rust
let flags = Color::Red | Color::Green | Color::new("Yellow");
```

## Format

We stores all data in `flatlowercase`
to avoid case mismatches and some typos.

## Serialization and Deserialization

We use a string to serialize our "string enums".
e.g. `"red"`
We use a csv like string to serialize our `Flags`
e.g. `"dog|cat|giraffe"`
This ensures converting from enum to `Flags` does not break serialization formats.

## The `debug` feature

Allowing any string to be an enum variant is obviously prone to typos.
When the debug feature is enabled, we performs a fuzzy string check
every time a comparison is made and emit a `warn!`
though the `log` crate
if similar strings are found.
This is obviously slow so be careful when using this feature.

## Warning

Currently we use [`EcoString`](https://docs.rs/ecow/latest/ecow/string/struct.EcoString.html)
which can only inline 15 bytes. Having a larger compile time constant string
is a ***runtime*** error if the constant is **USED**.

A proc macro implementation in the future will address this issue.