thousands/lib.rs
1#![doc(html_root_url = "https://docs.rs/thousands/0.2.0")]
2//! Provides a trait, [`Separable`], for formatting numbers with
3//! separators between the digits. Typically this will be used to add
4//! commas or spaces every three digits from the right, but can be
5//! configured via a [`SeparatorPolicy`].
6//!
7//! # Examples
8//!
9//! The simplest way to use the library is with trait [`Separable`]’s method
10//! [`separate_with_commas`] method, which does what it sounds like:
11//!
12//! ```
13//! use thousands::Separable;
14//!
15//! assert_eq!( 12345 .separate_with_commas(), "12,345" );
16//! assert_eq!( (-12345) .separate_with_commas(), "-12,345" );
17//! assert_eq!( 9876.5.separate_with_commas(), "9,876.5" );
18//! ```
19//!
20//! There are also methods [`separate_with_spaces`], [`separate_with_dots`], and
21//! [`separate_with_underscores`], in case you, your culture, or your file
22//! format prefer those separators.
23//!
24//! However, it's also possible to pass a policy for different behavior:
25//!
26//! ```
27//! use thousands::{Separable, SeparatorPolicy, digits};
28//!
29//! let policy = SeparatorPolicy {
30//! separator: ",",
31//! groups: &[3, 2],
32//! digits: digits::ASCII_DECIMAL,
33//! };
34//!
35//! assert_eq!( 1234567890.separate_by_policy(policy), "1,23,45,67,890" );
36//! ```
37//!
38//! # Usage
39//!
40//! It’s [on crates.io](https://crates.io/crates/thousands), so you can add
41//!
42//! ```toml
43//! [dependencies]
44//! thousands = "0.2.0"
45//! ```
46//!
47//! to your `Cargo.toml`.
48//!
49//! This crate supports Rust version 1.22 and newer.
50//!
51//! [`Separable`]: trait.Separable.html
52//! [`SeparatorPolicy`]: struct.SeparatorPolicy.html
53//! [`separate_with_commas`]: trait.Separable.html#method.separate_with_commas
54//! [`separate_with_spaces`]: trait.Separable.html#method.separate_with_spaces
55//! [`separate_with_dots`]: trait.Separable.html#method.separate_with_dots
56//! [`separate_with_underscores`]: trait.Separable.html#method.separate_with_underscores
57
58/// Collections of digits.
59///
60/// These are used for constructing [SeparatorPolicy](struct.SeparatorPolicy.html)s.
61pub mod digits;
62
63/// Predefined policies.
64pub mod policies;
65pub use policies::SeparatorPolicy;
66
67mod traits;
68pub use traits::Separable;
69
70// Contains blanket impl<T: Display> Separable for T.
71mod display;
72
73mod helpers;