1#![no_std]
2/*!
3# **Humansize**
4
5## Features
6Humansize is a humanization library for information size that is:
7- Simple & convenient to use
8- Customizable
9- Supports byte or bit sizes
10- `no-std`
11- Optionally non-allocating
12- Optionally accepts signed values
13
14## How to use it...
15
16Add humansize as a dependency to your project's `cargo.toml`:
17```toml
18[dependencies]
19...
20humansize = "2.0.0"
21```
22
23### ... to easily format a size:
24
251. Import the `format_size` function as well as your preferred set of defaults:
26 - `DECIMAL` (SI)
27 - `BINARY` (IEC)
28 - `WINDOWS` (IEC values but SI units)
292. Call `format_size` with an unsigned integer
30
31```rust
32use humansize::{format_size, DECIMAL};
33
34let size = 1_000_000u64;
35let res: String = format_size(size, DECIMAL);
36
37assert_eq!(&res, "1 MB");
38
39```
40
41### ... to format many sizes:
42To improve reusability, you can use `create_format`, which returns a formatter function akin to `format_size` but with the options argument curried so it doesn't need to be specified again:
43
44```rust
45use humansize::{make_format, DECIMAL};
46
47let formatter = make_format(DECIMAL);
48
49assert_eq!(formatter(1_000_000u64), "1 MB");
50assert_eq!(formatter(1_000_000_000u64), "1 GB");
51//...
52
53```
54
55### ... to avoid allocation:
56Specify the `no_alloc` feature flag in your project's `cargo.toml`:
57```toml
58[dependencies]
59...
60humansize = { version = "2.0.0", features = ["no_alloc"] }
61```
62This excludes all allocating code from compilation. You may now use the library's internal `SizeFormatter` struct, which implements `core::fmt::display` so that you can `write!` it to a custom buffer of your choice:
63```rust
64use humansize::{SizeFormatter, DECIMAL};
65
66let formatter = SizeFormatter::new(1_000_000usize, DECIMAL);
67assert_eq!(format!("{}", formatter), "1 MB");
68```
69### ... with the `impl` style API:
70For stylistic reasons, you may prefer to use the impl-style API of earlier versions of the crate.
71To do so, specify the `impl-style` feature flag in your project's `cargo.toml`:
72
73```toml
74[dependencies]
75...
76humansize = { version = "2.0.0", features = ["impl_style"] }
77```
78Enabling this feature makes two methods available:
79- `format_size` on unsigned integers types
80- `format_size_i` on signed integer types.
81
82To use it, bring the FormatSize trait into scope and call its method on an integer type:
83```ignore
84use humansize::{FormatSize, FormatSizeI DECIMAL};
85
86assert_eq!(1_000_000u64.format_size(DECIMAL), "1 MB");
87assert_eq!((-1_000_000).format_size_i(DECIMAL), "-1 MB");
88```
89### ... to further customize the output:
90Humansize exports three default option sets:
91* `Decimal`: kilo = 1000, unit format is `XB`.
92* `Binary`: kilo = 1024, unit format is `XiB`.
93* `WINDOWS` (Windows): kilo = 1024, unit format is `XB`.
94
95The formatting can be further customized by providing providing your own option set. See the documentation of the `FormatSizeOptions` struct to see all the addressable parameters, and [this example](examples/custom_options.rs) for its usage.
96
97### ... to accept negative values:
98The solutions presented above only accept unsigned integer types as input (`usize`, `8`, `u16`, `u32` and `u64`). If however accepting negative values is correct for your application, a signed alternative exists for each of them that will accept signed integer types, and format them accordingly if negative:
99
100- `format_size` : `format_size_i`
101- `create_format` : `create_format_i`
102- `FormatSize` trait : `FormatSizeI` trait
103- `SizeFormatter` : `ISizeFormatter`
104```rust
105use humansize::{format_size_i, make_format_i, ISizeFormatter, DECIMAL};
106
107assert_eq!(&format_size_i(-1_000_000, DECIMAL), "-1 MB");
108
109let signed_formatter = make_format_i(DECIMAL);
110assert_eq!(&signed_formatter(-1_000_000), "-1 MB");
111
112// With the `impl-style` feature enabled:
113// use humansize::FormatSizeI;
114// assert_eq(-1_000_000.format_size(DECIMAL), "-1 MB");
115
116let signed_size_formatter = ISizeFormatter::new(-1_000_000, DECIMAL);
117assert_eq!(format!("{}", signed_size_formatter), "-1 MB");
118
119```
120*/
121
122#[macro_use]
123#[cfg(not(feature = "no_alloc"))]
124extern crate alloc;
125extern crate libm;
126
127mod options;
128pub use options::{BaseUnit, FixedAt, FormatSizeOptions, Kilo, BINARY, DECIMAL, WINDOWS};
129
130mod numeric_traits;
131pub use numeric_traits::{Signed, ToF64, Unsigned};
132
133mod scales;
134mod utils;
135
136#[cfg(not(feature = "no_alloc"))]
137mod allocating;
138#[cfg(not(feature = "no_alloc"))]
139pub use allocating::*;
140
141#[cfg(feature = "impl_style")]
142mod impl_style;
143#[cfg(feature = "impl_style")]
144pub use impl_style::{FormatSize, FormatSizeI};
145
146mod formatters;
147pub use formatters::{SizeFormatter, ISizeFormatter};
148