third_party/rust/half/README.md

   1 # `f16` and `bf16` floating point types for Rust
   2 [![Crates.io](https://img.shields.io/crates/v/half.svg)](https://crates.io/crates/half/) [![Documentation](https://docs.rs/half/badge.svg)](https://docs.rs/half/) ![Crates.io](https://img.shields.io/crates/l/half) [![Build status](https://github.com/starkat99/half-rs/actions/workflows/rust.yml/badge.svg?branch=master)](https://github.com/starkat99/half-rs/actions/workflows/rust.yml)
   3
   4 This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE
   5 754-2008 standard [`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format)
   6 a.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
  11 The `f16` and `bf16` types provides conversion operations as a normal Rust floating point type, but
  12 since they are primarily leveraged for minimal floating point storage and most major hardware does
  13 not implement them, all math operations are done as an `f32` type under the hood. Complex arithmetic
  14 should manually convert to and from `f32` for better performance.
  15
  16 This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support by
  17 default so can easily be used in embedded code where a smaller float format is most useful.
  18
  19 *Requires Rust 1.51 or greater.* If you need support for older versions of Rust, use versions 1.7.1
  20 and earlier of this crate.
  21
  22 See 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
  64 This 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
  71 at your option.
  72
  73 This project is [REUSE-compliant](https://reuse.software/spec/). Copyrights are retained by their
  74 contributors. 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
  76 history.
  77
  78 ### Contributing
  79
  80 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
  81 work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
  82 additional terms or conditions.