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 as
14 //! addition, multiplication, etc. are not implemented. Operations should be performed with `f32`
15 //! or higher-precision types and converted to/from [`f16`] or [`bf16`] as necessary.
16 //!
17 //! This crate also provides a [`slice`] module for zero-copy in-place conversions of `u16` slices
18 //! to both [`f16`] and [`bf16`], as well as efficient vectorized conversions of larger buffers of
19 //! floating point values to and from these half formats.
20 //!
21 //! A [`prelude`] module is provided for easy importing of available utility traits.
22 //!
23 //! Some hardware architectures provide support for 16-bit floating point conversions. Enable the
24 //! `use-intrinsics` feature to use LLVM intrinsics for hardware conversions. This crate does no
25 //! checks on whether the hardware supports the feature. This feature currently only works on
26 //! nightly Rust due to a compiler feature gate. When this feature is enabled and the hardware
27 //! supports it, the [`slice`] trait conversions will use vectorized SIMD intructions for
28 //! increased efficiency.
29 //!
30 //! Support for [`serde`] crate `Serialize` and `Deserialize` traits is provided when the `serde`
31 //! feature is enabled. This adds a dependency on [`serde`] crate so is an optional cargo feature.
32 //! Support for [`bytemuck`] crate `Zeroable` and `Pod` traits is provided with the `bytemuck`
33 //! feature. Support for the [`num-traits`] crate `ToPrimitive` and `FromPrimitive` traits is
34 //! provided with the `num-traits` feature.
35 //!
36 //! The crate uses `#[no_std]` by default, so can be used in embedded environments without using the
37 //! Rust `std` library. A `std` feature is available, which enables additional utilities using the
38 //! `std` library, such as the [`vec`] module that provides zero-copy `Vec` conversions. The `alloc`
39 //! feature may be used to enable the [`vec`] module without adding a dependency to the `std`
40 //! library.
41 //!
42 //! [`f16`]: struct.f16.html
43 //! [`binary16`]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format
44 //! [`bf16`]: struct.bf16.html
45 //! [`bfloat16`]: https://en.wikipedia.org/wiki/Bfloat16_floating-point_format
46 //! [`slice`]: slice/index.html
47 //! [`prelude`]: prelude/index.html
48 //! [`serde`]: https://crates.io/crates/serde
49 //! [`bytemuck`]: https://crates.io/crates/bytemuck
50 //! [`num-traits`]: https://crates.io/crates/num-traits
51 //! [`vec`]: vec/index.html
52 
53 #![warn(
54     missing_docs,
55     missing_copy_implementations,
56     missing_debug_implementations,
57     trivial_numeric_casts,
58     unused_extern_crates,
59     unused_import_braces,
60     future_incompatible,
61     rust_2018_compatibility,
62     rust_2018_idioms,
63     clippy::all
64 )]
65 #![allow(clippy::verbose_bit_mask, clippy::cast_lossless)]
66 #![cfg_attr(not(feature = "std"), no_std)]
67 #![cfg_attr(
68     all(
69         feature = "use-intrinsics",
70         any(target_arch = "x86", target_arch = "x86_64")
71     ),
72     feature(stdsimd, f16c_target_feature)
73 )]
74 #![doc(html_root_url = "https://docs.rs/half/1.7.1")]
75 
76 #[cfg(all(feature = "alloc", not(feature = "std")))]
77 extern crate alloc;
78 
79 mod bfloat;
80 mod binary16;
81 pub mod slice;
82 #[cfg(any(feature = "alloc", feature = "std"))]
83 pub mod vec;
84 
85 pub use binary16::f16;
86 
87 #[allow(deprecated)]
88 pub use binary16::consts;
89 
90 pub use bfloat::bf16;
91 
92 /// A collection of the most used items and traits in this crate for easy importing.
93 ///
94 /// # Examples
95 ///
96 /// ```rust
97 /// use half::prelude::*;
98 /// ```
99 pub mod prelude {
100     #[doc(no_inline)]
101     pub use crate::{
102         bf16, f16,
103         slice::{HalfBitsSliceExt, HalfFloatSliceExt},
104     };
105 
106     #[cfg(any(feature = "alloc", feature = "std"))]
107     pub use crate::vec::{HalfBitsVecExt, HalfFloatVecExt};
108 }
109 
110 // Keep this module private to crate
111 pub(crate) mod private {
112     use crate::{bf16, f16};
113 
114     pub trait SealedHalf {}
115 
116     impl SealedHalf for f16 {}
117     impl SealedHalf for bf16 {}
118 }
119