Debian Codegraph @

.cargo/vendor/half/src/lib.rs

raw
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 }