Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename create_format to make_format in docs #33

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 31 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
[Documentation](https://docs.rs/humansize/latest/humansize/)

## Features

Humansize is a humanization library for information size that is:

- Simple & convenient to use
- Customizable
- Supports byte or bit sizes
Expand All @@ -14,6 +16,7 @@ Humansize is a humanization library for information size that is:
## How to use it...

Add humansize as a dependency to your project's `cargo.toml`:

```toml
[dependencies]
...
Expand All @@ -23,9 +26,9 @@ humansize = "2.1.3"
### ... to easily format a size:

1. Import the `format_size` function as well as your preferred set of defaults:
- `DECIMAL` (SI)
- `BINARY` (IEC)
- `WINDOWS` (IEC values but SI units)
- `DECIMAL` (SI)
- `BINARY` (IEC)
- `WINDOWS` (IEC values but SI units)
2. Call `format_size` with an unsigned integer

```rust
Expand All @@ -39,7 +42,8 @@ assert_eq!(&res, "1 MB");
```

### ... to format many sizes:
To 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:

To improve reusability, you can use `make_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:

```rust
use humansize::{make_format, DECIMAL};
Expand All @@ -53,20 +57,26 @@ assert_eq!(formatter(1_000_000_000u64), "1 GB");
```

### ... to avoid allocation:

Specify the `no_alloc` feature flag in your project's `cargo.toml`:

```toml
[dependencies]
...
humansize = { version = "2.0.0", features = ["no_alloc"] }
```

This 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:

```rust
use humansize::{SizeFormatter, DECIMAL};

let formatter = SizeFormatter::new(1_000_000usize, DECIMAL);
assert_eq!(format!("{}", formatter), "1 MB");
```

### ... with the `impl` style API:

For stylistic reasons, you may prefer to use the impl-style API of earlier versions of the crate.
To do so, specify the `impl-style` feature flag in your project's `cargo.toml`:

Expand All @@ -75,32 +85,40 @@ To do so, specify the `impl-style` feature flag in your project's `cargo.toml`:
...
humansize = { version = "2.0.0", features = ["impl_style"] }
```

Enabling this feature makes two methods available:

- `format_size` on unsigned integers types
- `format_size_i` on signed integer types.

To use it, bring the FormatSize trait into scope and call its method on an integer type:

```ignore
use humansize::{FormatSize, FormatSizeI DECIMAL};

assert_eq!(1_000_000u64.format_size(DECIMAL), "1 MB");
assert_eq!((-1_000_000).format_size_i(DECIMAL), "-1 MB");
```

### ... to further customize the output:

Humansize exports three default option sets:
* `Decimal`: kilo = 1000, unit format is `XB`.
* `Binary`: kilo = 1024, unit format is `XiB`.
* `WINDOWS` (Windows): kilo = 1024, unit format is `XB`.

- `Decimal`: kilo = 1000, unit format is `XB`.
- `Binary`: kilo = 1024, unit format is `XiB`.
- `WINDOWS` (Windows): kilo = 1024, unit format is `XB`.

The 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.

### ... to accept negative values:

The 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:

- `format_size` : `format_size_i`
- `create_format` : `create_format_i`
- `make_format` : `make_format_i`
- `FormatSize` trait : `FormatSizeI` trait
- `SizeFormatter` : `ISizeFormatter`

```rust
use humansize::{format_size_i, make_format_i, ISizeFormatter, DECIMAL};

Expand All @@ -122,14 +140,13 @@ assert_eq!(format!("{}", signed_size_formatter), "-1 MB");

This project is licensed under either of

* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
http://opensource.org/licenses/MIT)

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or
http://opensource.org/licenses/MIT)

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in humansize by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
dual licensed as above, without any additional terms or conditions.
4 changes: 2 additions & 2 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ assert_eq!(&res, "1 MB");
```

### ... to format many sizes:
To 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:
To improve reusability, you can use `make_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:

```rust
use humansize::{make_format, DECIMAL};
Expand Down Expand Up @@ -98,7 +98,7 @@ The formatting can be further customized by providing providing your own option
The 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:

- `format_size` : `format_size_i`
- `create_format` : `create_format_i`
- `make_format` : `make_format_i`
- `FormatSize` trait : `FormatSizeI` trait
- `SizeFormatter` : `ISizeFormatter`
```rust
Expand Down