From 6300fcc486b4676ad819a415dc05f9238f421870 Mon Sep 17 00:00:00 2001 From: Trevor Spiteri Date: Wed, 24 Feb 2021 16:27:52 +0100 Subject: [PATCH] add {from,to}_{be,le,ne}_bytes to {Wrapping,Unwrapped} wrappers --- README.md | 16 ++++++- RELEASES.md | 14 +++++- src/lib.rs | 2 +- src/unwrapped.rs | 114 +++++++++++++++++++++++++++++++++++++++++++++++ src/wrapping.rs | 114 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 256 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3a4a28d..80b29ad 100644 --- a/README.md +++ b/README.md @@ -88,17 +88,29 @@ The conversions supported cover the following cases. * [`to_be`][f-tb-1-7], [`to_le`][f-tl-1-7] * [`swap_bytes`][f-sb-1-7], * [`reverse_bits`][f-rb-1-7] + * The following methods were added to the [`Wrapping`][w-1-7] and + [`Unwrapped`][u-1-7] wrappers: + * [`from_be_bytes`][f-fbb-1-7], [`from_le_bytes`][f-flb-1-7], + [`from_ne_bytes`][f-fnb-1-7] + * [`to_be_bytes`][f-tbb-1-7], [`to_le_bytes`][f-tlb-1-7], + [`to_ne_bytes`][f-tnb-1-7] * For the experimental feature [`num-traits`][feat-exp-1-7], the - following traits were implemented where applicable: + following traits were implemented for all fixed-point numbers: * [`OverflowingAdd`][nt-0-2-oa], [`OverflowingSub`][nt-0-2-os], [`OverflowingMul`][nt-0-2-om] [f-fb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_be +[f-fbb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_be_bytes [f-fl-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_le +[f-flb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_le_bytes +[f-fnb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_ne_bytes [f-rb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.reverse_bits [f-sb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.swap_bytes [f-tb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_be +[f-tbb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_be_bytes [f-tl-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_le +[f-tlb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_le_bytes +[f-tnb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_ne_bytes [feat-exp-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/#experimental-optional-features [nt-0-2-oa]: https://docs.rs/num-traits/^0.2/num_traits/ops/overflowing/trait.OverflowingAdd.html [nt-0-2-om]: https://docs.rs/num-traits/^0.2/num_traits/ops/overflowing/trait.OverflowingMul.html @@ -267,7 +279,7 @@ dependencies can be updated to an incompatible newer version. There is one experimental feature: 1. `num-traits`, disabled by default. This implements some traits - from the [*num-traits* crate]. (The plan is to upgrade this to an + from the [*num-traits* crate]. (The plan is to promote this to an optional feature once the [*num-traits* crate] reaches version 1.0.0.) diff --git a/RELEASES.md b/RELEASES.md index b22b6f8..6032e4a 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -15,17 +15,29 @@ Version 1.7.0 (unreleased) * [`to_be`][f-tb-1-7], [`to_le`][f-tl-1-7] * [`swap_bytes`][f-sb-1-7], * [`reverse_bits`][f-rb-1-7] + * The following methods were added to the [`Wrapping`][w-1-7] and + [`Unwrapped`][u-1-7] wrappers: + * [`from_be_bytes`][f-fbb-1-7], [`from_le_bytes`][f-flb-1-7], + [`from_ne_bytes`][f-fnb-1-7] + * [`to_be_bytes`][f-tbb-1-7], [`to_le_bytes`][f-tlb-1-7], + [`to_ne_bytes`][f-tnb-1-7] * For the experimental feature [`num-traits`][feat-exp-1-7], the - following traits were implemented where applicable: + following traits were implemented for all fixed-point numbers: * [`OverflowingAdd`][nt-0-2-oa], [`OverflowingSub`][nt-0-2-os], [`OverflowingMul`][nt-0-2-om] [f-fb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_be +[f-fbb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_be_bytes [f-fl-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_le +[f-flb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_le_bytes +[f-fnb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.from_ne_bytes [f-rb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.reverse_bits [f-sb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.swap_bytes [f-tb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_be +[f-tbb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_be_bytes [f-tl-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_le +[f-tlb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_le_bytes +[f-tnb-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.to_ne_bytes [feat-exp-1-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/#experimental-optional-features [nt-0-2-oa]: https://docs.rs/num-traits/^0.2/num_traits/ops/overflowing/trait.OverflowingAdd.html [nt-0-2-om]: https://docs.rs/num-traits/^0.2/num_traits/ops/overflowing/trait.OverflowingMul.html diff --git a/src/lib.rs b/src/lib.rs index 1ea236b..9a3f2e9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -209,7 +209,7 @@ dependencies can be updated to an incompatible newer version. There is one experimental feature: 1. `num-traits`, disabled by default. This implements some traits - from the [*num-traits* crate]. (The plan is to upgrade this to an + from the [*num-traits* crate]. (The plan is to promote this to an optional feature once the [*num-traits* crate] reaches version 1.0.0.) diff --git a/src/unwrapped.rs b/src/unwrapped.rs index ff963f7..99bf61b 100644 --- a/src/unwrapped.rs +++ b/src/unwrapped.rs @@ -210,6 +210,120 @@ impl Unwrapped { Unwrapped(self.0.swap_bytes()) } + /// Creates a fixed-point number from its representation + /// as a byte array in big endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// let bytes = [0x12, 0x34, 0x56, 0x78]; + /// assert_eq!( + /// Unwrapped::::from_be_bytes(bytes), + /// Unwrapped::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_be_bytes(bytes: F::Bytes) -> Self { + Unwrapped(F::from_be_bytes(bytes)) + } + + /// Creates a fixed-point number from its representation + /// as a byte array in little endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// let bytes = [0x78, 0x56, 0x34, 0x12]; + /// assert_eq!( + /// Unwrapped::::from_le_bytes(bytes), + /// Unwrapped::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_le_bytes(bytes: F::Bytes) -> Self { + Unwrapped(F::from_le_bytes(bytes)) + } + + /// Creates a fixed-point number from its representation + /// as a byte array in native endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// let bytes = if cfg!(target_endian = "big") { + /// [0x12, 0x34, 0x56, 0x78] + /// } else { + /// [0x78, 0x56, 0x34, 0x12] + /// }; + /// assert_eq!( + /// Unwrapped::::from_ne_bytes(bytes), + /// Unwrapped::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_ne_bytes(bytes: F::Bytes) -> Self { + Unwrapped(F::from_ne_bytes(bytes)) + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in big-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// assert_eq!( + /// Unwrapped::::from_bits(0x1234_5678).to_be_bytes(), + /// [0x12, 0x34, 0x56, 0x78] + /// ); + /// ``` + #[inline] + pub fn to_be_bytes(self) -> F::Bytes { + self.0.to_be_bytes() + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in little-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// assert_eq!( + /// Unwrapped::::from_bits(0x1234_5678).to_le_bytes(), + /// [0x78, 0x56, 0x34, 0x12] + /// ); + /// ``` + #[inline] + pub fn to_le_bytes(self) -> F::Bytes { + self.0.to_le_bytes() + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in native-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Unwrapped}; + /// let bytes = if cfg!(target_endian = "big") { + /// [0x12, 0x34, 0x56, 0x78] + /// } else { + /// [0x78, 0x56, 0x34, 0x12] + /// }; + /// assert_eq!( + /// Unwrapped::::from_bits(0x1234_5678).to_ne_bytes(), + /// bytes + /// ); + /// ``` + #[inline] + pub fn to_ne_bytes(self) -> F::Bytes { + self.0.to_ne_bytes() + } + /// Unwrapped conversion from another number. /// /// The other number can be: diff --git a/src/wrapping.rs b/src/wrapping.rs index feb2ce1..4ae2e64 100644 --- a/src/wrapping.rs +++ b/src/wrapping.rs @@ -207,6 +207,120 @@ impl Wrapping { Wrapping(self.0.swap_bytes()) } + /// Creates a fixed-point number from its representation + /// as a byte array in big endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// let bytes = [0x12, 0x34, 0x56, 0x78]; + /// assert_eq!( + /// Wrapping::::from_be_bytes(bytes), + /// Wrapping::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_be_bytes(bytes: F::Bytes) -> Self { + Wrapping(F::from_be_bytes(bytes)) + } + + /// Creates a fixed-point number from its representation + /// as a byte array in little endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// let bytes = [0x78, 0x56, 0x34, 0x12]; + /// assert_eq!( + /// Wrapping::::from_le_bytes(bytes), + /// Wrapping::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_le_bytes(bytes: F::Bytes) -> Self { + Wrapping(F::from_le_bytes(bytes)) + } + + /// Creates a fixed-point number from its representation + /// as a byte array in native endian. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// let bytes = if cfg!(target_endian = "big") { + /// [0x12, 0x34, 0x56, 0x78] + /// } else { + /// [0x78, 0x56, 0x34, 0x12] + /// }; + /// assert_eq!( + /// Wrapping::::from_ne_bytes(bytes), + /// Wrapping::::from_bits(0x1234_5678) + /// ); + /// ``` + #[inline] + pub fn from_ne_bytes(bytes: F::Bytes) -> Self { + Wrapping(F::from_ne_bytes(bytes)) + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in big-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// assert_eq!( + /// Wrapping::::from_bits(0x1234_5678).to_be_bytes(), + /// [0x12, 0x34, 0x56, 0x78] + /// ); + /// ``` + #[inline] + pub fn to_be_bytes(self) -> F::Bytes { + self.0.to_be_bytes() + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in little-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// assert_eq!( + /// Wrapping::::from_bits(0x1234_5678).to_le_bytes(), + /// [0x78, 0x56, 0x34, 0x12] + /// ); + /// ``` + #[inline] + pub fn to_le_bytes(self) -> F::Bytes { + self.0.to_le_bytes() + } + + /// Returns the memory representation of this fixed-point + /// number as a byte array in native-endian byte order. + /// + /// # Examples + /// + /// ```rust + /// use fixed::{types::I16F16, Wrapping}; + /// let bytes = if cfg!(target_endian = "big") { + /// [0x12, 0x34, 0x56, 0x78] + /// } else { + /// [0x78, 0x56, 0x34, 0x12] + /// }; + /// assert_eq!( + /// Wrapping::::from_bits(0x1234_5678).to_ne_bytes(), + /// bytes + /// ); + /// ``` + #[inline] + pub fn to_ne_bytes(self) -> F::Bytes { + self.0.to_ne_bytes() + } + /// Wrapping conversion from another number. /// /// The other number can be: