# num-format
[](https://travis-ci.org/bcmyers/num-format)
[](https://crates.io/crates/num-format)
[](https://docs.rs/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.
```rust
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.
```rust
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.
```rust
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.
```rust
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).
<i>Since this type requires several dependencies (especially on Windows), it is behind a feature
flag. To use it, include `num-format = { version = "0.4", features = ["with-system-locale"] }`
in your `Cargo.toml`. Additionally, on Windows (but **only** on Windows), using `SystemLocale`
requires Clang 3.9 or higher.</i>
```rust
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.
```rust
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.31 or greater
* If you're using the `with-system-locale` feature **and** you're on Windows, Clang 3.9 or higher
is also required. See [here](https://rust-lang.github.io/rust-bindgen/requirements.html) for
installation instructions.
## Extra features
| `no_std` | `num-format = { version = "0.4", default-features = false }` |
| `with-num-bigint` | `num-format = { version = "0.4", features = ["with-num-bigint"] }` |
| `with-serde` | `num-format = { version = "0.4", features = ["with-serde"] }` |
| `with-system-locale` | `num-format = { version = "0.4", features = ["with-system-locale"] }` |
## License
**num-format** is licensed under either of:
- [The Apache License, Version 2.0], or
- [The MIT license]
at your option.
[bindgen]: https://crates.io/crates/bindgen
[`Buffer`]: https://docs.rs/num-format/0.4.0/num_format/struct.Buffer.html
[Common Locale Data Repository]: https://en.wikipedia.org/wiki/Common_Locale_Data_Repository
[`CustomFormat`]: https://docs.rs/num-format/0.4.0/num_format/struct.CustomFormat.html
[`File`]: https://doc.rust-lang.org/std/fs/struct.File.html
[`fmt::Write`]: https://doc.rust-lang.org/std/fmt/fn.write.html
[`Format`]: https://docs.rs/num-format/0.4.0/num_format/trait.Format.html
[`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
[`Locale`]: https://docs.rs/num-format/0.4.0/num_format/enum.Locale.html
[`num_bigint::BigInt`]: https://docs.rs/num-bigint/0.2.2/num_bigint/struct.BigInt.html
[picking a format]: #picking-a-format
[`String`]: https://doc.rust-lang.org/std/string/struct.String.html
[The Apache License, Version 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[The MIT license]: http://opensource.org/licenses/MIT
[`ToFormattedString`]: https://docs.rs/num-format/0.4.0/num_format/trait.ToFormattedString.html
[`to_formatted_string`]: https://docs.rs/num-format/0.4.0/num_format/trait.ToFormattedString.html#method.to_formatted_string
[Unicode Consortium]: https://en.wikipedia.org/wiki/Unicode_Consortium
[`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
[`WriteFormatted`]: https://docs.rs/num-format/0.4.0/num_format/trait.WriteFormatted.html