half-1.7.1/src/vec.rs

//! Contains utility functions and traits to convert between vectors of `u16` bits and `f16` or
//! `bf16` vectors.
//!
//! The utility [`HalfBitsVecExt`] sealed extension trait is implemented for `Vec<u16>` vectors,
//! while the utility [`HalfFloatVecExt`] sealed extension trait is implemented for both `Vec<f16>`
//! and `Vec<bf16>` vectors. These traits provide efficient conversions and reinterpret casting of
//! larger buffers of floating point values, and are automatically included in the [`prelude`]
//! module.
//!
//! This module is only available with the `std` or `alloc` feature.
//!
//! [`HalfBitsVecExt`]: trait.HalfBitsVecExt.html
//! [`HalfFloatVecExt`]: trait.HalfFloatVecExt.html
//! [`prelude`]: ../prelude/index.html

#![cfg(any(feature = "alloc", feature = "std"))]

use super::{bf16, f16, slice::HalfFloatSliceExt};
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::vec::Vec;
use core::mem;

/// Extensions to `Vec<f16>` and `Vec<bf16>` to support reinterpret operations.
///
/// This trait is sealed and cannot be implemented outside of this crate.
pub trait HalfFloatVecExt: private::SealedHalfFloatVec {
    /// Reinterpret a vector of [`f16`](../struct.f16.html) or [`bf16`](../struct.bf16.html)
    /// numbers as a vector of `u16` bits.
    ///
    /// This is a zero-copy operation. The reinterpreted vector has the same memory location as
    /// `self`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use half::prelude::*;
    /// let float_buffer = vec![f16::from_f32(1.), f16::from_f32(2.), f16::from_f32(3.)];
    /// let int_buffer = float_buffer.reinterpret_into();
    ///
    /// assert_eq!(int_buffer, [f16::from_f32(1.).to_bits(), f16::from_f32(2.).to_bits(), f16::from_f32(3.).to_bits()]);
    /// ```
    fn reinterpret_into(self) -> Vec<u16>;

    /// Convert all of the elements of a `[f32]` slice into a new [`f16`](../struct.f16.html) or
    /// [`bf16`](../struct.bf16.html) vector.
    ///
    /// The conversion operation is vectorized over the slice, meaning the conversion may be more
    /// efficient than converting individual elements on some hardware that supports SIMD
    /// conversions. See [crate documentation](../index.html) for more information on hardware
    /// conversion support.
    ///
    /// # Examples
    /// ```rust
    /// # use half::prelude::*;
    /// let float_values = [1., 2., 3., 4.];
    /// let vec: Vec<f16> = Vec::from_f32_slice(&float_values);
    ///
    /// assert_eq!(vec, vec![f16::from_f32(1.), f16::from_f32(2.), f16::from_f32(3.), f16::from_f32(4.)]);
    /// ```
    fn from_f32_slice(slice: &[f32]) -> Self;

    /// Convert all of the elements of a `[f64]` slice into a new [`f16`](../struct.f16.html) or
    /// [`bf16`](../struct.bf16.html) vector.
    ///
    /// The conversion operation is vectorized over the slice, meaning the conversion may be more
    /// efficient than converting individual elements on some hardware that supports SIMD
    /// conversions. See [crate documentation](../index.html) for more information on hardware
    /// conversion support.
    ///
    /// # Examples
    /// ```rust
    /// # use half::prelude::*;
    /// let float_values = [1., 2., 3., 4.];
    /// let vec: Vec<f16> = Vec::from_f64_slice(&float_values);
    ///
    /// assert_eq!(vec, vec![f16::from_f64(1.), f16::from_f64(2.), f16::from_f64(3.), f16::from_f64(4.)]);
    /// ```
    fn from_f64_slice(slice: &[f64]) -> Self;
}

