From 8f4b640806648f5c716e083a8b1841792700d4a4 Mon Sep 17 00:00:00 2001 From: Azriel Hoh Date: Wed, 19 Sep 2018 09:10:48 +1200 Subject: [PATCH] Updated documentation. Issue #21 --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++-------- strum/src/lib.rs | 51 ++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 86 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index b7b63317..d3d80f37 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ Cargo.toml. Strum_macros contains the macros needed to derive all the traits in ```toml [dependencies] -strum = "0.10.0" -strum_macros = "0.10.0" +strum = "0.11.0" +strum_macros = "0.11.0" ``` And add these lines to the root of your project, either lib.rs or main.rs. @@ -91,10 +91,10 @@ Strum has implemented the following macros: */ ``` - Note that the implementation of `FromStr` only matches on the name of the variant. - Strum, where possible, avoids operations that have an unknown runtime cost, and parsing strings - is potentially an expensive operation. If you do need that behavior, consider the more powerful - Serde library for your serialization. + Note that the implementation of `FromStr` by default only matches on the name of the + variant. There is an option to match on different case conversions through the + `#[strum(serialize_all = "snake_case")]` type attribute. See the **Additional Attributes** + Section for more information on using this feature. 2. `Display` / `ToString`: prints out the given enum. This enables you to perform round trip style conversions from enum into string and back again for unit style variants. `ToString` and @@ -298,8 +298,43 @@ Strum has implemented the following macros: # Additional Attributes -Strum supports several custom attributes to modify the generated code. Custom attributes are -applied to a variant by adding #[strum(parameter="value")] to the variant. +Strum supports several custom attributes to modify the generated code. At the enum level, the +`#[strum(serialize_all = "snake_case")]` attribute can be used to change the case used when +serializing to and deserializing from strings: + +```rust +extern crate strum; +#[macro_use] +extern crate strum_macros; + +#[derive(Debug, Eq, PartialEq, ToString)] +#[strum(serialize_all = "snake_case")] +enum Brightness { + DarkBlack, + Dim { + glow: usize, + }, + #[strum(serialize = "bright")] + BrightWhite, +} + +fn main() { + assert_eq!( + String::from("dark_black"), + Brightness::DarkBlack.to_string().as_ref() + ); + assert_eq!( + String::from("dim"), + Brightness::Dim { glow: 0 }.to_string().as_ref() + ); + assert_eq!( + String::from("bright"), + Brightness::BrightWhite.to_string().as_ref() + ); +} +``` + +Custom attributes are applied to a variant by adding `#[strum(parameter="value")]` to the variant. - `serialize="..."`: Changes the text that `FromStr()` looks for when parsing a string. This attribute can be applied multiple times to an element and the enum variant will be parsed if any of them match. diff --git a/strum/src/lib.rs b/strum/src/lib.rs index 6cdfcf7a..7a7b597b 100644 --- a/strum/src/lib.rs +++ b/strum/src/lib.rs @@ -14,8 +14,8 @@ //! //! ```toml //! [dependencies] -//! strum = "0.9.0" -//! strum_macros = "0.9.0" +//! strum = "0.11.0" +//! strum_macros = "0.11.0" //! ``` //! //! And add these lines to the root of your project, either lib.rs or main.rs. @@ -79,10 +79,10 @@ //! # fn main() {} //! ``` //! -//! Note that the implementation of `FromStr` only matches on the name of the variant. -//! Strum, where possible, avoids operations that have an unknown runtime cost, and parsing strings -//! is potentially an expensive operation. If you do need that behavior, consider the more powerful -//! Serde library for your serialization. +//! Note that the implementation of `FromStr` by default only matches on the name of the +//! variant. There is an option to match on different case conversions through the +//! `#[strum(serialize_all = "snake_case")]` type attribute. See the **Additional Attributes** +//! Section for more information on using this feature. //! //! 2. `Display`, `ToString`: both derives print out the given enum variant. This enables you to perform round trip //! style conversions from enum into string and back again for unit style variants. `ToString` and `Display` @@ -293,8 +293,43 @@ //! //! # Additional Attributes //! -//! Strum supports several custom attributes to modify the generated code. Custom attributes are -//! applied to a variant by adding #[strum(parameter="value")] to the variant. +//! Strum supports several custom attributes to modify the generated code. At the enum level, the +//! `#[strum(serialize_all = "snake_case")]` attribute can be used to change the case used when +//! serializing to and deserializing from strings: +//! +//! ```rust +//! extern crate strum; +//! #[macro_use] +//! extern crate strum_macros; +//! +//! #[derive(Debug, Eq, PartialEq, ToString)] +//! #[strum(serialize_all = "snake_case")] +//! enum Brightness { +//! DarkBlack, +//! Dim { +//! glow: usize, +//! }, +//! #[strum(serialize = "bright")] +//! BrightWhite, +//! } +//! +//! fn main() { +//! assert_eq!( +//! String::from("dark_black"), +//! Brightness::DarkBlack.to_string().as_ref() +//! ); +//! assert_eq!( +//! String::from("dim"), +//! Brightness::Dim { glow: 0 }.to_string().as_ref() +//! ); +//! assert_eq!( +//! String::from("bright"), +//! Brightness::BrightWhite.to_string().as_ref() +//! ); +//! } +//! ``` +//! +//! Custom attributes are applied to a variant by adding `#[strum(parameter="value")]` to the variant. //! //! - `serialize="..."`: Changes the text that `FromStr()` looks for when parsing a string. This attribute can //! be applied multiple times to an element and the enum variant will be parsed if any of them match.