README.md
1# `f16` and `bf16` floating point types for Rust
2[](https://crates.io/crates/half/) [](https://docs.rs/half/) [](https://travis-ci.org/starkat99/half-rs) [](https://ci.appveyor.com/project/starkat99/half-rs)
3
4This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE 754-2008 standard
5[`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) a.k.a `half` format,
6as well as a `bf16` type implementing the [`bfloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) format.
7
8## Usage
9
10The `f16` and `bf16` types provides conversion operations as a normal Rust floating point type, but since they are primarily leveraged for
11minimal floating point storage and most major hardware does not implement them, all math operations should be done as an `f32` type.
12
13This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support by default so can easily be used in embedded
14code where a smaller float format is most useful.
15
16*Requires Rust 1.32 or greater.* If you need support for older versions of Rust, use versions 1.3 and earlier of this crate.
17
18See the [crate documentation](https://docs.rs/half/) for more details.
19
20### Optional Features
21
22- **`serde`** - Implement `Serialize` and `Deserialize` traits for `f16` and `bf16`. This adds a dependency on the
23[`serde`](https://crates.io/crates/serde) crate.
24
25- **`use-intrinsics`** - Use hardware intrinsics for `f16` and `bf16` conversions if available on the compiler host target. By
26default, without this feature, conversions are done only in software, which will be the fallback if the host target does
27not have hardware support. **Available only on Rust nightly channel.**
28
29- **`alloc`** - Enable use of the [`alloc`](https://doc.rust-lang.org/alloc/) crate when not using the `std` library.
30
31 This enables the `vec` module, which contains zero-copy conversions for the `Vec` type. This allows fast conversion between
32 raw `Vec<u16>` bits and `Vec<f16>` or `Vec<bf16>` arrays, and vice versa. *Requires Rust 1.36 or greater.*
33
34- **`std`** - Enable features that depend on the Rust `std` library, including everything in the `alloc` feature.
35
36 Enabling the `std` feature enables runtime CPU feature detection when the `use-intrsincis` feature is also enabled.
37 Without this feature detection, intrinsics are only used when compiler host target supports them.
38
39- **`num-traits`** - Enable `ToPrimitive` and `FromPrimitive` trait implementations from the
40 `num-traits` crate.
41
42- **`bytemuck`** - Enable `Zeroable` and `Pod` trait implementations from the `bytemuck` crate.
43
44### More Documentation
45
46- [Crate API Reference](https://docs.rs/half/)
47- [Latest Changes](CHANGELOG.md)
48
49## License
50
51This library is distributed under the terms of either of:
52
53* MIT license ([LICENSE-MIT](LICENSE-MIT) or
54[http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
55* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
56[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
57
58at your option.
59
60### Contributing
61
62Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
63work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
64additional terms or conditions.
65
){kind=link}
){kind=link}
){kind=link}