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

zerocopy/
byteorder.rs
