heckCrate

Overview

Turning XMLHttpRequest into xml_http_request looks like a two-line problem until you write it. Where does a word start? What happens to a run of capitals, to digits, to an underscore that is already there? Get any of those wrong and a derive macro generates a field name nobody expects.

heck is that problem solved once. It defines a single rule for word boundaries and applies it to every conversion:

use heck::{ToSnakeCase, ToUpperCamelCase, ToKebabCase};

// Runs of capitals are handled: XML|Http|Request, not X|M|L|Http|Request.
assert_eq!("XMLHttpRequest".to_snake_case(), "xml_http_request");

// The input's own separators don't matter — only the words it contains.
assert_eq!("hello__world".to_snake_case(), "hello_world");
assert_eq!("user name".to_upper_camel_case(), "UserName");
assert_eq!("HTTPResponse".to_kebab_case(), "http-response");

The rule is worth reading once, because everything else follows from it. A word boundary sits at any non-alphanumeric character, and also inside a run of letters: before an uppercase character followed by lowercase, and between the last uppercase of a run and the lowercase that follows. So HelloWorld splits Hello|World while XMLHttpRequest splits XML|Http|Request. Separators in the input are discarded rather than preserved — adjacent ones fold into one, and leading or trailing ones are dropped.

This is why it shows up as a build dependency almost everywhere: serde's rename_all, clap's derive, and most code generators need exactly this, and they need every crate to agree on the answer. Its download rank is that, not direct use.

It converts identifiers, not prose. Unicode is handled, but the rule is about programming casing rather than natural language — to_title_case will capitalise every word rather than following an English style guide's rules about short prepositions.

Each conversion comes in two forms: a To* trait method returning a String, and an As* wrapper that implements Display and allocates nothing.

The crate is tiny — no dependencies, #![no_std] with alloc, MSRV 1.56 — and stable rather than actively developed: the last release was 0.5.0 in March 2024, because a solved problem needs no releases. The repository is not archived and still receives commits. convert_case is the alternative worth knowing, offering configurable boundary rules and more cases at the cost of a larger API.

When to use it

use heck::{ToSnakeCase, ToUpperCamelCase};

/// Given a struct name, name its generated builder and the module holding it.
fn generated_names(type_name: &str) -> (String, String) {
    (
        format!("{}Builder", type_name.to_upper_camel_case()),
        type_name.to_snake_case(),
    )
}

assert_eq!(
    generated_names("HTTPClient"),
    ("HttpClientBuilder".to_string(), "http_client".to_string()),
);
assert_eq!(
    generated_names("user_account"),
    ("UserAccountBuilder".to_string(), "user_account".to_string()),
);

use heck::{ToKebabCase, ToLowerCamelCase, ToShoutySnakeCase};

let field = "max_retry_count";

assert_eq!(field.to_lower_camel_case(), "maxRetryCount"); // JSON body
assert_eq!(field.to_kebab_case(), "max-retry-count");     // --max-retry-count
assert_eq!(field.to_shouty_snake_case(), "MAX_RETRY_COUNT"); // env var

use heck::AsSnakeCase;
use std::fmt::Write;

let fields = ["firstName", "lastName", "emailAddress"];

let mut sql = String::from("SELECT ");
for (i, field) in fields.iter().enumerate() {
    if i > 0 {
        sql.push_str(", ");
    }
    // No intermediate String per field.
    write!(sql, "{}", AsSnakeCase(field)).unwrap();
}

assert_eq!(sql, "SELECT first_name, last_name, email_address");

API map

Every case comes as a pair: a To* trait whose method returns a String, and an As* tuple struct implementing Display. The traits are implemented for str, so use heck::ToSnakeCase; puts .to_snake_case() on every string.

use heck::ToSnakeCase;

assert_eq!("HelloWorld".to_snake_case(), "hello_world");
assert_eq!("XMLHttpRequest".to_snake_case(), "xml_http_request");
assert_eq!("hello-world".to_snake_case(), "hello_world");
assert_eq!("HELLO".to_snake_case(), "hello");

use heck::ToKebabCase;

assert_eq!("MaxRetryCount".to_kebab_case(), "max-retry-count");
assert_eq!("max_retry_count".to_kebab_case(), "max-retry-count");

use heck::ToShoutySnakeCase;

assert_eq!("databaseUrl".to_shouty_snake_case(), "DATABASE_URL");
assert_eq!("HttpTimeout".to_shouty_snake_case(), "HTTP_TIMEOUT");

use heck::ToShoutyKebabCase;

assert_eq!("contentType".to_shouty_kebab_case(), "CONTENT-TYPE");

use heck::ToUpperCamelCase;

assert_eq!("user_account".to_upper_camel_case(), "UserAccount");
assert_eq!("http-client".to_upper_camel_case(), "HttpClient");
assert_eq!("XMLHttpRequest".to_upper_camel_case(), "XmlHttpRequest");

use heck::ToLowerCamelCase;

assert_eq!("first_name".to_lower_camel_case(), "firstName");
assert_eq!("HTTP_TIMEOUT".to_lower_camel_case(), "httpTimeout");

use heck::ToTitleCase;

assert_eq!("user_account".to_title_case(), "User Account");
assert_eq!("XMLHttpRequest".to_title_case(), "Xml Http Request");

use heck::ToTrainCase;

assert_eq!("content_type".to_train_case(), "Content-Type");
assert_eq!("xForwardedFor".to_train_case(), "X-Forwarded-For");

use heck::{AsKebabCase, AsShoutySnakeCase, AsUpperCamelCase};

// Interpolated directly, with no String in between.
assert_eq!(format!("--{}", AsKebabCase("maxRetries")), "--max-retries");
assert_eq!(format!("{}", AsUpperCamelCase("user_id")), "UserId");
assert_eq!(format!("{}=1", AsShoutySnakeCase("logLevel")), "LOG_LEVEL=1");