1# `f16` and `bf16` floating point types for Rust 2[](https://crates.io/crates/half/) [](https://docs.rs/half/)  [](https://github.com/starkat99/half-rs/actions/workflows/rust.yml) 3 4This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE 5754-2008 standard [`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) 6a.k.a `half` format, as well as a `bf16` type implementing the 7[`bfloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) format. 8 9## Usage 10 11The `f16` and `bf16` types provides conversion operations as a normal Rust floating point type, but 12since they are primarily leveraged for minimal floating point storage and most major hardware does 13not implement them, all math operations are done as an `f32` type under the hood. Complex arithmetic 14should manually convert to and from `f32` for better performance. 15 16This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support by 17default so can easily be used in embedded code where a smaller float format is most useful. 18 19*Requires Rust 1.58 or greater.* If you need support for older versions of Rust, use 1.x versions of 20this crate. 21 22See the [crate documentation](https://docs.rs/half/) for more details. 23 24### Optional Features 25 26- **`serde`** - Implement `Serialize` and `Deserialize` traits for `f16` and `bf16`. This adds a 27 dependency on the [`serde`](https://crates.io/crates/serde) crate. 28 29- **`use-intrinsics`** - Use hardware intrinsics for `f16` and `bf16` conversions if available on 30 the compiler host target. By default, without this feature, conversions are done only in software, 31 which will be the fallback if the host target does not have hardware support. **Available only on 32 Rust nightly channel.** 33 34- **`alloc`** - Enable use of the [`alloc`](https://doc.rust-lang.org/alloc/) crate when not using 35 the `std` library. 36 37 This enables the `vec` module, which contains zero-copy conversions for the `Vec` type. This 38 allows fast conversion between raw `Vec<u16>` bits and `Vec<f16>` or `Vec<bf16>` arrays, and vice 39 versa. 40 41- **`std`** - Enable features that depend on the Rust `std` library, including everything in the 42 `alloc` feature. 43 44 Enabling the `std` feature enables runtime CPU feature detection when the `use-intrsincis` feature 45 is also enabled. 46 Without this feature detection, intrinsics are only used when compiler host target supports them. 47 48- **`num-traits`** - Enable `ToPrimitive`, `FromPrimitive`, `Num`, `Float`, `FloatCore` and 49 `Bounded` trait implementations from the [`num-traits`](https://crates.io/crates/num-traits) crate. 50 51- **`bytemuck`** - Enable `Zeroable` and `Pod` trait implementations from the 52 [`bytemuck`](https://crates.io/crates/bytemuck) crate. 53 54- **`zerocopy`** - Enable `AsBytes` and `FromBytes` trait implementations from the 55 [`zerocopy`](https://crates.io/crates/zerocopy) crate. 56 57### More Documentation 58 59- [Crate API Reference](https://docs.rs/half/) 60- [Latest Changes](CHANGELOG.md) 61 62## License 63 64This library is distributed under the terms of either of: 65 66* [MIT License](LICENSES/MIT.txt) 67 ([http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) 68* [Apache License, Version 2.0](LICENSES/Apache-2.0.txt) 69 ([http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)) 70 71at your option. 72 73This project is [REUSE-compliant](https://reuse.software/spec/). Copyrights are retained by their 74contributors. Some files may include explicit copyright notices and/or license 75[SPDX identifiers](https://spdx.dev/ids/). For full authorship information, see the version control 76history. 77 78### Contributing 79 80Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the 81work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any 82additional terms or conditions. 83
){kind=link}
){kind=link}
){kind=link}