readable 0.11.0

Human readable strings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# Readable
[![CI](https://github.com/hinto-janai/readable/actions/workflows/ci.yml/badge.svg)](https://github.com/hinto-janai/readable/actions/workflows/ci.yml) [![crates.io](https://img.shields.io/crates/v/readable.svg)](https://crates.io/crates/readable) [![docs.rs](https://docs.rs/readable/badge.svg)](https://docs.rs/readable)

![readable](https://github.com/hinto-janai/readable/assets/101352116/2b4c0c1b-c80e-4b7a-a8b9-b86375382db9)

Human **readable** strings.

This library:
- Transforms various data types into human-readable strings
- Parses raw string data into human-readable versions
- Provides various string types and utilities

Most of the strings are implemented as fixed sized stack allocated arrays that are [`Copy`](https://doc.rust-lang.org/stable/std/marker/trait..html)-able.

In general, `readable` types are often used where you need to quickly format some data into a more human-friendly string, display it, then throw it away (although most `readable` types are perfectly fine to permanently store).

Creation of `readable` types is relatively performant.

## Examples
#### Unsigned
```rust
use readable::*;
assert_eq!(Unsigned::from(1000_u64), "1,000");
```
#### Int
```rust
use readable::*;
assert_eq!(Int::from(-1000), "-1,000");
```
#### Float
```rust
use readable::*;
assert_eq!(Float::from(1000.123), "1,000.123");
```
#### Percent
```rust
use readable::*;
assert_eq!(Percent::from(1000.123), "1,000.12%");
```
#### Runtime
```rust
use readable::*;
assert_eq!(Runtime::from(311.123),      "5:11");
assert_eq!(RuntimePad::from(311.123),   "00:05:11");
assert_eq!(RuntimeMilli::from(311.123), "00:05:11.123");
```
#### Time
```rust
use readable::*;
assert_eq!(Time::from(86399_u32), "23h, 59m, 59s");
assert_eq!(TimeFull::from(86399_u32), "23 hours, 59 minutes, 59 seconds");
```
#### Date
```rust
use readable::*;
assert_eq!(Date::from_ymd(2014, 12, 31).unwrap(), "2014-12-31");
```
#### Byte
```rust
use readable::*;
assert_eq!(Byte::from(1234), "1.234 KB");
```

## Comparison
All number types implement `PartialEq` against `str` and their internal numbers.

This is comparing `b`'s inner `String`:
```rust
use readable::*;
let a = std::time::Duration::from_secs(86399);
let b = TimeFull::from(a);
assert_eq!(b, "23 hours, 59 minutes, 59 seconds");
```
This is comparing `a`'s inner `i64`:
```rust
use readable::*;
let a = Int::from(-1000);
assert_eq!(a, -1000);
```
This compares both the `u64` AND `String` inside `a` and `b`:
```rust
use readable::*;
let a = Unsigned::from(1000_u64);
let b = Unsigned::from(1000_u64);
assert_eq!(a, b);
```

## Arithmetic
All number types implement the common arithmetic operators `+`, `-`, `/`, `*`, `%`, outputting a new `Self`.
#### `+` Addition
```rust
use readable::*;
let f1 = Float::from(1.0);
let f2 = Float::from(2.0);
assert_eq!(f1 + f2, 3.0);
```
#### `-` Subtraction
```rust
use readable::*;
let p50 = Percent::from(50.0);
let p25 = Percent::from(25.0);
assert_eq!(p50 - p25, "25.00%");
```
#### `/` Division
```rust
use readable::*;
let u100 = Unsigned::from(100_u64);
let u10  = Unsigned::from(10_u64);
assert_eq!(u100 / u10, 10);
```
#### `*` Muliplication
```rust
use readable::*;
let u10 = Unsigned::from(10_u64);
assert_eq!(u10 * u10, Unsigned::from(100_u64));
```
#### `%` Modulo
```rust
use readable::*;
let u10 = Unsigned::from(10_u64);
assert_eq!(u10 % u10, 0);
```

## Feature Flags
| Flag             | Purpose |
|------------------|---------|
| `serde`          | Enables [`serde`](https://docs.rs/serde) on most types
| `bincode`        | Enables [`bincode 2.0.0-rc.3`](https://docs.rs/bincode/2.0.0-rc.3/bincode/index.html)'s `Encode/Decode` on most types
| `byte`           | Enables the `byte` module
| `date`           | Enables the `date` module
| `num`            | Enables the `num` module
| `run`            | Enables the `run` module
| `str`            | Enables the `str` module
| `time`           | Enables the `time` module
| `toa`            | Enables the `toa` module
| `full`           | Enables everything above. This is on by default.

## Re-Exports
Types are separated per module depending on what type of data they take as input, and what type of data they output.
```rust
use readable::num::{ // Number formatting
	Unsigned, // Formats u8, u16, u32, etc...
	Int,      // Formats i8, i16, i32, etc...
};
```

All major types are exported to the root, so they can be imported without specifying the full path:
```rust,ignore
use readable::HeadTail; // shorter, preferred.

use readable::str::HeadTail; // longer
```