/// Extensions to `Vec<u16>` to support reinterpret operations.
///
/// This trait is sealed and cannot be implemented outside of this crate.
pub trait HalfBitsVecExt: private::SealedHalfBitsVec {
    /// Reinterpret a vector of `u16` bits as a vector of [`f16`](../struct.f16.html) or
    /// [`bf16`](../struct.bf16.html) numbers.
    ///
    /// `H` is the type to cast to, and must be either the [`f16`](../struct.f16.html) or
    /// [`bf16`](../struct.bf16.html) type.
    ///
    /// This is a zero-copy operation. The reinterpreted vector has the same memory location as
    /// `self`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use half::prelude::*;
    /// let int_buffer = vec![f16::from_f32(1.).to_bits(), f16::from_f32(2.).to_bits(), f16::from_f32(3.).to_bits()];
    /// let float_buffer = int_buffer.reinterpret_into::<f16>();
    ///
    /// assert_eq!(float_buffer, [f16::from_f32(1.), f16::from_f32(2.), f16::from_f32(3.)]);
    /// ```
    fn reinterpret_into<H>(self) -> Vec<H>
    where
        H: crate::private::SealedHalf;
}

mod private {
    use crate::{bf16, f16};
    #[cfg(all(feature = "alloc", not(feature = "std")))]
    use alloc::vec::Vec;

    pub trait SealedHalfFloatVec {}
    impl SealedHalfFloatVec for Vec<f16> {}
    impl SealedHalfFloatVec for Vec<bf16> {}

    pub trait SealedHalfBitsVec {}
    impl SealedHalfBitsVec for Vec<u16> {}
}

impl HalfFloatVecExt for Vec<f16> {
    #[inline]
    fn reinterpret_into(mut self) -> Vec<u16> {
        // An f16 array has same length and capacity as u16 array
        let length = self.len();
        let capacity = self.capacity();

        // Actually reinterpret the contents of the Vec<f16> as u16,
        // knowing that structs are represented as only their members in memory,
        // which is the u16 part of `f16(u16)`
        let pointer = self.as_mut_ptr() as *mut u16;

        // Prevent running a destructor on the old Vec<u16>, so the pointer won't be deleted
        mem::forget(self);

        // Finally construct a new Vec<f16> from the raw pointer
        // SAFETY: We are reconstructing full length and capacity of original vector,
        // using its original pointer, and the size of elements are identical.
        unsafe { Vec::from_raw_parts(pointer, length, capacity) }
    }

    fn from_f32_slice(slice: &[f32]) -> Self {
        let mut vec = Vec::with_capacity(slice.len());
        // SAFETY: convert will initialize every value in the vector without reading them,
        // so this is safe to do instead of double initialize from resize, and we're setting it to
        // same value as capacity.
        unsafe { vec.set_len(slice.len()) };
        vec.convert_from_f32_slice(&slice);
        vec
    }

    fn from_f64_slice(slice: &[f64]) -> Self {
        let mut vec = Vec::with_capacity(slice.len());
        // SAFETY: convert will initialize every value in the vector without reading them,
        // so this is safe to do instead of double initialize from resize, and we're setting it to
        // same value as capacity.
        unsafe { vec.set_len(slice.len()) };
        vec.convert_from_f64_slice(&slice);
        vec
    }
}

impl HalfFloatVecExt for Vec<bf16> {
    #[inline]
    fn reinterpret_into(mut self) -> Vec<u16> {
        // An f16 array has same length and capacity as u16 array
        let length = self.len();
        let capacity = self.capacity();

        // Actually reinterpret the contents of the Vec<f16> as u16,
        // knowing that structs are represented as only their members in memory,
        // which is the u16 part of `f16(u16)`
        let pointer = self.as_mut_ptr() as *mut u16;

        // Prevent running a destructor on the old Vec<u16>, so the pointer won't be deleted
        mem::forget(self);

        // Finally construct a new Vec<f16> from the raw pointer
        // SAFETY: We are reconstructing full length and capacity of original vector,
        // using its original pointer, and the size of elements are identical.
        unsafe { Vec::from_raw_parts(pointer, length, capacity) }
    }

    fn from_f32_slice(slice: &[f32]) -> Self {
        let mut vec = Vec::with_capacity(slice.len());
        // SAFETY: convert will initialize every value in the vector without reading them,
        // so this is safe to do instead of double initialize from resize, and we're setting it to
        // same value as capacity.
        unsafe { vec.set_len(slice.len()) };
        vec.convert_from_f32_slice(&slice);
        vec
    }

