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