• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Convert number to enum
2======================
3
4[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/enumn-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/enumn)
5[<img alt="crates.io" src="https://img.shields.io/crates/v/enumn.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/enumn)
6[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-enumn-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/enumn)
7[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/enumn/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/enumn/actions?query=branch%3Amaster)
8
9This crate provides a derive macro to generate a function for converting a
10primitive integer into the corresponding variant of an enum.
11
12The generated function is named `n` and has the following signature:
13
14```rust
15impl YourEnum {
16    pub fn n(value: Repr) -> Option<Self>;
17}
18```
19
20where `Repr` is an integer type of the right size as described in more
21detail below.
22
23## Example
24
25```rust
26use enumn::N;
27
28#[derive(PartialEq, Debug, N)]
29enum Status {
30    LegendaryTriumph,
31    QualifiedSuccess,
32    FortuitousRevival,
33    IndeterminateStalemate,
34    RecoverableSetback,
35    DireMisadventure,
36    AbjectFailure,
37}
38
39fn main() {
40    let s = Status::n(1);
41    assert_eq!(s, Some(Status::QualifiedSuccess));
42
43    let s = Status::n(9);
44    assert_eq!(s, None);
45}
46```
47
48## Signature
49
50The generated signature depends on whether the enum has a `#[repr(..)]`
51attribute. If a `repr` is specified, the input to `n` will be required to be
52of that type.
53
54```rust
55#[derive(enumn::N)]
56#[repr(u8)]
57enum E {
58    /* ... */
59}
60
61// expands to:
62impl E {
63    pub fn n(value: u8) -> Option<Self> {
64        /* ... */
65    }
66}
67```
68
69On the other hand if no `repr` is specified then we get a signature that is
70generic over a variety of possible types.
71
72```rust
73impl E {
74    pub fn n<REPR: Into<i64>>(value: REPR) -> Option<Self> {
75        /* ... */
76    }
77}
78```
79
80## Discriminants
81
82The conversion respects explictly specified enum discriminants. Consider
83this enum:
84
85```rust
86#[derive(enumn::N)]
87enum Letter {
88    A = 65,
89    B = 66,
90}
91```
92
93Here `Letter::n(65)` would return `Some(Letter::A)`.
94
95<br>
96
97#### License
98
99<sup>
100Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
1012.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
102</sup>
103
104<br>
105
106<sub>
107Unless you explicitly state otherwise, any contribution intentionally submitted
108for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
109be dual licensed as above, without any additional terms or conditions.
110</sub>
111