Crate convert_case

source ·
Expand description

Converts to and from various cases.

Command Line Utility ccase

Since version “0.3.0” this crate is just a case conversion library. The command line utility that uses the tools in this library has been moved to the ccase crate. You can read about it at the github repository.

Rust Library

Provides a Case enum which defines a variety of cases to convert into. A Case can be used with an item that implements the Casing trait, which allows the item to be converted to a given case.

You can convert a string or string slice into a case using the to_case method.

use convert_case::{Case, Casing};

assert_eq!("Ronnie James Dio", "ronnie james dio".to_case(Case::Title));
assert_eq!("ronnieJamesDio", "Ronnie_James_dio".to_case(Case::Camel));
assert_eq!("Ronnie-James-Dio", "RONNIE_JAMES_DIO".to_case(Case::Train));

By default, to_case will split along all word boundaries, that is

  • space characters ,
  • underscores _,
  • hyphens -,
  • and changes in capitalization aA.

For more accuracy, the from_case method splits based on the word boundaries of a particular case. For example, splitting from snake case will only treat underscores as word boundaries.

use convert_case::{Case, Casing};

assert_eq!(
    "2020 04 16 My Cat Cali",
    "2020-04-16_my_cat_cali".to_case(Case::Title)
);
assert_eq!(
    "2020-04-16 My Cat Cali",
    "2020-04-16_my_cat_cali".from_case(Case::Snake).to_case(Case::Title)
);

By default (and when converting from camel case or similar cases) convert_case will detect acronyms. It also ignores any leading, trailing, or deplicate delimeters.

use convert_case::{Case, Casing};

assert_eq!("io_stream", "IOStream".to_case(Case::Snake));
assert_eq!("my_json_parser", "myJSONParser".to_case(Case::Snake));

assert_eq!("weird_var_name", "__weird--var _name-".to_case(Case::Snake));

It also works non-ascii characters. However, no inferences on the language itself is made. For instance, the diagraph ij in dutch will not be capitalized, because it is represented as two distinct unicode characters. However, æ would be capitalized.

use convert_case::{Case, Casing};

assert_eq!("granat-äpfel", "GranatÄpfel".to_case(Case::Kebab));

// The example from str::to_lowercase documentation
let odysseus = "ὈΔΥΣΣΕΎΣ";
assert_eq!("ὀδυσσεύς", odysseus.to_case(Case::Lower));

For the purposes of case conversion, characters followed by numerics and vice-versa are considered word boundaries. In addition, any special ascii characters (besides _ and -) are ignored.

use convert_case::{Case, Casing};
 
assert_eq!("e_5150", "E5150".to_case(Case::Snake));
assert_eq!("10,000_days", "10,000Days".to_case(Case::Snake));
assert_eq!("HELLO, WORLD!", "Hello, world!".to_case(Case::Upper));
assert_eq!("One\ntwo\nthree", "ONE\nTWO\nTHREE".to_case(Case::Title));

Note on Accuracy

The Casing methods from_case and to_case do not fail. Conversion to a case will always succeed. However, the results can still be unexpected. Failure to detect any word boundaries for a particular case means the entire string will be considered a single word.

use convert_case::{Case, Casing};

// Mistakenly parsing using Case::Snake
assert_eq!("My-kebab-var", "my-kebab-var".from_case(Case::Snake).to_case(Case::Title));

// Converts using an unexpected method
assert_eq!("my_kebab_like_variable", "myKebab-like-variable".to_case(Case::Snake));

Random Feature

To ensure this library had zero dependencies, randomness was moved to the random feature, which requires the rand crate. You can enable this feature by including the following in your Cargo.toml.

[dependencies]
convert_case = { version = "^0.3, features = ["random"] }

This will add two additional cases: Random and PseudoRandom. You can read about their construction in the Case enum.

Structs

  • FromCasing
    Holds information about parsing before converting into a case.

Enums

  • Case
    Defines the type of casing a string can be.

Traits

  • Casing
    Describes items that can be converted into a case.