| 1 |
//! A crate that provides support for half-precision 16-bit floating point types. |
| 2 |
//! |
| 3 |
//! This crate provides the [`f16`] type, which is an implementation of the IEEE 754-2008 standard |
| 4 |
//! [`binary16`] a.k.a "half" floating point type. This 16-bit floating point type is intended for |
| 5 |
//! efficient storage where the full range and precision of a larger floating point value is not |
| 6 |
//! required. This is especially useful for image storage formats. |
| 7 |
//! |
| 8 |
//! This crate also provides a [`bf16`] type, an alternative 16-bit floating point format. The |
| 9 |
//! [`bfloat16`] format is a truncated IEEE 754 standard `binary32` float that preserves the |
| 10 |
//! exponent to allow the same range as [`f32`] but with only 8 bits of precision (instead of 11 |
| 11 |
//! bits for [`f16`]). See the [`bf16`] type for details. |
| 12 |
//! |
| 13 |
//! Because [`f16`] and [`bf16`] are primarily for efficient storage, floating point operations such |
| 14 |
//! as addition, multiplication, etc. are not always implemented by hardware. When hardware does not |
| 15 |
//! support these operations, this crate emulates them by converting the value to |
| 16 |
//! [`f32`] before performing the operation and then back afterward. |
| 17 |
//! |
| 18 |
//! Note that conversion from [`f32`]/[`f64`] to both [`f16`] and [`bf16`] are lossy operations, and |
| 19 |
//! just as converting a [`f64`] to [`f32`] is lossy and does not have `Into`/`From` trait |
| 20 |
//! implementations, so too do these smaller types not have those trait implementations either. |
| 21 |
//! Instead, use `from_f32`/`from_f64` functions for the types in this crate. If you don't care |
| 22 |
//! about lossy conversions and need trait conversions, use the appropriate [`num-traits`] |
| 23 |
//! traits that are implemented. |
| 24 |
//! |
| 25 |
//! This crate also provides a [`slice`][mod@slice] module for zero-copy in-place conversions of |
| 26 |
//! [`u16`] slices to both [`f16`] and [`bf16`], as well as efficient vectorized conversions of |
| 27 |
//! larger buffers of floating point values to and from these half formats. |
| 28 |
//! |
| 29 |
//! The crate supports `#[no_std]` when the `std` cargo feature is not enabled, so can be used in |
| 30 |
//! embedded environments without using the Rust [`std`] library. The `std` feature enables support |
| 31 |
//! for the standard library and is enabled by default, see the [Cargo Features](#cargo-features) |
| 32 |
//! section below. |
| 33 |
//! |
| 34 |
//! A [`prelude`] module is provided for easy importing of available utility traits. |
| 35 |
//! |
| 36 |
//! # Serialization |
| 37 |
//! |
| 38 |
//! When the `serde` feature is enabled, [`f16`] and [`bf16`] will be serialized as a newtype of |
| 39 |
//! [`u16`] by default. In binary formats this is ideal, as it will generally use just two bytes for |
| 40 |
//! storage. For string formats like JSON, however, this isn't as useful, and due to design |
| 41 |
//! limitations of serde, it's not possible for the default `Serialize` implementation to support |
| 42 |
//! different serialization for different formats. |
| 43 |
//! |
| 44 |
//! Instead, it's up to the containter type of the floats to control how it is serialized. This can |
| 45 |
//! easily be controlled when using the derive macros using `#[serde(serialize_with="")]` |
| 46 |
//! attributes. For both [`f16`] and [`bf16`] a `serialize_as_f32` and `serialize_as_string` are |
| 47 |
//! provided for use with this attribute. |
| 48 |
//! |
| 49 |
//! Deserialization of both float types supports deserializing from the default serialization, |
| 50 |
//! strings, and `f32`/`f64` values, so no additional work is required. |
| 51 |
//! |
| 52 |
//! # Hardware support |
| 53 |
//! |
| 54 |
//! Hardware support for these conversions and arithmetic will be used |
| 55 |
//! whenever hardware support is available—either through instrinsics or targeted assembly—although |
| 56 |
//! a nightly Rust toolchain may be required for some hardware. When hardware supports it the |
| 57 |
//! functions and traits in the [`slice`][mod@slice] and [`vec`] modules will also use vectorized |
| 58 |
//! SIMD intructions for increased efficiency. |
| 59 |
//! |
| 60 |
//! The following list details hardware support for floating point types in this crate. When using |
| 61 |
//! `std` cargo feature, runtime CPU target detection will be used. To get the most performance |
| 62 |
//! benefits, compile for specific CPU features which avoids the runtime overhead and works in a |
| 63 |
//! `no_std` environment. |
| 64 |
//! |
| 65 |
//! | Architecture | CPU Target Feature | Notes | |
| 66 |
//! | ------------ | ------------------ | ----- | |
| 67 |
//! | `x86`/`x86_64` | `f16c` | This supports conversion to/from [`f16`] only (including vector SIMD) and does not support any [`bf16`] or arithmetic operations. | |
| 68 |
//! | `aarch64` | `fp16` | This supports all operations on [`f16`] only. | |
| 69 |
//! |
| 70 |
//! # Cargo Features |
| 71 |
//! |
| 72 |
//! This crate supports a number of optional cargo features. None of these features are enabled by |
| 73 |
//! default, even `std`. |
| 74 |
//! |
| 75 |
//! - **`alloc`** — Enable use of the [`alloc`] crate when not using the `std` library. |
| 76 |
//! |
| 77 |
//! Among other functions, this enables the [`vec`] module, which contains zero-copy |
| 78 |
//! conversions for the [`Vec`] type. This allows fast conversion between raw `Vec<u16>` bits and |
| 79 |
//! `Vec<f16>` or `Vec<bf16>` arrays, and vice versa. |
| 80 |
//! |
| 81 |
//! - **`std`** — Enable features that depend on the Rust [`std`] library. This also enables the |
| 82 |
//! `alloc` feature automatically. |
| 83 |
//! |
| 84 |
//! Enabling the `std` feature enables runtime CPU feature detection of hardware support. |
| 85 |
//! Without this feature detection, harware is only used when compiler target supports them. |
| 86 |
//! |
| 87 |
//! - **`serde`** — Adds support for the [`serde`] crate by implementing [`Serialize`] and |
| 88 |
//! [`Deserialize`] traits for both [`f16`] and [`bf16`]. |
| 89 |
//! |
| 90 |
//! - **`num-traits`** — Adds support for the [`num-traits`] crate by implementing [`ToPrimitive`], |
| 91 |
//! [`FromPrimitive`], [`AsPrimitive`], [`Num`], [`Float`], [`FloatCore`], and [`Bounded`] traits |
| 92 |
//! for both [`f16`] and [`bf16`]. |
| 93 |
//! |
| 94 |
//! - **`bytemuck`** — Adds support for the [`bytemuck`] crate by implementing [`Zeroable`] and |
| 95 |
//! [`Pod`] traits for both [`f16`] and [`bf16`]. |
| 96 |
//! |
| 97 |
//! - **`zerocopy`** — Adds support for the [`zerocopy`] crate by implementing [`AsBytes`] and |
| 98 |
//! [`FromBytes`] traits for both [`f16`] and [`bf16`]. |
| 99 |
//! |
| 100 |
//! - **`rand_distr`** — Adds support for the [`rand_distr`] crate by implementing [`Distribution`] |
| 101 |
//! and other traits for both [`f16`] and [`bf16`]. |
| 102 |
//! |
| 103 |
//! - **`rkyv`** -- Enable zero-copy deserializtion with [`rkyv`] crate. |
| 104 |
//! |
| 105 |
//! [`alloc`]: https://doc.rust-lang.org/alloc/ |
| 106 |
//! [`std`]: https://doc.rust-lang.org/std/ |
| 107 |
//! [`binary16`]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format |
| 108 |
//! [`bfloat16`]: https://en.wikipedia.org/wiki/Bfloat16_floating-point_format |
| 109 |
//! [`serde`]: https://crates.io/crates/serde |
| 110 |
//! [`bytemuck`]: https://crates.io/crates/bytemuck |
| 111 |
//! [`num-traits`]: https://crates.io/crates/num-traits |
| 112 |
//! [`zerocopy`]: https://crates.io/crates/zerocopy |
| 113 |
//! [`rand_distr`]: https://crates.io/crates/rand_distr |
| 114 |
//! [`rkyv`]: (https://crates.io/crates/rkyv) |
| 115 |
#![cfg_attr( |
| 116 |
feature = "alloc", |
| 117 |
doc = " |
| 118 |
[`vec`]: mod@vec" |
| 119 |
)] |
| 120 |
#![cfg_attr( |
| 121 |
not(feature = "alloc"), |
| 122 |
doc = " |
| 123 |
[`vec`]: # |
| 124 |
[`Vec`]: https://docs.rust-lang.org/stable/alloc/vec/struct.Vec.html" |
| 125 |
)] |
| 126 |
#![cfg_attr( |
| 127 |
feature = "serde", |
| 128 |
doc = " |
| 129 |
[`Serialize`]: serde::Serialize |
| 130 |
[`Deserialize`]: serde::Deserialize" |
| 131 |
)] |
| 132 |
#![cfg_attr( |
| 133 |
not(feature = "serde"), |
| 134 |
doc = " |
| 135 |
[`Serialize`]: https://docs.rs/serde/*/serde/trait.Serialize.html |
| 136 |
[`Deserialize`]: https://docs.rs/serde/*/serde/trait.Deserialize.html" |
| 137 |
)] |
| 138 |
#![cfg_attr( |
| 139 |
feature = "num-traits", |
| 140 |
doc = " |
| 141 |
[`ToPrimitive`]: ::num_traits::ToPrimitive |
| 142 |
[`FromPrimitive`]: ::num_traits::FromPrimitive |
| 143 |
[`AsPrimitive`]: ::num_traits::AsPrimitive |
| 144 |
[`Num`]: ::num_traits::Num |
| 145 |
[`Float`]: ::num_traits::Float |
| 146 |
[`FloatCore`]: ::num_traits::float::FloatCore |
| 147 |
[`Bounded`]: ::num_traits::Bounded" |
| 148 |
)] |
| 149 |
#![cfg_attr( |
| 150 |
not(feature = "num-traits"), |
| 151 |
doc = " |
| 152 |
[`ToPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.ToPrimitive.html |
| 153 |
[`FromPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.FromPrimitive.html |
| 154 |
[`AsPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.AsPrimitive.html |
| 155 |
[`Num`]: https://docs.rs/num-traits/*/num_traits/trait.Num.html |
| 156 |
[`Float`]: https://docs.rs/num-traits/*/num_traits/float/trait.Float.html |
| 157 |
[`FloatCore`]: https://docs.rs/num-traits/*/num_traits/float/trait.FloatCore.html |
| 158 |
[`Bounded`]: https://docs.rs/num-traits/*/num_traits/bounds/trait.Bounded.html" |
| 159 |
)] |
| 160 |
#![cfg_attr( |
| 161 |
feature = "bytemuck", |
| 162 |
doc = " |
| 163 |
[`Zeroable`]: bytemuck::Zeroable |
| 164 |
[`Pod`]: bytemuck::Pod" |
| 165 |
)] |
| 166 |
#![cfg_attr( |
| 167 |
not(feature = "bytemuck"), |
| 168 |
doc = " |
| 169 |
[`Zeroable`]: https://docs.rs/bytemuck/*/bytemuck/trait.Zeroable.html |
| 170 |
[`Pod`]: https://docs.rs/bytemuck/*bytemuck/trait.Pod.html" |
| 171 |
)] |
| 172 |
#![cfg_attr( |
| 173 |
feature = "zerocopy", |
| 174 |
doc = " |
| 175 |
[`AsBytes`]: zerocopy::AsBytes |
| 176 |
[`FromBytes`]: zerocopy::FromBytes" |
| 177 |
)] |
| 178 |
#![cfg_attr( |
| 179 |
not(feature = "zerocopy"), |
| 180 |
doc = " |
| 181 |
[`AsBytes`]: https://docs.rs/zerocopy/*/zerocopy/trait.AsBytes.html |
| 182 |
[`FromBytes`]: https://docs.rs/zerocopy/*/zerocopy/trait.FromBytes.html" |
| 183 |
)] |
| 184 |
#![cfg_attr( |
| 185 |
feature = "rand_distr", |
| 186 |
doc = " |
| 187 |
[`Distribution`]: rand::distributions::Distribution" |
| 188 |
)] |
| 189 |
#![cfg_attr( |
| 190 |
not(feature = "rand_distr"), |
| 191 |
doc = " |
| 192 |
[`Distribution`]: https://docs.rs/rand/*/rand/distributions/trait.Distribution.html" |
| 193 |
)] |
| 194 |
#![warn( |
| 195 |
missing_docs, |
| 196 |
missing_copy_implementations, |
| 197 |
trivial_numeric_casts, |
| 198 |
future_incompatible |
| 199 |
)] |
| 200 |
#![cfg_attr(not(target_arch = "spirv"), warn(missing_debug_implementations))] |
| 201 |
#![allow(clippy::verbose_bit_mask, clippy::cast_lossless)] |
| 202 |
#![cfg_attr(not(feature = "std"), no_std)] |
| 203 |
#![doc(html_root_url = "https://docs.rs/half/2.4.1")] |
| 204 |
#![doc(test(attr(deny(warnings), allow(unused))))] |
| 205 |
#![cfg_attr(docsrs, feature(doc_auto_cfg))] |
| 206 |
|
| 207 |
#[cfg(feature = "alloc")] |
| 208 |
extern crate alloc; |
| 209 |
|
| 210 |
mod bfloat; |
| 211 |
mod binary16; |
| 212 |
mod leading_zeros; |
| 213 |
#[cfg(feature = "num-traits")] |
| 214 |
mod num_traits; |
| 215 |
|
| 216 |
#[cfg(not(target_arch = "spirv"))] |
| 217 |
pub mod slice; |
| 218 |
#[cfg(feature = "alloc")] |
| 219 |
pub mod vec; |
| 220 |
|
| 221 |
pub use bfloat::bf16; |
| 222 |
pub use binary16::f16; |
| 223 |
|
| 224 |
#[cfg(feature = "rand_distr")] |
| 225 |
mod rand_distr; |
| 226 |
|
| 227 |
/// A collection of the most used items and traits in this crate for easy importing. |
| 228 |
/// |
| 229 |
/// # Examples |
| 230 |
/// |
| 231 |
/// ```rust |
| 232 |
/// use half::prelude::*; |
| 233 |
/// ``` |
| 234 |
pub mod prelude { |
| 235 |
#[doc(no_inline)] |
| 236 |
pub use crate::{bf16, f16}; |
| 237 |
|
| 238 |
#[cfg(not(target_arch = "spirv"))] |
| 239 |
#[doc(no_inline)] |
| 240 |
pub use crate::slice::{HalfBitsSliceExt, HalfFloatSliceExt}; |
| 241 |
|
| 242 |
#[cfg(feature = "alloc")] |
| 243 |
#[doc(no_inline)] |
| 244 |
pub use crate::vec::{HalfBitsVecExt, HalfFloatVecExt}; |
| 245 |
} |
| 246 |
|
| 247 |
// Keep this module private to crate |
| 248 |
mod private { |
| 249 |
use crate::{bf16, f16}; |
| 250 |
|
| 251 |
pub trait SealedHalf {} |
| 252 |
|
| 253 |
impl SealedHalf for f16 {} |
| 254 |
impl SealedHalf for bf16 {} |
| 255 |
} |