smooth/lib.rs
1//! A utility library for human-readable presentation of numbers.
2//!
3//! Rationale
4//! =========
5//!
6//! Formatting numbers does not always yield human-readable results:
7//!
8//! ```rust
9//! assert_eq!(format!("{}", 1.0_f64 / 3.0), "0.3333333333333333");
10//! assert_eq!(format!("{}", 2.0_f64.sqrt()), "1.4142135623730951");
11//! ```
12//!
13//! When presenting numbers for humans to consume, especially lots of numbers,
14//! it may be beneficial to *reduce precision* to make what's shown
15//! *comprehensible*. This library is intended to be used in user interface
16//! (UI) code, inbetween the library, which produces these numbers, and the UI,
17//! which presents these numbers to the user, to **control the compromise
18//! between precision and readability**.
19//!
20//! Examples
21//! ========
22//!
23//! Single Number Smoothing
24//! -----------------------
25//!
26//! ```rust
27//! use smooth::Smooth;
28//!
29//! // numbers without a fraction are simply rounded
30//! assert_eq!(0.0.smooth_str(), "0");
31//! assert_eq!(42.0.smooth_str(), "42");
32//!
33//! // numbers with zero integer part are rounded to 2 decimals
34//! assert_eq!(0.1.smooth_str(), "0.1");
35//! assert_eq!(0.09.smooth_str(), "0.09");
36//! assert_eq!(0.009.smooth_str(), "0.01");
37//! assert_eq!(0.001.smooth_str(), "0");
38//!
39//! // comparatively large fractions are kept
40//! assert_eq!(1.1.smooth_str(), "1.1");
41//! assert_eq!(1.01.smooth_str(), "1.01");
42//! assert_eq!(10.9.smooth_str(), "10.9");
43//!
44//! // comparatively small fractions are smoothed away
45//! assert_eq!(1.001.smooth_str(), "1");
46//! assert_eq!(10.09.smooth_str(), "10.1");
47//! assert_eq!(1000.1.smooth_str(), "1000");
48//! ```
49//!
50//! Multiple Number Smoothing
51//! -------------------------
52//!
53//! ```rust
54//! use smooth::MultiSmooth;
55//!
56//! let numbers = [1.1111, 5.5555, 9.9999];
57//! assert_eq!(numbers.smooth_str(), ["1.1", "5.6", "10"]);
58//!
59//! let numbers = [1.1111, 5.5555, 1000.0];
60//! assert_eq!(numbers.smooth_str(), ["1", "6", "1000"]);
61//!
62//! let numbers = [0.009, 0.249, 0.999];
63//! assert_eq!(numbers.smooth_str(), ["0.01", "0.25", "1"]);
64//! ```
65//!
66//! Rounding
67//! --------
68//!
69//! In some use cases, rounding to a specific number of decimals might be a
70//! better compromise.
71//!
72//! ```rust
73//! use smooth::{MultiSmooth, Smooth};
74//!
75//! // round to a specific number of decimals
76//! assert_eq!(1.0.round_to_str(2), "1");
77//! assert_eq!(1.001.round_to_str(2), "1");
78//! assert_eq!(1.018.round_to_str(2), "1.02");
79//! assert_eq!(1.4242.round_to_str(2), "1.42");
80//!
81//! // consistently round multiple numbers
82//! let numbers = [1.1111, 2.2222, 5.5555];
83//! assert_eq!(numbers.round_to_str(2), ["1.11", "2.22", "5.56"]);
84//! ```
85
86#![forbid(unsafe_code)]
87#![deny(clippy::all, missing_docs)]
88#![warn(clippy::pedantic, clippy::nursery, clippy::cargo)]
89
90mod multi;
91mod single;
92
93pub use multi::MultiSmooth;
94pub use single::Smooth;