num-format

A Rust crate for producing string representations of numbers, formatted according to international standards, e.g.

• "1,000,000" for US English
• "10,00,000" for Indian English
• "1 000 000" for French French

Creating a string representation

num-format offers three principal APIs...

ToFormattedString

The [ToFormattedString] trait is the simplist of the three APIs. Just call [to_formatted_string] on a type that implements it (all the integer types in the standard library implement it) while providing a desired format (see picking a format below). That said, using [ToFormattedString] will always heap allocate; so it is the slowest of the three APIs and cannot be used in a no_std environment.

use num_format::{Locale, ToFormattedString};

fn main() {
    let s = 1000000.to_formatted_string(&Locale::en);
    assert_eq!(&s, "1,000,000");
}

Buffer

Using the [Buffer] type is the fastest API, as it does not heap allocate. Instead, the formatted representation is written into a stack-allocated buffer. As such, you can use it in a no_std environment.

Although this API is available for all the integer types in the standard library, it is not available for types like [num_bigint::BigInt] whose maximum size cannot be known in advance.

use num_format::{Buffer, Locale};

fn main() {
    // Create a stack-allocated buffer...
    let mut buf = Buffer::default();

    // Write "1,000,000" into the buffer...
    buf.write_formatted(&1000000, &Locale::en);

    // Get a view into the buffer as a &str...
    let s = buf.as_str();

    // Do what you want with the &str...
    assert_eq!("1,000,000", s);
}

WriteFormatted

The [WriteFormatted] trait is in between the other two APIs. You can write a formatted representation into any type that implements [WriteFormatted] (all the types in the standard library that implement [io::Write] or [fmt::Write] implement [WriteFormatted], such as [Vec], [String], [File], etc.).

If you're writing a number type that can use the [Buffer] API, there is no heap allocation. That said, the [io::Write] and [fmt::Write] machinery adds a bit of overhead; so it's faster to use the [Buffer] type directly. This trait is not available in a no_std environment.

use num_format::{Locale, WriteFormatted};

fn main() {
    // Create a writer...
    let mut writer = String::new(); // Could also be Vec::new(), File::open(...), ...

    // Write "1,000,000" into the writer...
    writer.write_formatted(&1000000, &Locale::en);

    assert_eq!(&writer, "1,000,000");
}

Picking a format

Formatting options (e.g. which thousands separator to use, what the minus sign looks like, etc.) are represented by the [Format] trait. This crate offers three concrete implementations of the [Format] trait...

Locale

The [Locale] type is a programatically generated enum representing formatting standards from the Common Locale Data Repository, which is maintained by the Unicode Consortium and used by Apple in macOS and iOS, by LibreOffice, by IBM in AIX, among others.

use num_format::{Grouping, Locale};

fn main() {
    let locale = Locale::en;
    assert_eq!(locale.grouping(), Grouping::Standard);
    assert_eq!(locale.minus_sign(), "-");
    assert_eq!(locale.name(), "en");
    assert_eq!(locale.separator(), ",");

    let locale2 = Locale::from_name("en").unwrap();
    assert_eq!(locale, locale2);

    let available = Locale::available_names();
    println!("All of the locale names available in the Unicode database are...");
    println!("{:#?}", available);
}

SystemLocale (available behind feature flag with-system-locale)

The SystemLocale type is another type that implements [Format]. It allows you to access your OS's locale information. It has a very similar API to [Locale] and should work on all major operating systems (i.e. macOS, linux, the BSDs, and Windows).

Since this type requires several dependencies (especially on Windows), it is behind a feature flag. To use it, include num-format = { version = "0.4.3", features = ["with-system-locale"] } in your Cargo.toml. Additionally, on Windows (but only on Windows), using SystemLocale requires Clang 3.9 or higher.

use num_format::SystemLocale;

fn main() {
    let locale = SystemLocale::default().unwrap();
    println!("My system's default locale is...");
    println!("{:#?}", &locale);

    let available = SystemLocale::available_names().unwrap();
    println!("My available locale names are...");
    println!("{:#?}", available);

    match SystemLocale::from_name("en_US") {
        Ok(_) => println!("My system has the 'en_US' locale."),
        Err(_) => println!("The 'en_US' locale is not included with my system."),
    }
}

CustomFormat

[CustomFormat] is the third and final type that implements [Format]. You can use it to build your own custom formats.

use num_format::{Buffer, Error, CustomFormat, Grouping};

fn main() -> Result<(), Error> {
    let format = CustomFormat::builder()
        .grouping(Grouping::Indian)
        .minus_sign("🙌")
        .separator("😀")
        .build()?;

    let mut buf = Buffer::new();
    buf.write_formatted(&(-1000000), &format);
    assert_eq!("🙌10😀00😀000", buf.as_str());

    Ok(())
}

Requirements

• Rust 1.56.0 or greater if compiled with --no-default-features
• Rust 1.58.0 or greater if compiled with default features
• If you're using the with-system-locale feature and you're on Windows, Clang 3.9 or higher is also required. See here for installation instructions.

Extra features

License

num-format is licensed under either of:

• The Apache License, Version 2.0, or
• The MIT license

at your option.