    fn from_f64_slice(slice: &[f64]) -> Self {
        let mut vec = Vec::with_capacity(slice.len());
        // SAFETY: convert will initialize every value in the vector without reading them,
        // so this is safe to do instead of double initialize from resize, and we're setting it to
        // same value as capacity.
        unsafe { vec.set_len(slice.len()) };
        vec.convert_from_f64_slice(&slice);
        vec
    }
}

impl HalfBitsVecExt for Vec<u16> {
    // This is safe because all traits are sealed
    #[inline]
    fn reinterpret_into<H>(mut self) -> Vec<H>
    where
        H: crate::private::SealedHalf,
    {
        // An f16 array has same length and capacity as u16 array
        let length = self.len();
        let capacity = self.capacity();

        // Actually reinterpret the contents of the Vec<u16> as f16,
        // knowing that structs are represented as only their members in memory,
        // which is the u16 part of `f16(u16)`
        let pointer = self.as_mut_ptr() as *mut H;

        // Prevent running a destructor on the old Vec<u16>, so the pointer won't be deleted
        mem::forget(self);

        // Finally construct a new Vec<f16> from the raw pointer
        // SAFETY: We are reconstructing full length and capacity of original vector,
        // using its original pointer, and the size of elements are identical.
        unsafe { Vec::from_raw_parts(pointer, length, capacity) }
    }
}

/// Converts a vector of `u16` elements into a vector of [`f16`](../struct.f16.html) elements.
///
/// This function merely reinterprets the contents of the vector, so it's a zero-copy operation.
#[deprecated(
    since = "1.4.0",
    note = "use [`HalfBitsVecExt::reinterpret_into`](trait.HalfBitsVecExt.html#tymethod.reinterpret_into) instead"
)]
#[inline]
pub fn from_bits(bits: Vec<u16>) -> Vec<f16> {
    bits.reinterpret_into()
}

/// Converts a vector of [`f16`](../struct.f16.html) elements into a vector of `u16` elements.
///
/// This function merely reinterprets the contents of the vector, so it's a zero-copy operation.
#[deprecated(
    since = "1.4.0",
    note = "use [`HalfFloatVecExt::reinterpret_into`](trait.HalfFloatVecExt.html#tymethod.reinterpret_into) instead"
)]
#[inline]
pub fn to_bits(numbers: Vec<f16>) -> Vec<u16> {
    numbers.reinterpret_into()
}

#[cfg(test)]
mod test {
    use super::{HalfBitsVecExt, HalfFloatVecExt};
    use crate::{bf16, f16};
    #[cfg(all(feature = "alloc", not(feature = "std")))]
    use alloc::vec;

    #[test]
    fn test_vec_conversions_f16() {
        let numbers = vec![f16::E, f16::PI, f16::EPSILON, f16::FRAC_1_SQRT_2];
        let bits = vec![
            f16::E.to_bits(),
            f16::PI.to_bits(),
            f16::EPSILON.to_bits(),
            f16::FRAC_1_SQRT_2.to_bits(),
        ];
        let bits_cloned = bits.clone();

        // Convert from bits to numbers
        let from_bits = bits.reinterpret_into::<f16>();
        assert_eq!(&from_bits[..], &numbers[..]);

        // Convert from numbers back to bits
        let to_bits = from_bits.reinterpret_into();
        assert_eq!(&to_bits[..], &bits_cloned[..]);
    }

    #[test]
    fn test_vec_conversions_bf16() {
        let numbers = vec![bf16::E, bf16::PI, bf16::EPSILON, bf16::FRAC_1_SQRT_2];
        let bits = vec![
            bf16::E.to_bits(),
            bf16::PI.to_bits(),
            bf16::EPSILON.to_bits(),
            bf16::FRAC_1_SQRT_2.to_bits(),
        ];
        let bits_cloned = bits.clone();

        // Convert from bits to numbers
        let from_bits = bits.reinterpret_into::<bf16>();
        assert_eq!(&from_bits[..], &numbers[..]);

        // Convert from numbers back to bits
        let to_bits = from_bits.reinterpret_into();
        assert_eq!(&to_bits[..], &bits_cloned[..]);
    }
}