zerocopy/
byteorder.rs

1// Copyright 2019 The Fuchsia Authors
2//
3// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
4// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
5// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6// This file may not be copied, modified, or distributed except according to
7// those terms.
8
9//! Byte order-aware numeric primitives.
10//!
11//! This module contains equivalents of the native multi-byte integer types with
12//! no alignment requirement and supporting byte order conversions.
13//!
14//! For each native multi-byte integer type - `u16`, `i16`, `u32`, etc - and
15//! floating point type - `f32` and `f64` - an equivalent type is defined by
16//! this module - [`U16`], [`I16`], [`U32`], [`F32`], [`F64`], etc. Unlike their
17//! native counterparts, these types have alignment 1, and take a type parameter
18//! specifying the byte order in which the bytes are stored in memory. Each type
19//! implements this crate's relevant conversion and marker traits.
20//!
21//! These two properties, taken together, make these types useful for defining
22//! data structures whose memory layout matches a wire format such as that of a
23//! network protocol or a file format. Such formats often have multi-byte values
24//! at offsets that do not respect the alignment requirements of the equivalent
25//! native types, and stored in a byte order not necessarily the same as that of
26//! the target platform.
27//!
28//! Type aliases are provided for common byte orders in the [`big_endian`],
29//! [`little_endian`], [`network_endian`], and [`native_endian`] submodules.
30//!
31//! # Example
32//!
33//! One use of these types is for representing network packet formats, such as
34//! UDP:
35//!
36//! ```rust
37//! use zerocopy::{*, byteorder::network_endian::U16};
38//! # use zerocopy_derive::*;
39//!
40//! #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
41//! #[repr(C)]
42//! struct UdpHeader {
43//!     src_port: U16,
44//!     dst_port: U16,
45//!     length: U16,
46//!     checksum: U16,
47//! }
48//!
49//! #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
50//! #[repr(C, packed)]
51//! struct UdpPacket {
52//!     header: UdpHeader,
53//!     body: [u8],
54//! }
55//!
56//! impl UdpPacket {
57//!     fn parse(bytes: &[u8]) -> Option<&UdpPacket> {
58//!         UdpPacket::ref_from_bytes(bytes).ok()
59//!     }
60//! }
61//! ```
62
63use core::{
64    convert::{TryFrom, TryInto},
65    fmt::{Binary, Debug, LowerHex, Octal, UpperHex},
66    num::TryFromIntError,
67};
68
69use super::*;
70
71/// A type-level representation of byte order.
72///
73/// This type is implemented by [`BigEndian`] and [`LittleEndian`], which
74/// represent big-endian and little-endian byte order respectively. This module
75/// also provides a number of useful aliases for those types: [`NativeEndian`],
76/// [`NetworkEndian`], [`BE`], and [`LE`].
77///
78/// `ByteOrder` types can be used to specify the byte order of the types in this
79/// module - for example, [`U32<BigEndian>`] is a 32-bit integer stored in
80/// big-endian byte order.
81///
82/// [`U32<BigEndian>`]: U32
83pub trait ByteOrder:
84    Copy + Clone + Debug + Display + Eq + PartialEq + Ord + PartialOrd + private::Sealed
85{
86    #[doc(hidden)]
87    const ORDER: Order;
88}
89
90mod private {
91    pub trait Sealed {}
92
93    impl Sealed for super::BigEndian {}
94    impl Sealed for super::LittleEndian {}
95}
96
97#[allow(missing_copy_implementations, missing_debug_implementations)]
98#[doc(hidden)]
99pub enum Order {
100    BigEndian,
101    LittleEndian,
102}
103
104/// Big-endian byte order.
105///
106/// See [`ByteOrder`] for more details.
107#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
108pub enum BigEndian {}
109
110impl ByteOrder for BigEndian {
111    const ORDER: Order = Order::BigEndian;
112}
113
114impl Display for BigEndian {
115    #[inline]
116    fn fmt(&self, _: &mut Formatter<'_>) -> fmt::Result {
117        match *self {}
118    }
119}
120
121/// Little-endian byte order.
122///
123/// See [`ByteOrder`] for more details.
124#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
125pub enum LittleEndian {}
126
127impl ByteOrder for LittleEndian {
128    const ORDER: Order = Order::LittleEndian;
129}
130
131impl Display for LittleEndian {
132    #[inline]
133    fn fmt(&self, _: &mut Formatter<'_>) -> fmt::Result {
134        match *self {}
135    }
136}
137
138/// The endianness used by this platform.
139///
140/// This is a type alias for [`BigEndian`] or [`LittleEndian`] depending on the
141/// endianness of the target platform.
142#[cfg(target_endian = "big")]
143pub type NativeEndian = BigEndian;
144
145/// The endianness used by this platform.
146///
147/// This is a type alias for [`BigEndian`] or [`LittleEndian`] depending on the
148/// endianness of the target platform.
149#[cfg(target_endian = "little")]
150pub type NativeEndian = LittleEndian;
151
152/// The endianness used in many network protocols.
153///
154/// This is a type alias for [`BigEndian`].
155pub type NetworkEndian = BigEndian;
156
157/// A type alias for [`BigEndian`].
158pub type BE = BigEndian;
159
160/// A type alias for [`LittleEndian`].
161pub type LE = LittleEndian;
162
163macro_rules! impl_fmt_trait {
164    ($name:ident, $native:ident, $trait:ident) => {
165        impl<O: ByteOrder> $trait for $name<O> {
166            #[inline(always)]
167            fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
168                $trait::fmt(&self.get(), f)
169            }
170        }
171    };
172}
173
174macro_rules! impl_fmt_traits {
175    ($name:ident, $native:ident, "floating point number") => {
176        impl_fmt_trait!($name, $native, Display);
177    };
178    ($name:ident, $native:ident, "unsigned integer") => {
179        impl_fmt_traits!($name, $native, @all_types);
180    };
181    ($name:ident, $native:ident, "signed integer") => {
182        impl_fmt_traits!($name, $native, @all_types);
183    };
184    ($name:ident, $native:ident, @all_types) => {
185        impl_fmt_trait!($name, $native, Display);
186        impl_fmt_trait!($name, $native, Octal);
187        impl_fmt_trait!($name, $native, LowerHex);
188        impl_fmt_trait!($name, $native, UpperHex);
189        impl_fmt_trait!($name, $native, Binary);
190    };
191}
192
193macro_rules! impl_ops_traits {
194    ($name:ident, $native:ident, "floating point number") => {
195        impl_ops_traits!($name, $native, @all_types);
196        impl_ops_traits!($name, $native, @signed_integer_floating_point);
197
198        impl<O: ByteOrder> PartialOrd for $name<O> {
199            #[inline(always)]
200            fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
201                self.get().partial_cmp(&other.get())
202            }
203        }
204    };
205    ($name:ident, $native:ident, "unsigned integer") => {
206        impl_ops_traits!($name, $native, @signed_unsigned_integer);
207        impl_ops_traits!($name, $native, @all_types);
208    };
209    ($name:ident, $native:ident, "signed integer") => {
210        impl_ops_traits!($name, $native, @signed_unsigned_integer);
211        impl_ops_traits!($name, $native, @signed_integer_floating_point);
212        impl_ops_traits!($name, $native, @all_types);
213    };
214    ($name:ident, $native:ident, @signed_unsigned_integer) => {
215        impl_ops_traits!(@without_byteorder_swap $name, $native, BitAnd, bitand, BitAndAssign, bitand_assign);
216        impl_ops_traits!(@without_byteorder_swap $name, $native, BitOr, bitor, BitOrAssign, bitor_assign);
217        impl_ops_traits!(@without_byteorder_swap $name, $native, BitXor, bitxor, BitXorAssign, bitxor_assign);
218        impl_ops_traits!(@with_byteorder_swap $name, $native, Shl, shl, ShlAssign, shl_assign);
219        impl_ops_traits!(@with_byteorder_swap $name, $native, Shr, shr, ShrAssign, shr_assign);
220
221        impl<O> core::ops::Not for $name<O> {
222            type Output = $name<O>;
223
224            #[inline(always)]
225            fn not(self) -> $name<O> {
226                 let self_native = $native::from_ne_bytes(self.0);
227                 $name((!self_native).to_ne_bytes(), PhantomData)
228            }
229        }
230
231        impl<O: ByteOrder> PartialOrd for $name<O> {
232            #[inline(always)]
233            fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
234                Some(self.cmp(other))
235            }
236        }
237
238        impl<O: ByteOrder> Ord for $name<O> {
239            #[inline(always)]
240            fn cmp(&self, other: &Self) -> Ordering {
241                self.get().cmp(&other.get())
242            }
243        }
244
245        impl<O: ByteOrder> PartialOrd<$native> for $name<O> {
246            #[inline(always)]
247            fn partial_cmp(&self, other: &$native) -> Option<Ordering> {
248                self.get().partial_cmp(other)
249            }
250        }
251    };
252    ($name:ident, $native:ident, @signed_integer_floating_point) => {
253        impl<O: ByteOrder> core::ops::Neg for $name<O> {
254            type Output = $name<O>;
255
256            #[inline(always)]
257            fn neg(self) -> $name<O> {
258                let self_native: $native = self.get();
259                #[allow(clippy::arithmetic_side_effects)]
260                $name::<O>::new(-self_native)
261            }
262        }
263    };
264    ($name:ident, $native:ident, @all_types) => {
265        impl_ops_traits!(@with_byteorder_swap $name, $native, Add, add, AddAssign, add_assign);
266        impl_ops_traits!(@with_byteorder_swap $name, $native, Div, div, DivAssign, div_assign);
267        impl_ops_traits!(@with_byteorder_swap $name, $native, Mul, mul, MulAssign, mul_assign);
268        impl_ops_traits!(@with_byteorder_swap $name, $native, Rem, rem, RemAssign, rem_assign);
269        impl_ops_traits!(@with_byteorder_swap $name, $native, Sub, sub, SubAssign, sub_assign);
270    };
271    (@with_byteorder_swap $name:ident, $native:ident, $trait:ident, $method:ident, $trait_assign:ident, $method_assign:ident) => {
272        impl<O: ByteOrder> core::ops::$trait<$name<O>> for $name<O> {
273            type Output = $name<O>;
274
275            #[inline(always)]
276            fn $method(self, rhs: $name<O>) -> $name<O> {
277                let self_native: $native = self.get();
278                let rhs_native: $native = rhs.get();
279                let result_native = core::ops::$trait::$method(self_native, rhs_native);
280                $name::<O>::new(result_native)
281            }
282        }
283
284        impl<O: ByteOrder> core::ops::$trait<$name<O>> for $native {
285            type Output = $name<O>;
286
287            #[inline(always)]
288            fn $method(self, rhs: $name<O>) -> $name<O> {
289                let rhs_native: $native = rhs.get();
290                let result_native = core::ops::$trait::$method(self, rhs_native);
291                $name::<O>::new(result_native)
292            }
293        }
294
295        impl<O: ByteOrder> core::ops::$trait<$native> for $name<O> {
296            type Output = $name<O>;
297
298            #[inline(always)]
299            fn $method(self, rhs: $native) -> $name<O> {
300                let self_native: $native = self.get();
301                let result_native = core::ops::$trait::$method(self_native, rhs);
302                $name::<O>::new(result_native)
303            }
304        }
305
306        impl<O: ByteOrder> core::ops::$trait_assign<$name<O>> for $name<O> {
307            #[inline(always)]
308            fn $method_assign(&mut self, rhs: $name<O>) {
309                *self = core::ops::$trait::$method(*self, rhs);
310            }
311        }
312
313        impl<O: ByteOrder> core::ops::$trait_assign<$name<O>> for $native {
314            #[inline(always)]
315            fn $method_assign(&mut self, rhs: $name<O>) {
316                let rhs_native: $native = rhs.get();
317                *self = core::ops::$trait::$method(*self, rhs_native);
318            }
319        }
320
321        impl<O: ByteOrder> core::ops::$trait_assign<$native> for $name<O> {
322            #[inline(always)]
323            fn $method_assign(&mut self, rhs: $native) {
324                *self = core::ops::$trait::$method(*self, rhs);
325            }
326        }
327    };
328    // Implement traits in terms of the same trait on the native type, but
329    // without performing a byte order swap when both operands are byteorder
330    // types. This only works for bitwise operations like `&`, `|`, etc.
331    //
332    // When only one operand is a byteorder type, we still need to perform a
333    // byteorder swap.
334    (@without_byteorder_swap $name:ident, $native:ident, $trait:ident, $method:ident, $trait_assign:ident, $method_assign:ident) => {
335        impl<O: ByteOrder> core::ops::$trait<$name<O>> for $name<O> {
336            type Output = $name<O>;
337
338            #[inline(always)]
339            fn $method(self, rhs: $name<O>) -> $name<O> {
340                let self_native = $native::from_ne_bytes(self.0);
341                let rhs_native = $native::from_ne_bytes(rhs.0);
342                let result_native = core::ops::$trait::$method(self_native, rhs_native);
343                $name(result_native.to_ne_bytes(), PhantomData)
344            }
345        }
346
347        impl<O: ByteOrder> core::ops::$trait<$name<O>> for $native {
348            type Output = $name<O>;
349
350            #[inline(always)]
351            fn $method(self, rhs: $name<O>) -> $name<O> {
352                // No runtime cost - just byte packing
353                let rhs_native = $native::from_ne_bytes(rhs.0);
354                // (Maybe) runtime cost - byte order swap
355                let slf_byteorder = $name::<O>::new(self);
356                // No runtime cost - just byte packing
357                let slf_native = $native::from_ne_bytes(slf_byteorder.0);
358                // Runtime cost - perform the operation
359                let result_native = core::ops::$trait::$method(slf_native, rhs_native);
360                // No runtime cost - just byte unpacking
361                $name(result_native.to_ne_bytes(), PhantomData)
362            }
363        }
364
365        impl<O: ByteOrder> core::ops::$trait<$native> for $name<O> {
366            type Output = $name<O>;
367
368            #[inline(always)]
369            fn $method(self, rhs: $native) -> $name<O> {
370                // (Maybe) runtime cost - byte order swap
371                let rhs_byteorder = $name::<O>::new(rhs);
372                // No runtime cost - just byte packing
373                let rhs_native = $native::from_ne_bytes(rhs_byteorder.0);
374                // No runtime cost - just byte packing
375                let slf_native = $native::from_ne_bytes(self.0);
376                // Runtime cost - perform the operation
377                let result_native = core::ops::$trait::$method(slf_native, rhs_native);
378                // No runtime cost - just byte unpacking
379                $name(result_native.to_ne_bytes(), PhantomData)
380            }
381        }
382
383        impl<O: ByteOrder> core::ops::$trait_assign<$name<O>> for $name<O> {
384            #[inline(always)]
385            fn $method_assign(&mut self, rhs: $name<O>) {
386                *self = core::ops::$trait::$method(*self, rhs);
387            }
388        }
389
390        impl<O: ByteOrder> core::ops::$trait_assign<$name<O>> for $native {
391            #[inline(always)]
392            fn $method_assign(&mut self, rhs: $name<O>) {
393                // (Maybe) runtime cost - byte order swap
394                let rhs_native = rhs.get();
395                // Runtime cost - perform the operation
396                *self = core::ops::$trait::$method(*self, rhs_native);
397            }
398        }
399
400        impl<O: ByteOrder> core::ops::$trait_assign<$native> for $name<O> {
401            #[inline(always)]
402            fn $method_assign(&mut self, rhs: $native) {
403                *self = core::ops::$trait::$method(*self, rhs);
404            }
405        }
406    };
407}
408
409macro_rules! doc_comment {
410    ($x:expr, $($tt:tt)*) => {
411        #[doc = $x]
412        $($tt)*
413    };
414}
415
416macro_rules! define_max_value_constant {
417    ($name:ident, $bytes:expr, "unsigned integer") => {
418        /// The maximum value.
419        ///
420        /// This constant should be preferred to constructing a new value using
421        /// `new`, as `new` may perform an endianness swap depending on the
422        /// endianness `O` and the endianness of the platform.
423        pub const MAX_VALUE: $name<O> = $name([0xFFu8; $bytes], PhantomData);
424    };
425    // We don't provide maximum and minimum value constants for signed values
426    // and floats because there's no way to do it generically - it would require
427    // a different value depending on the value of the `ByteOrder` type
428    // parameter. Currently, one workaround would be to provide implementations
429    // for concrete implementations of that trait. In the long term, if we are
430    // ever able to make the `new` constructor a const fn, we could use that
431    // instead.
432    ($name:ident, $bytes:expr, "signed integer") => {};
433    ($name:ident, $bytes:expr, "floating point number") => {};
434}
435
436macro_rules! define_type {
437    (
438        $article:ident,
439        $description:expr,
440        $name:ident,
441        $native:ident,
442        $bits:expr,
443        $bytes:expr,
444        $from_be_fn:path,
445        $to_be_fn:path,
446        $from_le_fn:path,
447        $to_le_fn:path,
448        $number_kind:tt,
449        [$($larger_native:ty),*],
450        [$($larger_native_try:ty),*],
451        [$($larger_byteorder:ident),*],
452        [$($larger_byteorder_try:ident),*]
453    ) => {
454        doc_comment! {
455            concat!($description, " stored in a given byte order.
456
457`", stringify!($name), "` is like the native `", stringify!($native), "` type with
458two major differences: First, it has no alignment requirement (its alignment is 1).
459Second, the endianness of its memory layout is given by the type parameter `O`,
460which can be any type which implements [`ByteOrder`]. In particular, this refers
461to [`BigEndian`], [`LittleEndian`], [`NativeEndian`], and [`NetworkEndian`].
462
463", stringify!($article), " `", stringify!($name), "` can be constructed using
464the [`new`] method, and its contained value can be obtained as a native
465`",stringify!($native), "` using the [`get`] method, or updated in place with
466the [`set`] method. In all cases, if the endianness `O` is not the same as the
467endianness of the current platform, an endianness swap will be performed in
468order to uphold the invariants that a) the layout of `", stringify!($name), "`
469has endianness `O` and that, b) the layout of `", stringify!($native), "` has
470the platform's native endianness.
471
472`", stringify!($name), "` implements [`FromBytes`], [`IntoBytes`], and [`Unaligned`],
473making it useful for parsing and serialization. See the module documentation for an
474example of how it can be used for parsing UDP packets.
475
476[`new`]: crate::byteorder::", stringify!($name), "::new
477[`get`]: crate::byteorder::", stringify!($name), "::get
478[`set`]: crate::byteorder::", stringify!($name), "::set
479[`FromBytes`]: crate::FromBytes
480[`IntoBytes`]: crate::IntoBytes
481[`Unaligned`]: crate::Unaligned"),
482            #[derive(Copy, Clone, Eq, PartialEq, Hash)]
483            #[cfg_attr(any(feature = "derive", test), derive(KnownLayout, Immutable, FromBytes, IntoBytes, Unaligned))]
484            #[repr(transparent)]
485            pub struct $name<O>([u8; $bytes], PhantomData<O>);
486        }
487
488        #[cfg(not(any(feature = "derive", test)))]
489        impl_known_layout!(O => $name<O>);
490
491        safety_comment! {
492            /// SAFETY:
493            /// `$name<O>` is `repr(transparent)`, and so it has the same layout
494            /// as its only non-zero field, which is a `u8` array. `u8` arrays
495            /// are `Immutable`, `TryFromBytes`, `FromZeros`, `FromBytes`,
496            /// `IntoBytes`, and `Unaligned`.
497            impl_or_verify!(O => Immutable for $name<O>);
498            impl_or_verify!(O => TryFromBytes for $name<O>);
499            impl_or_verify!(O => FromZeros for $name<O>);
500            impl_or_verify!(O => FromBytes for $name<O>);
501            impl_or_verify!(O => IntoBytes for $name<O>);
502            impl_or_verify!(O => Unaligned for $name<O>);
503        }
504
505        impl<O> Default for $name<O> {
506            #[inline(always)]
507            fn default() -> $name<O> {
508                $name::ZERO
509            }
510        }
511
512        impl<O> $name<O> {
513            /// The value zero.
514            ///
515            /// This constant should be preferred to constructing a new value
516            /// using `new`, as `new` may perform an endianness swap depending
517            /// on the endianness and platform.
518            pub const ZERO: $name<O> = $name([0u8; $bytes], PhantomData);
519
520            define_max_value_constant!($name, $bytes, $number_kind);
521
522            /// Constructs a new value from bytes which are already in `O` byte
523            /// order.
524            #[must_use = "has no side effects"]
525            #[inline(always)]
526            pub const fn from_bytes(bytes: [u8; $bytes]) -> $name<O> {
527                $name(bytes, PhantomData)
528            }
529
530            /// Extracts the bytes of `self` without swapping the byte order.
531            ///
532            /// The returned bytes will be in `O` byte order.
533            #[must_use = "has no side effects"]
534            #[inline(always)]
535            pub const fn to_bytes(self) -> [u8; $bytes] {
536                self.0
537            }
538        }
539
540        impl<O: ByteOrder> $name<O> {
541            maybe_const_trait_bounded_fn! {
542                /// Constructs a new value, possibly performing an endianness
543                /// swap to guarantee that the returned value has endianness
544                /// `O`.
545                #[must_use = "has no side effects"]
546                #[inline(always)]
547                pub const fn new(n: $native) -> $name<O> {
548                    let bytes = match O::ORDER {
549                        Order::BigEndian => $to_be_fn(n),
550                        Order::LittleEndian => $to_le_fn(n),
551                    };
552
553                    $name(bytes, PhantomData)
554                }
555            }
556
557            maybe_const_trait_bounded_fn! {
558                /// Returns the value as a primitive type, possibly performing
559                /// an endianness swap to guarantee that the return value has
560                /// the endianness of the native platform.
561                #[must_use = "has no side effects"]
562                #[inline(always)]
563                pub const fn get(self) -> $native {
564                    match O::ORDER {
565                        Order::BigEndian => $from_be_fn(self.0),
566                        Order::LittleEndian => $from_le_fn(self.0),
567                    }
568                }
569            }
570
571            /// Updates the value in place as a primitive type, possibly
572            /// performing an endianness swap to guarantee that the stored value
573            /// has the endianness `O`.
574            #[inline(always)]
575            pub fn set(&mut self, n: $native) {
576                *self = Self::new(n);
577            }
578        }
579
580        // The reasoning behind which traits to implement here is to only
581        // implement traits which won't cause inference issues. Notably,
582        // comparison traits like PartialEq and PartialOrd tend to cause
583        // inference issues.
584
585        impl<O: ByteOrder> From<$name<O>> for [u8; $bytes] {
586            #[inline(always)]
587            fn from(x: $name<O>) -> [u8; $bytes] {
588                x.0
589            }
590        }
591
592        impl<O: ByteOrder> From<[u8; $bytes]> for $name<O> {
593            #[inline(always)]
594            fn from(bytes: [u8; $bytes]) -> $name<O> {
595                $name(bytes, PhantomData)
596            }
597        }
598
599        impl<O: ByteOrder> From<$name<O>> for $native {
600            #[inline(always)]
601            fn from(x: $name<O>) -> $native {
602                x.get()
603            }
604        }
605
606        impl<O: ByteOrder> From<$native> for $name<O> {
607            #[inline(always)]
608            fn from(x: $native) -> $name<O> {
609                $name::new(x)
610            }
611        }
612
613        $(
614            impl<O: ByteOrder> From<$name<O>> for $larger_native {
615                #[inline(always)]
616                fn from(x: $name<O>) -> $larger_native {
617                    x.get().into()
618                }
619            }
620        )*
621
622        $(
623            impl<O: ByteOrder> TryFrom<$larger_native_try> for $name<O> {
624                type Error = TryFromIntError;
625                #[inline(always)]
626                fn try_from(x: $larger_native_try) -> Result<$name<O>, TryFromIntError> {
627                    $native::try_from(x).map($name::new)
628                }
629            }
630        )*
631
632        $(
633            impl<O: ByteOrder, P: ByteOrder> From<$name<O>> for $larger_byteorder<P> {
634                #[inline(always)]
635                fn from(x: $name<O>) -> $larger_byteorder<P> {
636                    $larger_byteorder::new(x.get().into())
637                }
638            }
639        )*
640
641        $(
642            impl<O: ByteOrder, P: ByteOrder> TryFrom<$larger_byteorder_try<P>> for $name<O> {
643                type Error = TryFromIntError;
644                #[inline(always)]
645                fn try_from(x: $larger_byteorder_try<P>) -> Result<$name<O>, TryFromIntError> {
646                    x.get().try_into().map($name::new)
647                }
648            }
649        )*
650
651        impl<O> AsRef<[u8; $bytes]> for $name<O> {
652            #[inline(always)]
653            fn as_ref(&self) -> &[u8; $bytes] {
654                &self.0
655            }
656        }
657
658        impl<O> AsMut<[u8; $bytes]> for $name<O> {
659            #[inline(always)]
660            fn as_mut(&mut self) -> &mut [u8; $bytes] {
661                &mut self.0
662            }
663        }
664
665        impl<O> PartialEq<$name<O>> for [u8; $bytes] {
666            #[inline(always)]
667            fn eq(&self, other: &$name<O>) -> bool {
668                self.eq(&other.0)
669            }
670        }
671
672        impl<O> PartialEq<[u8; $bytes]> for $name<O> {
673            #[inline(always)]
674            fn eq(&self, other: &[u8; $bytes]) -> bool {
675                self.0.eq(other)
676            }
677        }
678
679        impl<O: ByteOrder> PartialEq<$native> for $name<O> {
680            #[inline(always)]
681            fn eq(&self, other: &$native) -> bool {
682                self.get().eq(other)
683            }
684        }
685
686        impl_fmt_traits!($name, $native, $number_kind);
687        impl_ops_traits!($name, $native, $number_kind);
688
689        impl<O: ByteOrder> Debug for $name<O> {
690            #[inline]
691            fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
692                // This results in a format like "U16(42)".
693                f.debug_tuple(stringify!($name)).field(&self.get()).finish()
694            }
695        }
696    };
697}
698
699define_type!(
700    A,
701    "A 16-bit unsigned integer",
702    U16,
703    u16,
704    16,
705    2,
706    u16::from_be_bytes,
707    u16::to_be_bytes,
708    u16::from_le_bytes,
709    u16::to_le_bytes,
710    "unsigned integer",
711    [u32, u64, u128, usize],
712    [u32, u64, u128, usize],
713    [U32, U64, U128, Usize],
714    [U32, U64, U128, Usize]
715);
716define_type!(
717    A,
718    "A 32-bit unsigned integer",
719    U32,
720    u32,
721    32,
722    4,
723    u32::from_be_bytes,
724    u32::to_be_bytes,
725    u32::from_le_bytes,
726    u32::to_le_bytes,
727    "unsigned integer",
728    [u64, u128],
729    [u64, u128],
730    [U64, U128],
731    [U64, U128]
732);
733define_type!(
734    A,
735    "A 64-bit unsigned integer",
736    U64,
737    u64,
738    64,
739    8,
740    u64::from_be_bytes,
741    u64::to_be_bytes,
742    u64::from_le_bytes,
743    u64::to_le_bytes,
744    "unsigned integer",
745    [u128],
746    [u128],
747    [U128],
748    [U128]
749);
750define_type!(
751    A,
752    "A 128-bit unsigned integer",
753    U128,
754    u128,
755    128,
756    16,
757    u128::from_be_bytes,
758    u128::to_be_bytes,
759    u128::from_le_bytes,
760    u128::to_le_bytes,
761    "unsigned integer",
762    [],
763    [],
764    [],
765    []
766);
767define_type!(
768    A,
769    "A word-sized unsigned integer",
770    Usize,
771    usize,
772    mem::size_of::<usize>() * 8,
773    mem::size_of::<usize>(),
774    usize::from_be_bytes,
775    usize::to_be_bytes,
776    usize::from_le_bytes,
777    usize::to_le_bytes,
778    "unsigned integer",
779    [],
780    [],
781    [],
782    []
783);
784define_type!(
785    An,
786    "A 16-bit signed integer",
787    I16,
788    i16,
789    16,
790    2,
791    i16::from_be_bytes,
792    i16::to_be_bytes,
793    i16::from_le_bytes,
794    i16::to_le_bytes,
795    "signed integer",
796    [i32, i64, i128, isize],
797    [i32, i64, i128, isize],
798    [I32, I64, I128, Isize],
799    [I32, I64, I128, Isize]
800);
801define_type!(
802    An,
803    "A 32-bit signed integer",
804    I32,
805    i32,
806    32,
807    4,
808    i32::from_be_bytes,
809    i32::to_be_bytes,
810    i32::from_le_bytes,
811    i32::to_le_bytes,
812    "signed integer",
813    [i64, i128],
814    [i64, i128],
815    [I64, I128],
816    [I64, I128]
817);
818define_type!(
819    An,
820    "A 64-bit signed integer",
821    I64,
822    i64,
823    64,
824    8,
825    i64::from_be_bytes,
826    i64::to_be_bytes,
827    i64::from_le_bytes,
828    i64::to_le_bytes,
829    "signed integer",
830    [i128],
831    [i128],
832    [I128],
833    [I128]
834);
835define_type!(
836    An,
837    "A 128-bit signed integer",
838    I128,
839    i128,
840    128,
841    16,
842    i128::from_be_bytes,
843    i128::to_be_bytes,
844    i128::from_le_bytes,
845    i128::to_le_bytes,
846    "signed integer",
847    [],
848    [],
849    [],
850    []
851);
852define_type!(
853    An,
854    "A word-sized signed integer",
855    Isize,
856    isize,
857    mem::size_of::<isize>() * 8,
858    mem::size_of::<isize>(),
859    isize::from_be_bytes,
860    isize::to_be_bytes,
861    isize::from_le_bytes,
862    isize::to_le_bytes,
863    "signed integer",
864    [],
865    [],
866    [],
867    []
868);
869
870// TODO(https://github.com/rust-lang/rust/issues/72447): Use the endianness
871// conversion methods directly once those are const-stable.
872macro_rules! define_float_conversion {
873    ($ty:ty, $bits:ident, $bytes:expr, $mod:ident) => {
874        mod $mod {
875            use super::*;
876
877            define_float_conversion!($ty, $bits, $bytes, from_be_bytes, to_be_bytes);
878            define_float_conversion!($ty, $bits, $bytes, from_le_bytes, to_le_bytes);
879        }
880    };
881    ($ty:ty, $bits:ident, $bytes:expr, $from:ident, $to:ident) => {
882        // Clippy: The suggestion of using `from_bits()` instead doesn't work
883        // because `from_bits` is not const-stable on our MSRV.
884        #[allow(clippy::transmute_int_to_float)]
885        pub(crate) const fn $from(bytes: [u8; $bytes]) -> $ty {
886            transmute!($bits::$from(bytes))
887        }
888
889        pub(crate) const fn $to(f: $ty) -> [u8; $bytes] {
890            // Clippy: The suggestion of using `f.to_bits()` instead doesn't
891            // work because `to_bits` is not const-stable on our MSRV.
892            #[allow(clippy::transmute_float_to_int)]
893            let bits: $bits = transmute!(f);
894            bits.$to()
895        }
896    };
897}
898
899define_float_conversion!(f32, u32, 4, f32_ext);
900define_float_conversion!(f64, u64, 8, f64_ext);
901
902define_type!(
903    An,
904    "A 32-bit floating point number",
905    F32,
906    f32,
907    32,
908    4,
909    f32_ext::from_be_bytes,
910    f32_ext::to_be_bytes,
911    f32_ext::from_le_bytes,
912    f32_ext::to_le_bytes,
913    "floating point number",
914    [f64],
915    [],
916    [F64],
917    []
918);
919define_type!(
920    An,
921    "A 64-bit floating point number",
922    F64,
923    f64,
924    64,
925    8,
926    f64_ext::from_be_bytes,
927    f64_ext::to_be_bytes,
928    f64_ext::from_le_bytes,
929    f64_ext::to_le_bytes,
930    "floating point number",
931    [],
932    [],
933    [],
934    []
935);
936
937macro_rules! module {
938    ($name:ident, $trait:ident, $endianness_str:expr) => {
939        /// Numeric primitives stored in
940        #[doc = $endianness_str]
941        /// byte order.
942        pub mod $name {
943            use super::$trait;
944
945            module!(@ty U16,  $trait, "16-bit unsigned integer", $endianness_str);
946            module!(@ty U32,  $trait, "32-bit unsigned integer", $endianness_str);
947            module!(@ty U64,  $trait, "64-bit unsigned integer", $endianness_str);
948            module!(@ty U128, $trait, "128-bit unsigned integer", $endianness_str);
949            module!(@ty I16,  $trait, "16-bit signed integer", $endianness_str);
950            module!(@ty I32,  $trait, "32-bit signed integer", $endianness_str);
951            module!(@ty I64,  $trait, "64-bit signed integer", $endianness_str);
952            module!(@ty I128, $trait, "128-bit signed integer", $endianness_str);
953            module!(@ty F32,  $trait, "32-bit floating point number", $endianness_str);
954            module!(@ty F64,  $trait, "64-bit floating point number", $endianness_str);
955        }
956    };
957    (@ty $ty:ident, $trait:ident, $desc_str:expr, $endianness_str:expr) => {
958        /// A
959        #[doc = $desc_str]
960        /// stored in
961        #[doc = $endianness_str]
962        /// byte order.
963        pub type $ty = crate::byteorder::$ty<$trait>;
964    };
965}
966
967module!(big_endian, BigEndian, "big-endian");
968module!(little_endian, LittleEndian, "little-endian");
969module!(network_endian, NetworkEndian, "network-endian");
970module!(native_endian, NativeEndian, "native-endian");
971
972#[cfg(any(test, kani))]
973mod tests {
974    use super::*;
975
976    #[cfg(not(kani))]
977    mod compatibility {
978        pub(super) use rand::{
979            distributions::{Distribution, Standard},
980            rngs::SmallRng,
981            Rng, SeedableRng,
982        };
983
984        pub(crate) trait Arbitrary {}
985
986        impl<T> Arbitrary for T {}
987    }
988
989    #[cfg(kani)]
990    mod compatibility {
991        pub(crate) use kani::Arbitrary;
992
993        pub(crate) struct SmallRng;
994
995        impl SmallRng {
996            pub(crate) fn seed_from_u64(_state: u64) -> Self {
997                Self
998            }
999        }
1000
1001        pub(crate) trait Rng {
1002            fn sample<T, D: Distribution<T>>(&mut self, _distr: D) -> T
1003            where
1004                T: Arbitrary,
1005            {
1006                kani::any()
1007            }
1008        }
1009
1010        impl Rng for SmallRng {}
1011
1012        pub(crate) trait Distribution<T> {}
1013        impl<T, U> Distribution<T> for U {}
1014
1015        pub(crate) struct Standard;
1016    }
1017
1018    use compatibility::*;
1019
1020    // A native integer type (u16, i32, etc).
1021    trait Native: Arbitrary + FromBytes + IntoBytes + Immutable + Copy + PartialEq + Debug {
1022        const ZERO: Self;
1023        const MAX_VALUE: Self;
1024
1025        type Distribution: Distribution<Self>;
1026        const DIST: Self::Distribution;
1027
1028        fn rand<R: Rng>(rng: &mut R) -> Self {
1029            rng.sample(Self::DIST)
1030        }
1031
1032        #[cfg_attr(kani, allow(unused))]
1033        fn checked_add(self, rhs: Self) -> Option<Self>;
1034
1035        #[cfg_attr(kani, allow(unused))]
1036        fn checked_div(self, rhs: Self) -> Option<Self>;
1037
1038        #[cfg_attr(kani, allow(unused))]
1039        fn checked_mul(self, rhs: Self) -> Option<Self>;
1040
1041        #[cfg_attr(kani, allow(unused))]
1042        fn checked_rem(self, rhs: Self) -> Option<Self>;
1043
1044        #[cfg_attr(kani, allow(unused))]
1045        fn checked_sub(self, rhs: Self) -> Option<Self>;
1046
1047        #[cfg_attr(kani, allow(unused))]
1048        fn checked_shl(self, rhs: Self) -> Option<Self>;
1049
1050        #[cfg_attr(kani, allow(unused))]
1051        fn checked_shr(self, rhs: Self) -> Option<Self>;
1052
1053        fn is_nan(self) -> bool;
1054
1055        /// For `f32` and `f64`, NaN values are not considered equal to
1056        /// themselves. This method is like `assert_eq!`, but it treats NaN
1057        /// values as equal.
1058        fn assert_eq_or_nan(self, other: Self) {
1059            let slf = (!self.is_nan()).then(|| self);
1060            let other = (!other.is_nan()).then(|| other);
1061            assert_eq!(slf, other);
1062        }
1063    }
1064
1065    trait ByteArray:
1066        FromBytes + IntoBytes + Immutable + Copy + AsRef<[u8]> + AsMut<[u8]> + Debug + Default + Eq
1067    {
1068        /// Invert the order of the bytes in the array.
1069        fn invert(self) -> Self;
1070    }
1071
1072    trait ByteOrderType:
1073        FromBytes + IntoBytes + Unaligned + Copy + Eq + Debug + From<Self::Native>
1074    {
1075        type Native: Native;
1076        type ByteArray: ByteArray;
1077
1078        const ZERO: Self;
1079
1080        fn new(native: Self::Native) -> Self;
1081        fn get(self) -> Self::Native;
1082        fn set(&mut self, native: Self::Native);
1083        fn from_bytes(bytes: Self::ByteArray) -> Self;
1084        fn into_bytes(self) -> Self::ByteArray;
1085
1086        /// For `f32` and `f64`, NaN values are not considered equal to
1087        /// themselves. This method is like `assert_eq!`, but it treats NaN
1088        /// values as equal.
1089        fn assert_eq_or_nan(self, other: Self) {
1090            let slf = (!self.get().is_nan()).then(|| self);
1091            let other = (!other.get().is_nan()).then(|| other);
1092            assert_eq!(slf, other);
1093        }
1094    }
1095
1096    trait ByteOrderTypeUnsigned: ByteOrderType {
1097        const MAX_VALUE: Self;
1098    }
1099
1100    macro_rules! impl_byte_array {
1101        ($bytes:expr) => {
1102            impl ByteArray for [u8; $bytes] {
1103                fn invert(mut self) -> [u8; $bytes] {
1104                    self.reverse();
1105                    self
1106                }
1107            }
1108        };
1109    }
1110
1111    impl_byte_array!(2);
1112    impl_byte_array!(4);
1113    impl_byte_array!(8);
1114    impl_byte_array!(16);
1115
1116    macro_rules! impl_byte_order_type_unsigned {
1117        ($name:ident, unsigned) => {
1118            impl<O: ByteOrder> ByteOrderTypeUnsigned for $name<O> {
1119                const MAX_VALUE: $name<O> = $name::MAX_VALUE;
1120            }
1121        };
1122        ($name:ident, signed) => {};
1123    }
1124
1125    macro_rules! impl_traits {
1126        ($name:ident, $native:ident, $sign:ident $(, @$float:ident)?) => {
1127            impl Native for $native {
1128                // For some types, `0 as $native` is required (for example, when
1129                // `$native` is a floating-point type; `0` is an integer), but
1130                // for other types, it's a trivial cast. In all cases, Clippy
1131                // thinks it's dangerous.
1132                #[allow(trivial_numeric_casts, clippy::as_conversions)]
1133                const ZERO: $native = 0 as $native;
1134                const MAX_VALUE: $native = $native::MAX;
1135
1136                type Distribution = Standard;
1137                const DIST: Standard = Standard;
1138
1139                impl_traits!(@float_dependent_methods $(@$float)?);
1140            }
1141
1142            impl<O: ByteOrder> ByteOrderType for $name<O> {
1143                type Native = $native;
1144                type ByteArray = [u8; mem::size_of::<$native>()];
1145
1146                const ZERO: $name<O> = $name::ZERO;
1147
1148                fn new(native: $native) -> $name<O> {
1149                    $name::new(native)
1150                }
1151
1152                fn get(self) -> $native {
1153                    $name::get(self)
1154                }
1155
1156                fn set(&mut self, native: $native) {
1157                    $name::set(self, native)
1158                }
1159
1160                fn from_bytes(bytes: [u8; mem::size_of::<$native>()]) -> $name<O> {
1161                    $name::from(bytes)
1162                }
1163
1164                fn into_bytes(self) -> [u8; mem::size_of::<$native>()] {
1165                    <[u8; mem::size_of::<$native>()]>::from(self)
1166                }
1167            }
1168
1169            impl_byte_order_type_unsigned!($name, $sign);
1170        };
1171        (@float_dependent_methods) => {
1172            fn checked_add(self, rhs: Self) -> Option<Self> { self.checked_add(rhs) }
1173            fn checked_div(self, rhs: Self) -> Option<Self> { self.checked_div(rhs) }
1174            fn checked_mul(self, rhs: Self) -> Option<Self> { self.checked_mul(rhs) }
1175            fn checked_rem(self, rhs: Self) -> Option<Self> { self.checked_rem(rhs) }
1176            fn checked_sub(self, rhs: Self) -> Option<Self> { self.checked_sub(rhs) }
1177            fn checked_shl(self, rhs: Self) -> Option<Self> { self.checked_shl(rhs.try_into().unwrap_or(u32::MAX)) }
1178            fn checked_shr(self, rhs: Self) -> Option<Self> { self.checked_shr(rhs.try_into().unwrap_or(u32::MAX)) }
1179            fn is_nan(self) -> bool { false }
1180        };
1181        (@float_dependent_methods @float) => {
1182            fn checked_add(self, rhs: Self) -> Option<Self> { Some(self + rhs) }
1183            fn checked_div(self, rhs: Self) -> Option<Self> { Some(self / rhs) }
1184            fn checked_mul(self, rhs: Self) -> Option<Self> { Some(self * rhs) }
1185            fn checked_rem(self, rhs: Self) -> Option<Self> { Some(self % rhs) }
1186            fn checked_sub(self, rhs: Self) -> Option<Self> { Some(self - rhs) }
1187            fn checked_shl(self, _rhs: Self) -> Option<Self> { unimplemented!() }
1188            fn checked_shr(self, _rhs: Self) -> Option<Self> { unimplemented!() }
1189            fn is_nan(self) -> bool { self.is_nan() }
1190        };
1191    }
1192
1193    impl_traits!(U16, u16, unsigned);
1194    impl_traits!(U32, u32, unsigned);
1195    impl_traits!(U64, u64, unsigned);
1196    impl_traits!(U128, u128, unsigned);
1197    impl_traits!(Usize, usize, unsigned);
1198    impl_traits!(I16, i16, signed);
1199    impl_traits!(I32, i32, signed);
1200    impl_traits!(I64, i64, signed);
1201    impl_traits!(I128, i128, signed);
1202    impl_traits!(Isize, isize, unsigned);
1203    impl_traits!(F32, f32, signed, @float);
1204    impl_traits!(F64, f64, signed, @float);
1205
1206    macro_rules! call_for_unsigned_types {
1207        ($fn:ident, $byteorder:ident) => {
1208            $fn::<U16<$byteorder>>();
1209            $fn::<U32<$byteorder>>();
1210            $fn::<U64<$byteorder>>();
1211            $fn::<U128<$byteorder>>();
1212            $fn::<Usize<$byteorder>>();
1213        };
1214    }
1215
1216    macro_rules! call_for_signed_types {
1217        ($fn:ident, $byteorder:ident) => {
1218            $fn::<I16<$byteorder>>();
1219            $fn::<I32<$byteorder>>();
1220            $fn::<I64<$byteorder>>();
1221            $fn::<I128<$byteorder>>();
1222            $fn::<Isize<$byteorder>>();
1223        };
1224    }
1225
1226    macro_rules! call_for_float_types {
1227        ($fn:ident, $byteorder:ident) => {
1228            $fn::<F32<$byteorder>>();
1229            $fn::<F64<$byteorder>>();
1230        };
1231    }
1232
1233    macro_rules! call_for_all_types {
1234        ($fn:ident, $byteorder:ident) => {
1235            call_for_unsigned_types!($fn, $byteorder);
1236            call_for_signed_types!($fn, $byteorder);
1237            call_for_float_types!($fn, $byteorder);
1238        };
1239    }
1240
1241    #[cfg(target_endian = "big")]
1242    type NonNativeEndian = LittleEndian;
1243    #[cfg(target_endian = "little")]
1244    type NonNativeEndian = BigEndian;
1245
1246    // We use a `u64` seed so that we can use `SeedableRng::seed_from_u64`.
1247    // `SmallRng`'s `SeedableRng::Seed` differs by platform, so if we wanted to
1248    // call `SeedableRng::from_seed`, which takes a `Seed`, we would need
1249    // conditional compilation by `target_pointer_width`.
1250    const RNG_SEED: u64 = 0x7A03CAE2F32B5B8F;
1251
1252    const RAND_ITERS: usize = if cfg!(any(miri, kani)) {
1253        // The tests below which use this constant used to take a very long time
1254        // on Miri, which slows down local development and CI jobs. We're not
1255        // using Miri to check for the correctness of our code, but rather its
1256        // soundness, and at least in the context of these particular tests, a
1257        // single loop iteration is just as good for surfacing UB as multiple
1258        // iterations are.
1259        //
1260        // As of the writing of this comment, here's one set of measurements:
1261        //
1262        //   $ # RAND_ITERS == 1
1263        //   $ cargo miri test -- -Z unstable-options --report-time endian
1264        //   test byteorder::tests::test_native_endian ... ok <0.049s>
1265        //   test byteorder::tests::test_non_native_endian ... ok <0.061s>
1266        //
1267        //   $ # RAND_ITERS == 1024
1268        //   $ cargo miri test -- -Z unstable-options --report-time endian
1269        //   test byteorder::tests::test_native_endian ... ok <25.716s>
1270        //   test byteorder::tests::test_non_native_endian ... ok <38.127s>
1271        1
1272    } else {
1273        1024
1274    };
1275
1276    #[test]
1277    fn test_const_methods() {
1278        use big_endian::*;
1279
1280        #[rustversion::since(1.61.0)]
1281        const _U: U16 = U16::new(0);
1282        #[rustversion::since(1.61.0)]
1283        const _NATIVE: u16 = _U.get();
1284        const _FROM_BYTES: U16 = U16::from_bytes([0, 1]);
1285        const _BYTES: [u8; 2] = _FROM_BYTES.to_bytes();
1286    }
1287
1288    #[cfg_attr(test, test)]
1289    #[cfg_attr(kani, kani::proof)]
1290    fn test_zero() {
1291        fn test_zero<T: ByteOrderType>() {
1292            assert_eq!(T::ZERO.get(), T::Native::ZERO);
1293        }
1294
1295        call_for_all_types!(test_zero, NativeEndian);
1296        call_for_all_types!(test_zero, NonNativeEndian);
1297    }
1298
1299    #[cfg_attr(test, test)]
1300    #[cfg_attr(kani, kani::proof)]
1301    fn test_max_value() {
1302        fn test_max_value<T: ByteOrderTypeUnsigned>() {
1303            assert_eq!(T::MAX_VALUE.get(), T::Native::MAX_VALUE);
1304        }
1305
1306        call_for_unsigned_types!(test_max_value, NativeEndian);
1307        call_for_unsigned_types!(test_max_value, NonNativeEndian);
1308    }
1309
1310    #[cfg_attr(test, test)]
1311    #[cfg_attr(kani, kani::proof)]
1312    fn test_endian() {
1313        fn test<T: ByteOrderType>(invert: bool) {
1314            let mut r = SmallRng::seed_from_u64(RNG_SEED);
1315            for _ in 0..RAND_ITERS {
1316                let native = T::Native::rand(&mut r);
1317                let mut bytes = T::ByteArray::default();
1318                bytes.as_mut_bytes().copy_from_slice(native.as_bytes());
1319                if invert {
1320                    bytes = bytes.invert();
1321                }
1322                let mut from_native = T::new(native);
1323                let from_bytes = T::from_bytes(bytes);
1324
1325                from_native.assert_eq_or_nan(from_bytes);
1326                from_native.get().assert_eq_or_nan(native);
1327                from_bytes.get().assert_eq_or_nan(native);
1328
1329                assert_eq!(from_native.into_bytes(), bytes);
1330                assert_eq!(from_bytes.into_bytes(), bytes);
1331
1332                let updated = T::Native::rand(&mut r);
1333                from_native.set(updated);
1334                from_native.get().assert_eq_or_nan(updated);
1335            }
1336        }
1337
1338        fn test_native<T: ByteOrderType>() {
1339            test::<T>(false);
1340        }
1341
1342        fn test_non_native<T: ByteOrderType>() {
1343            test::<T>(true);
1344        }
1345
1346        call_for_all_types!(test_native, NativeEndian);
1347        call_for_all_types!(test_non_native, NonNativeEndian);
1348    }
1349
1350    #[test]
1351    fn test_ops_impls() {
1352        // Test implementations of traits in `core::ops`. Some of these are
1353        // fairly banal, but some are optimized to perform the operation without
1354        // swapping byte order (namely, bit-wise operations which are identical
1355        // regardless of byte order). These are important to test, and while
1356        // we're testing those anyway, it's trivial to test all of the impls.
1357
1358        fn test<T, FTT, FTN, FNT, FNN, FNNChecked, FATT, FATN, FANT>(
1359            op_t_t: FTT,
1360            op_t_n: FTN,
1361            op_n_t: FNT,
1362            op_n_n: FNN,
1363            op_n_n_checked: Option<FNNChecked>,
1364            op_assign: Option<(FATT, FATN, FANT)>,
1365        ) where
1366            T: ByteOrderType,
1367            FTT: Fn(T, T) -> T,
1368            FTN: Fn(T, T::Native) -> T,
1369            FNT: Fn(T::Native, T) -> T,
1370            FNN: Fn(T::Native, T::Native) -> T::Native,
1371            FNNChecked: Fn(T::Native, T::Native) -> Option<T::Native>,
1372
1373            FATT: Fn(&mut T, T),
1374            FATN: Fn(&mut T, T::Native),
1375            FANT: Fn(&mut T::Native, T),
1376        {
1377            let mut r = SmallRng::seed_from_u64(RNG_SEED);
1378            for _ in 0..RAND_ITERS {
1379                let n0 = T::Native::rand(&mut r);
1380                let n1 = T::Native::rand(&mut r);
1381                let t0 = T::new(n0);
1382                let t1 = T::new(n1);
1383
1384                // If this operation would overflow/underflow, skip it rather
1385                // than attempt to catch and recover from panics.
1386                if matches!(&op_n_n_checked, Some(checked) if checked(n0, n1).is_none()) {
1387                    continue;
1388                }
1389
1390                let t_t_res = op_t_t(t0, t1);
1391                let t_n_res = op_t_n(t0, n1);
1392                let n_t_res = op_n_t(n0, t1);
1393                let n_n_res = op_n_n(n0, n1);
1394
1395                // For `f32` and `f64`, NaN values are not considered equal to
1396                // themselves. We store `Option<f32>`/`Option<f64>` and store
1397                // NaN as `None` so they can still be compared.
1398                let val_or_none = |t: T| (!T::Native::is_nan(t.get())).then(|| t.get());
1399                let t_t_res = val_or_none(t_t_res);
1400                let t_n_res = val_or_none(t_n_res);
1401                let n_t_res = val_or_none(n_t_res);
1402                let n_n_res = (!T::Native::is_nan(n_n_res)).then(|| n_n_res);
1403                assert_eq!(t_t_res, n_n_res);
1404                assert_eq!(t_n_res, n_n_res);
1405                assert_eq!(n_t_res, n_n_res);
1406
1407                if let Some((op_assign_t_t, op_assign_t_n, op_assign_n_t)) = &op_assign {
1408                    let mut t_t_res = t0;
1409                    op_assign_t_t(&mut t_t_res, t1);
1410                    let mut t_n_res = t0;
1411                    op_assign_t_n(&mut t_n_res, n1);
1412                    let mut n_t_res = n0;
1413                    op_assign_n_t(&mut n_t_res, t1);
1414
1415                    // For `f32` and `f64`, NaN values are not considered equal to
1416                    // themselves. We store `Option<f32>`/`Option<f64>` and store
1417                    // NaN as `None` so they can still be compared.
1418                    let t_t_res = val_or_none(t_t_res);
1419                    let t_n_res = val_or_none(t_n_res);
1420                    let n_t_res = (!T::Native::is_nan(n_t_res)).then(|| n_t_res);
1421                    assert_eq!(t_t_res, n_n_res);
1422                    assert_eq!(t_n_res, n_n_res);
1423                    assert_eq!(n_t_res, n_n_res);
1424                }
1425            }
1426        }
1427
1428        macro_rules! test {
1429            (
1430                @binary
1431                $trait:ident,
1432                $method:ident $([$checked_method:ident])?,
1433                $trait_assign:ident,
1434                $method_assign:ident,
1435                $($call_for_macros:ident),*
1436            ) => {{
1437                fn t<T>()
1438                where
1439                    T: ByteOrderType,
1440                    T: core::ops::$trait<T, Output = T>,
1441                    T: core::ops::$trait<T::Native, Output = T>,
1442                    T::Native: core::ops::$trait<T, Output = T>,
1443                    T::Native: core::ops::$trait<T::Native, Output = T::Native>,
1444
1445                    T: core::ops::$trait_assign<T>,
1446                    T: core::ops::$trait_assign<T::Native>,
1447                    T::Native: core::ops::$trait_assign<T>,
1448                    T::Native: core::ops::$trait_assign<T::Native>,
1449                {
1450                    test::<T, _, _, _, _, _, _, _, _>(
1451                        core::ops::$trait::$method,
1452                        core::ops::$trait::$method,
1453                        core::ops::$trait::$method,
1454                        core::ops::$trait::$method,
1455                        {
1456                            #[allow(unused_mut, unused_assignments)]
1457                            let mut op_native_checked = None::<fn(T::Native, T::Native) -> Option<T::Native>>;
1458                            $(
1459                                op_native_checked = Some(T::Native::$checked_method);
1460                            )?
1461                            op_native_checked
1462                        },
1463                        Some((
1464                            <T as core::ops::$trait_assign<T>>::$method_assign,
1465                            <T as core::ops::$trait_assign::<T::Native>>::$method_assign,
1466                            <T::Native as core::ops::$trait_assign::<T>>::$method_assign
1467                        )),
1468                    );
1469                }
1470
1471                $(
1472                    $call_for_macros!(t, NativeEndian);
1473                    $call_for_macros!(t, NonNativeEndian);
1474                )*
1475            }};
1476            (
1477                @unary
1478                $trait:ident,
1479                $method:ident,
1480                $($call_for_macros:ident),*
1481            ) => {{
1482                fn t<T>()
1483                where
1484                    T: ByteOrderType,
1485                    T: core::ops::$trait<Output = T>,
1486                    T::Native: core::ops::$trait<Output = T::Native>,
1487                {
1488                    test::<T, _, _, _, _, _, _, _, _>(
1489                        |slf, _rhs| core::ops::$trait::$method(slf),
1490                        |slf, _rhs| core::ops::$trait::$method(slf),
1491                        |slf, _rhs| core::ops::$trait::$method(slf).into(),
1492                        |slf, _rhs| core::ops::$trait::$method(slf),
1493                        None::<fn(T::Native, T::Native) -> Option<T::Native>>,
1494                        None::<(fn(&mut T, T), fn(&mut T, T::Native), fn(&mut T::Native, T))>,
1495                    );
1496                }
1497
1498                $(
1499                    $call_for_macros!(t, NativeEndian);
1500                    $call_for_macros!(t, NonNativeEndian);
1501                )*
1502            }};
1503        }
1504
1505        test!(@binary Add, add[checked_add], AddAssign, add_assign, call_for_all_types);
1506        test!(@binary Div, div[checked_div], DivAssign, div_assign, call_for_all_types);
1507        test!(@binary Mul, mul[checked_mul], MulAssign, mul_assign, call_for_all_types);
1508        test!(@binary Rem, rem[checked_rem], RemAssign, rem_assign, call_for_all_types);
1509        test!(@binary Sub, sub[checked_sub], SubAssign, sub_assign, call_for_all_types);
1510
1511        test!(@binary BitAnd, bitand, BitAndAssign, bitand_assign, call_for_unsigned_types, call_for_signed_types);
1512        test!(@binary BitOr, bitor, BitOrAssign, bitor_assign, call_for_unsigned_types, call_for_signed_types);
1513        test!(@binary BitXor, bitxor, BitXorAssign, bitxor_assign, call_for_unsigned_types, call_for_signed_types);
1514        test!(@binary Shl, shl[checked_shl], ShlAssign, shl_assign, call_for_unsigned_types, call_for_signed_types);
1515        test!(@binary Shr, shr[checked_shr], ShrAssign, shr_assign, call_for_unsigned_types, call_for_signed_types);
1516
1517        test!(@unary Not, not, call_for_signed_types, call_for_unsigned_types);
1518        test!(@unary Neg, neg, call_for_signed_types, call_for_float_types);
1519    }
1520
1521    #[test]
1522    fn test_debug_impl() {
1523        // Ensure that Debug applies format options to the inner value.
1524        let val = U16::<LE>::new(10);
1525        assert_eq!(format!("{:?}", val), "U16(10)");
1526        assert_eq!(format!("{:03?}", val), "U16(010)");
1527        assert_eq!(format!("{:x?}", val), "U16(a)");
1528    }
1529}
zerocopy/byteorder.rs

zerocopy/
byteorder.rs
