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 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
//! # Strum //! //! [](https://travis-ci.org/Peternator7/strum) //! [](https://crates.io/crates/strum) //! [](https://docs.rs/strum) //! //! Strum is a set of macros and traits for working with //! enums and strings easier in Rust. //! //! The full version of the README can be found on [Github](https://github.com/Peternator7/strum). //! //! # Including Strum in Your Project //! //! Import strum and strum_macros into your project by adding the following lines to your //! Cargo.toml. Strum_macros contains the macros needed to derive all the traits in Strum. //! //! ```toml //! [dependencies] //! strum = "0.18.0" //! strum_macros = "0.18.0" //! ``` //! //! And add these lines to the root of your project, either lib.rs or main.rs. //! //! ```rust //! // Strum contains all the trait definitions //! extern crate strum; //! #[macro_use] //! extern crate strum_macros; //! # fn main() {} //! ``` //! //! # Strum Macros //! //! Strum has implemented the following macros: //! //! | Macro | Description | //! | --- | ----------- | //! | [EnumString] | Converts strings to enum variants based on their name | //! | [Display] | Converts enum variants to strings | //! | [AsRefStr] | Converts enum variants to `&'static str` | //! | [IntoStaticStr] | Implements `From<MyEnum> for &'static str` on an enum | //! | [EnumVariantNames] | Implements Strum::VariantNames which adds an associated constant `VARIANTS` which is an array of discriminant names | //! | [EnumIter] | Creates a new type that iterates of the variants of an enum. | //! | [EnumProperty] | Add custom properties to enum variants. | //! | [EnumMessage] | Add a verbose message to an enum variant. | //! | [EnumDiscriminants] | Generate a new type with only the discriminant names. | //! | [EnumCount] | Add a constant `usize` equal to the number of variants. | //! //! [EnumString]: https://github.com/Peternator7/strum/wiki/Derive-EnumString //! [Display]: https://github.com/Peternator7/strum/wiki/Derive-Display //! [AsRefStr]: https://github.com/Peternator7/strum/wiki/Derive-AsRefStr //! [IntoStaticStr]: https://github.com/Peternator7/strum/wiki/Derive-IntoStaticStr //! [EnumVariantNames]: https://github.com/Peternator7/strum/wiki/Derive-EnumVariantNames //! [EnumIter]: https://github.com/Peternator7/strum/wiki/Derive-EnumIter //! [EnumProperty]: https://github.com/Peternator7/strum/wiki/Derive-EnumProperty //! [EnumMessage]: https://github.com/Peternator7/strum/wiki/Derive-EnumMessage //! [EnumDiscriminants]: https://github.com/Peternator7/strum/wiki/Derive-EnumDiscriminants //! [EnumCount]: https://github.com/Peternator7/strum/wiki/Derive-EnumCount /// The ParseError enum is a collection of all the possible reasons /// an enum can fail to parse from a string. #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)] pub enum ParseError { VariantNotFound, } impl std::fmt::Display for ParseError { fn fmt(&self, f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> { // We could use our macro here, but this way we don't take a dependency on the // macros crate. match self { ParseError::VariantNotFound => write!(f, "Matching variant not found"), } } } impl std::error::Error for ParseError { fn description(&self) -> &str { match self { ParseError::VariantNotFound => { "Unable to find a variant of the given enum matching the string given. Matching \ can be extended with the Serialize attribute and is case sensitive." } } } } /// This trait designates that an `Enum` can be iterated over. It can /// be auto generated using `strum_macros` on your behalf. /// /// # Example /// /// ```rust /// # extern crate strum; /// # #[macro_use] extern crate strum_macros; /// # use std::fmt::Debug; /// // You need to bring the type into scope to use it!!! /// use strum::IntoEnumIterator; /// /// #[derive(EnumIter,Debug)] /// enum Color { /// Red, /// Green { range:usize }, /// Blue(usize), /// Yellow, /// } /// /// // Iterate over the items in an enum and perform some function on them. /// fn generic_iterator<E, F>(pred: F) /// where /// E: IntoEnumIterator, /// F: Fn(E), /// { /// for e in E::iter() { /// pred(e) /// } /// } /// /// fn main() { /// generic_iterator::<Color, _>(|color| println!("{:?}", color)); /// } /// ``` pub trait IntoEnumIterator: Sized { type Iterator: Iterator<Item = Self>; fn iter() -> Self::Iterator; } /// Associates additional pieces of information with an Enum. This can be /// autoimplemented by deriving `EnumMessage` and annotating your variants with /// `#[strum(message="...")]. /// /// # Example /// /// ```rust /// # extern crate strum; /// # #[macro_use] extern crate strum_macros; /// # use std::fmt::Debug; /// // You need to bring the type into scope to use it!!! /// use strum::EnumMessage; /// /// #[derive(PartialEq, Eq, Debug, EnumMessage)] /// enum Pet { /// #[strum(message="I have a dog")] /// #[strum(detailed_message="My dog's name is Spots")] /// Dog, /// #[strum(message="I don't have a cat")] /// Cat, /// } /// /// fn main() { /// let my_pet = Pet::Dog; /// assert_eq!("I have a dog", my_pet.get_message().unwrap()); /// } /// ``` pub trait EnumMessage { fn get_message(&self) -> Option<&str>; fn get_detailed_message(&self) -> Option<&str>; fn get_serializations(&self) -> &[&str]; } /// EnumProperty is a trait that makes it possible to store additional information /// with enum variants. This trait is designed to be used with the macro of the same /// name in the `strum_macros` crate. Currently, the only string literals are supported /// in attributes, the other methods will be implemented as additional attribute types /// become stabilized. /// /// # Example /// /// ```rust /// # extern crate strum; /// # #[macro_use] extern crate strum_macros; /// # use std::fmt::Debug; /// // You need to bring the type into scope to use it!!! /// use strum::EnumProperty; /// /// #[derive(PartialEq, Eq, Debug, EnumProperty)] /// enum Class { /// #[strum(props(Teacher="Ms.Frizzle", Room="201"))] /// History, /// #[strum(props(Teacher="Mr.Smith"))] /// #[strum(props(Room="103"))] /// Mathematics, /// #[strum(props(Time="2:30"))] /// Science, /// } /// /// fn main() { /// let history = Class::History; /// assert_eq!("Ms.Frizzle", history.get_str("Teacher").unwrap()); /// } /// ``` pub trait EnumProperty { fn get_str(&self, prop: &str) -> Option<&'static str>; fn get_int(&self, _prop: &str) -> Option<usize> { Option::None } fn get_bool(&self, _prop: &str) -> Option<bool> { Option::None } } /// A cheap reference-to-reference conversion. Used to convert a value to a /// reference value with `'static` lifetime within generic code. /// #[deprecated(since="0.13.0", note="please use `#[derive(IntoStaticStr)]` instead")] pub trait AsStaticRef<T> where T: ?Sized, { fn as_static(&self) -> &'static T; } /// A trait for capturing the number of variants in Enum. This trait can be autoderived by /// `strum_macros`. pub trait EnumCount { const COUNT: usize; } /// A trait for retrieving the names of each variant in Enum. This trait can /// be autoderived by `strum_macros`. pub trait VariantNames { /// Names of the variants of this enum const VARIANTS: &'static [&'static str]; } #[cfg(feature = "derive")] #[allow(unused_imports)] #[macro_use] extern crate strum_macros; #[cfg(feature = "derive")] #[doc(hidden)] pub use strum_macros::*;