1//! A crate that provides support for half-precision 16-bit floating point types.
2//!
3//! This crate provides the [`struct@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 [`struct@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 [`struct@f16`]). See the [`struct@bf16`] type for details.
12//!
13//! Because [`struct@f16`] and [`struct@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 [`struct@f16`] and [`struct@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 [`struct@f16`] and [`struct@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, [`struct@f16`] and [`struct@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 [`struct@f16`] and [`struct@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 [`struct@f16`] only (including vector SIMD) and does not support any [`struct@bf16`] or arithmetic operations. |
68//! | `aarch64` | `fp16` | This supports all operations on [`struct@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 [`struct@f16`] and [`struct@bf16`].
89//!
90//! - **`num-traits`** — Adds support for the [`num-traits`] crate by implementing [`ToPrimitive`],
91//! [`FromPrimitive`], [`ToBytes`], `FromBytes`, [`AsPrimitive`], [`Num`], [`Float`],
92//! [`FloatCore`], and [`Bounded`] traits for both [`struct@f16`] and [`struct@bf16`].
93//!
94//! - **`bytemuck`** — Adds support for the [`bytemuck`] crate by implementing [`Zeroable`] and
95//! [`Pod`] traits for both [`struct@f16`] and [`struct@bf16`].
96//!
97//! - **`zerocopy`** — Adds support for the [`zerocopy`] crate by implementing [`IntoBytes`] and
98//! [`FromBytes`] traits for both [`struct@f16`] and [`struct@bf16`].
99//!
100//! - **`rand_distr`** — Adds support for the [`rand_distr`] crate by implementing [`Distribution`]
101//! and other traits for both [`struct@f16`] and [`struct@bf16`].
102//!
103//! - **`rkyv`** -- Enable zero-copy deserializtion with [`rkyv`] crate.
104//!
105//! - **`aribtrary`** -- Enable fuzzing support with [`arbitrary`] crate by implementing
106//! [`Arbitrary`] trait.
107//!
108//! [`alloc`]: https://doc.rust-lang.org/alloc/
109//! [`std`]: https://doc.rust-lang.org/std/
110//! [`binary16`]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format
111//! [`bfloat16`]: https://en.wikipedia.org/wiki/Bfloat16_floating-point_format
112//! [`serde`]: https://crates.io/crates/serde
113//! [`bytemuck`]: https://crates.io/crates/bytemuck
114//! [`num-traits`]: https://crates.io/crates/num-traits
115//! [`zerocopy`]: https://crates.io/crates/zerocopy
116//! [`rand_distr`]: https://crates.io/crates/rand_distr
117//! [`rkyv`]: (https://crates.io/crates/rkyv)
118//! [`arbitrary`]: (https://crates.io/crates/arbitrary)
119#![cfg_attr(
120 feature = "alloc",
121 doc = "
122[`vec`]: mod@vec"
123)]
124#![cfg_attr(
125 not(feature = "alloc"),
126 doc = "
127[`vec`]: #
128[`Vec`]: https://docs.rust-lang.org/stable/alloc/vec/struct.Vec.html"
129)]
130#![cfg_attr(
131 feature = "serde",
132 doc = "
133[`Serialize`]: serde::Serialize
134[`Deserialize`]: serde::Deserialize"
135)]
136#![cfg_attr(
137 not(feature = "serde"),
138 doc = "
139[`Serialize`]: https://docs.rs/serde/*/serde/trait.Serialize.html
140[`Deserialize`]: https://docs.rs/serde/*/serde/trait.Deserialize.html"
141)]
142#![cfg_attr(
143 feature = "num-traits",
144 doc = "
145[`ToPrimitive`]: ::num_traits::ToPrimitive
146[`FromPrimitive`]: ::num_traits::FromPrimitive
147[`ToBytes`]: ::num_traits::ToBytes
148[`AsPrimitive`]: ::num_traits::AsPrimitive
149[`Num`]: ::num_traits::Num
150[`Float`]: ::num_traits::Float
151[`FloatCore`]: ::num_traits::float::FloatCore
152[`Bounded`]: ::num_traits::Bounded"
153)]
154#![cfg_attr(
155 not(feature = "num-traits"),
156 doc = "
157[`ToPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.ToPrimitive.html
158[`FromPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.FromPrimitive.html
159[`ToBytes`]: https://docs.rs/num-traits/*/num_traits/ops/bytes/trait.ToBytes.html
160[`AsPrimitive`]: https://docs.rs/num-traits/*/num_traits/cast/trait.AsPrimitive.html
161[`Num`]: https://docs.rs/num-traits/*/num_traits/trait.Num.html
162[`Float`]: https://docs.rs/num-traits/*/num_traits/float/trait.Float.html
163[`FloatCore`]: https://docs.rs/num-traits/*/num_traits/float/trait.FloatCore.html
164[`Bounded`]: https://docs.rs/num-traits/*/num_traits/bounds/trait.Bounded.html"
165)]
166#![cfg_attr(
167 feature = "bytemuck",
168 doc = "
169[`Zeroable`]: bytemuck::Zeroable
170[`Pod`]: bytemuck::Pod"
171)]
172#![cfg_attr(
173 not(feature = "bytemuck"),
174 doc = "
175[`Zeroable`]: https://docs.rs/bytemuck/*/bytemuck/trait.Zeroable.html
176[`Pod`]: https://docs.rs/bytemuck/*bytemuck/trait.Pod.html"
177)]
178#![cfg_attr(
179 feature = "zerocopy",
180 doc = "
181[`IntoBytes`]: zerocopy::IntoBytes
182[`FromBytes`]: zerocopy::FromBytes"
183)]
184#![cfg_attr(
185 not(feature = "zerocopy"),
186 doc = "
187[`IntoBytes`]: https://docs.rs/zerocopy/*/zerocopy/trait.IntoBytes.html
188[`FromBytes`]: https://docs.rs/zerocopy/*/zerocopy/trait.FromBytes.html"
189)]
190#![cfg_attr(
191 feature = "rand_distr",
192 doc = "
193[`Distribution`]: rand::distr::Distribution"
194)]
195#![cfg_attr(
196 not(feature = "rand_distr"),
197 doc = "
198[`Distribution`]: https://docs.rs/rand/*/rand/distr/trait.Distribution.html"
199)]
200#![cfg_attr(
201 feature = "arbitrary",
202 doc = "
203[`Arbitrary`]: arbitrary::Arbitrary"
204)]
205#![cfg_attr(
206 not(feature = "arbitrary"),
207 doc = "
208[`Arbitrary`]: https://docs.rs/arbitrary/*/arbitrary/trait.Arbitrary.html"
209)]
210#![warn(
211 missing_docs,
212 missing_copy_implementations,
213 trivial_numeric_casts,
214 future_incompatible
215)]
216#![cfg_attr(not(target_arch = "spirv"), warn(missing_debug_implementations))]
217#![allow(clippy::verbose_bit_mask, clippy::cast_lossless, unexpected_cfgs)]
218#![cfg_attr(not(feature = "std"), no_std)]
219#![doc(html_root_url = "https://docs.rs/half/2.6.0")]
220#![doc(test(attr(deny(warnings), allow(unused))))]
221#![cfg_attr(docsrs, feature(doc_auto_cfg))]
222
223#[cfg(feature = "alloc")]
224extern crate alloc;
225
226mod bfloat;
227mod binary16;
228mod leading_zeros;
229#[cfg(feature = "num-traits")]
230mod num_traits;
231
232#[cfg(not(target_arch = "spirv"))]
233pub mod slice;
234#[cfg(feature = "alloc")]
235pub mod vec;
236
237pub use bfloat::bf16;
238pub use binary16::f16;
239
240#[cfg(feature = "rand_distr")]
241mod rand_distr;
242
243/// A collection of the most used items and traits in this crate for easy importing.
244///
245/// # Examples
246///
247/// ```rust
248/// use half::prelude::*;
249/// ```
250pub mod prelude {
251 #[doc(no_inline)]
252 pub use crate::{bf16, f16};
253
254 #[cfg(not(target_arch = "spirv"))]
255 #[doc(no_inline)]
256 pub use crate::slice::{HalfBitsSliceExt, HalfFloatSliceExt};
257
258 #[cfg(feature = "alloc")]
259 #[doc(no_inline)]
260 pub use crate::vec::{HalfBitsVecExt, HalfFloatVecExt};
261}
262
263// Keep this module private to crate
264mod private {
265 use crate::{bf16, f16};
266
267 pub trait SealedHalf {}
268
269 impl SealedHalf for f16 {}
270 impl SealedHalf for bf16 {}
271}
272