projects/linux·blob master · refs

1596 lines · 54.5 KiB

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