wrapper_lite/
lib.rs

1#![doc = include_str!("../README.md")]
2#![no_std]
3
4#[macro_export]
5/// Helper macro for creating a wrapper over any type (new-type idiom).
6///
7/// This is a shortcut for using the [`wrapper!`] macro with the most common
8/// impls (`AsRef`, `Borrow`, `From`).
9///
10/// ```rust
11/// wrapper_lite::general_wrapper!(
12///     #[derive(Debug, Clone, Copy)]
13///     pub struct ExampleWrapper<'a, P>(pub(crate) &'a P);
14/// );
15/// ```
16///
17/// This is equivalent to using the `wrapper!` macro with the following
18/// attributes:
19///
20/// ```rust
21/// wrapper_lite::wrapper!(
22///     #[wrapper_impl(AsRef)]
23///     #[wrapper_impl(Borrow)]
24///     #[wrapper_impl(From)]
25///     #[derive(Debug, Clone, Copy)]
26///     pub struct ExampleWrapper<'a, P>(pub(crate) &'a P);
27/// );
28/// ```
29///
30/// You can certainly add attributes like `#[wrapper_impl(Deref)]` other than
31/// the preset ones. See [`wrapper!`] for more details.
32///
33/// ```rust
34/// wrapper_lite::general_wrapper!(
35///     #[wrapper_impl(Deref)]
36///     #[derive(Debug, Clone, Copy)]
37///     pub struct ExampleWrapper<'a, P>(pub(crate) &'a P);
38/// );
39/// ```
40macro_rules! general_wrapper {
41    ($($tt:tt)+) => {
42        $crate::wrapper! {
43            #[wrapper_impl(AsRef)]
44            #[wrapper_impl(Borrow)]
45            #[wrapper_impl(From)]
46            $($tt)+
47        }
48    };
49}
50
51#[macro_export]
52#[doc(hidden)]
53macro_rules! aligned {
54    ($($tt:tt)*) => {
55        // Starting from Intel's Sandy Bridge, spatial prefetcher is now pulling pairs of 64-byte cache
56        // lines at a time, so we have to align to 128 bytes rather than 64.
57        //
58        // Sources:
59        // - https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-optimization-manual.pdf
60        // - https://github.com/facebook/folly/blob/1b5288e6eea6df074758f877c849b6e73bbb9fbb/folly/lang/Align.h#L107
61        //
62        // aarch64/arm64ec's big.LITTLE architecture has asymmetric cores and "big" cores have 128-byte cache line size.
63        //
64        // Sources:
65        // - https://www.mono-project.com/news/2016/09/12/arm64-icache/
66        //
67        // powerpc64 has 128-byte cache line size.
68        //
69        // Sources:
70        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_ppc64x.go#L9
71        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/powerpc/include/asm/cache.h#L26
72        #[cfg_attr(
73            any(
74                target_arch = "x86_64",
75                target_arch = "aarch64",
76                target_arch = "arm64ec",
77                target_arch = "powerpc64",
78            ),
79            repr(align(128))
80        )]
81        // arm, mips, mips64, sparc, and hexagon have 32-byte cache line size.
82        //
83        // Sources:
84        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_arm.go#L7
85        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips.go#L7
86        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mipsle.go#L7
87        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips64x.go#L9
88        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/sparc/include/asm/cache.h#L17
89        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/hexagon/include/asm/cache.h#L12
90        #[cfg_attr(
91            any(
92                target_arch = "arm",
93                target_arch = "mips",
94                target_arch = "mips32r6",
95                target_arch = "mips64",
96                target_arch = "mips64r6",
97                target_arch = "sparc",
98                target_arch = "hexagon",
99            ),
100            repr(align(32))
101        )]
102        // m68k has 16-byte cache line size.
103        //
104        // Sources:
105        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/m68k/include/asm/cache.h#L9
106        #[cfg_attr(target_arch = "m68k", repr(align(16)))]
107        // s390x has 256-byte cache line size.
108        //
109        // Sources:
110        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_s390x.go#L7
111        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/s390/include/asm/cache.h#L13
112        #[cfg_attr(target_arch = "s390x", repr(align(256)))]
113        // x86, wasm, riscv, and sparc64 have 64-byte cache line size.
114        //
115        // Sources:
116        // - https://github.com/golang/go/blob/dda2991c2ea0c5914714469c4defc2562a907230/src/internal/cpu/cpu_x86.go#L9
117        // - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_wasm.go#L7
118        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/riscv/include/asm/cache.h#L10
119        // - https://github.com/torvalds/linux/blob/3516bd729358a2a9b090c1905bd2a3fa926e24c6/arch/sparc/include/asm/cache.h#L19
120        //
121        // All others are assumed to have 64-byte cache line size.
122        #[cfg_attr(
123            not(any(
124                target_arch = "x86_64",
125                target_arch = "aarch64",
126                target_arch = "arm64ec",
127                target_arch = "powerpc64",
128                target_arch = "arm",
129                target_arch = "mips",
130                target_arch = "mips32r6",
131                target_arch = "mips64",
132                target_arch = "mips64r6",
133                target_arch = "sparc",
134                target_arch = "hexagon",
135                target_arch = "m68k",
136                target_arch = "s390x",
137            )),
138            repr(align(64))
139        )]
140        $($tt)*
141    }
142}
143
144#[macro_export]
145/// Helper macro for creating a wrapper over any type (new-type idiom).
146///
147/// # Usage
148///
149/// It's worth noting that `wrapper! { ... }` is almost equivalent to
150/// `wrapper!( ... );` but lacking `cargo-fmt` support. We recommend using the
151/// latter.
152///
153/// ## Usage: basic
154///
155/// ```rust
156/// wrapper_lite::wrapper!(
157///     #[wrapper_impl(AsRef)]
158///     #[wrapper_impl(AsMut)]
159///     // #[wrapper_impl(Borrow)]
160///     #[wrapper_impl(BorrowMut)]
161///     // #[wrapper_impl(Deref)]
162///     #[wrapper_impl(DerefMut)]
163///     #[wrapper_impl(From)]
164///     #[derive(Debug, Clone, Copy)]
165///     pub struct ExampleWrapper<'a, P>(pub(crate) &'a P);
166/// );
167/// ```
168///
169/// Generates const accessor methods for wrapper types implementing `AsRef` and
170/// `AsMut` traits. For types implementing `AsRef`, this creates a const method
171/// `as_inner` that returns a reference to the wrapped value. For types
172/// implementing `AsMut`, this creates a (const) method `as_inner_mut` that
173/// returns a mutable reference to the wrapped value, sharing the same
174/// visibility as the inner field.
175///
176/// Additionally generates a const constructor method `from_inner` for the
177/// wrapper type when possible, also sharing the same visibility as the inner
178/// field. When the `From` trait is implemented, also generates a public const
179/// method `from`.
180///
181/// ## Usage: advanced
182///
183/// You can also create a wrapper type with a struct with multiple fields,
184/// especially when some lifetime markers or generics markers are too complex,
185/// or you need some custom fields.
186///
187/// Here's an complex example:
188///
189/// ```rust
190/// use core::fmt::Debug;
191/// use core::marker::PhantomData;
192///
193/// wrapper_lite::wrapper!(
194///     #[wrapper_impl(AsMut)]
195///     #[wrapper_impl(AsRef)]
196///     // #[wrapper_impl(Borrow)]
197///     #[wrapper_impl(BorrowMut)]
198///     // #[wrapper_impl(Deref)]
199///     #[wrapper_impl(DerefMut)]
200///     // #[wrapper_impl(From)]
201///     #[wrapper_impl(Debug)]
202///     #[derive(Clone, Copy, PartialEq, Eq)]
203///     #[repr(transparent)]
204///     pub struct ExampleWrapperComplex<'a, 'b: 'a, P: Debug = String> {
205///         inner: P,
206///         _a: PhantomData<&'a ()>,
207///         _b: PhantomData<&'b ()>,
208///     }
209/// );
210/// ```
211///
212/// There're some known limitations:
213///
214/// - The inner field must be the first one declared in the struct (the name
215///   does not matter)
216/// - When there's no default value specified, we cannot implement the `From`
217///   trait for the wrapper type. You may specify a default value like this:
218///
219///   ```rust
220///   wrapper_lite::wrapper!(
221///       #[wrapper_impl(From)]
222///       pub struct ExampleWrapperComplexWithDefault<P> {
223///           inner: P,
224///          _marker: u8 = 0,
225///       }
226///   );
227///   ```
228///
229///   However, the non-Rust syntax will make `cargo-fmt` upset, and you can just
230///   implement the `From` trait by yourself.
231/// - For trait bounds on generics parameters, you have to import the traits and
232///   cannot specify a path (e.g., `T: ::core::fmt::Debug`) due to the
233///   limitation of procedural macros.
234/// - `where` clauses are not supported yet.
235///
236/// ## Special usages
237///
238/// ### `Debug` and `DebugName`
239///
240/// We offer `Debug` and `DebugName` attributes to control how the wrapper type
241/// is printed when using the `Debug` trait, instead of `#[derive(Debug)]`.
242///
243/// - `#[wrapper_impl(Debug)]`: transparently implements the `Debug` trait if
244///   the inner type implements it. The debug output is the same as the inner
245///   one.
246/// - `#[wrapper_impl(DebugName)]`: implements the `Debug` trait, but only
247///   prints the name of the wrapper type.
248///
249/// ```rust
250/// wrapper_lite::wrapper!(
251///     #[wrapper_impl(Debug)]
252///     #[derive(Clone, Copy)]
253///     pub struct ExampleWrapperDebug<'a, P>(&'a P);
254/// );
255///
256/// wrapper_lite::wrapper!(
257///     #[wrapper_impl(DebugName)]
258///     #[derive(Clone, Copy)]
259///     pub struct ExampleWrapperDebugName<'a, P>(&'a P);
260/// );
261///
262/// let data = "Hello".to_string();
263///
264/// // Here we transparently print the debug output of the inner type.
265/// assert_eq!(
266///     format!("{:?}", ExampleWrapperDebug { inner: &data }),
267///     "\"Hello\""
268/// );
269/// // Here we only print the name of the wrapper type.
270/// assert_eq!(
271///     format!("{:?}", ExampleWrapperDebugName { inner: &data }),
272///     "ExampleWrapperDebugName"
273/// );
274/// ```
275///
276/// ### `Display`
277///
278/// Like `Debug`.
279///
280/// ```rust
281/// wrapper_lite::wrapper!(
282///     #[wrapper_impl(Display)]
283///     #[derive(Clone, Copy)]
284///     pub struct ExampleWrapperDisplay<'a, P>(&'a P);
285/// );
286///
287/// let data = "Hello".to_string();
288///
289/// // Here we transparently print the debug output of the inner type.
290/// assert_eq!(
291///     format!("{}", ExampleWrapperDisplay { inner: &data }),
292///     "Hello"
293/// );
294/// ```
295///
296/// ### `ConstAsMut`
297///
298/// Like `AsMut`, but instead generates a const version of `as_inner_mut` method
299/// (stable since Rust 1.83.0+).
300///
301/// ```rust,no_run
302/// wrapper_lite::wrapper!(
303///     #[wrapper_impl(ConstAsMut)]
304///     #[derive(Debug, Clone, Copy)]
305///     pub struct ExampleWrapper<P>(pub(crate) P);
306/// );
307///
308/// const fn const_fn_example<P>(w: &mut ExampleWrapper<P>) -> &mut P {
309///     w.as_inner_mut()
310/// }
311/// ```
312///
313/// ### `AsRef<T>`, `AsMut<T>`, `Borrow<T>`, `BorrowMut<T>`, `Deref<T>`, `DerefMut<T>`
314///
315/// These attributes allow you to specify a target type `T` for the respective
316/// traits (experimental). This is done by auto-dereferencing the inner type to
317/// get a reference to `T`.
318///
319/// ```rust
320/// wrapper_lite::wrapper!(
321///     #[wrapper_impl(AsRef<[u8]>)]
322///     #[wrapper_impl(AsMut<[u8]>)]
323///     // #[wrapper_impl(Borrow<[u8]>)]
324///     #[wrapper_impl(BorrowMut<[u8]>)]
325///     // #[wrapper_impl(Deref<[u8]>)]
326///     #[wrapper_impl(DerefMut<[u8]>)]
327///     pub struct ExampleWrapper(pub(crate) Vec<u8>);
328/// );
329/// ```
330///
331/// ### `repr(align(cache))`
332///
333/// You can use `#[repr(align(cache))]` to pad and align the wrapper type to the
334/// cache line size. This is useful for performance optimization in certain
335/// scenarios.
336///
337/// ```
338/// wrapper_lite::wrapper!(
339///     #[wrapper_impl(From)]
340///     #[repr(align(cache))]
341///     /// Example doc
342///     pub struct ExampleWrapperCachePadded(u64);
343/// );
344/// #[cfg(target_arch = "x86_64")]
345/// assert_eq!(core::mem::align_of::<ExampleWrapperCachePadded>(), 128);
346/// ```
347///
348/// Credits: <https://docs.rs/crossbeam/latest/crossbeam/utils/struct.CachePadded.html>.
349///
350/// Notes that `repr(align(cache))` must be placed after other
351/// `#[wrapper_impl(...)]` attributes and before any other attributes, including
352/// docs.
353///
354/// ## Notes
355///
356/// - The `wrapper_impl` attribute must be on top of any other attributes.
357/// - For `BorrowMut` and `DerefMut`, the macro will automatically implement the
358///   corresponding `Borrow` and `Deref` traits, so the following two examples
359///   will fail to compile:
360///
361///   ```rust,compile_fail
362///   wrapper_lite::wrapper!(
363///       #[wrapper_impl(Borrow)]
364///       #[wrapper_impl(BorrowMut)]
365///       pub struct ExampleWrapper<P>(pub(crate) P);
366///   );
367///   ```
368///
369///   ```rust,compile_fail
370///   wrapper_lite::wrapper!(
371///       #[wrapper_impl(Deref)]
372///       #[wrapper_impl(DerefMut)]
373///       pub struct ExampleWrapper<P>(pub(crate) P);
374///   );
375///   ```
376macro_rules! wrapper {
377    // To filter out the `wrapper_impl` attribute and extract the inner type.
378    (
379        @INTERNAL IMPL
380        #[wrapper_impl(AsRef $(<$target:ty>)? )]
381        $($tt:tt)*
382    ) => {
383        $crate::wrapper! {
384            @INTERNAL IMPL
385            $($tt)*
386        }
387    };
388    (
389        @INTERNAL IMPL
390        #[wrapper_impl(AsMut $(<$target:ty>)? )]
391        $($tt:tt)*
392    ) => {
393        $crate::wrapper! {
394            @INTERNAL IMPL
395            $($tt)*
396        }
397    };
398    (
399        @INTERNAL IMPL
400        #[wrapper_impl(ConstAsMut $(<$target:ty>)? )]
401        $($tt:tt)*
402    ) => {
403        $crate::wrapper! {
404            @INTERNAL IMPL
405            $($tt)*
406        }
407    };
408    (
409        @INTERNAL IMPL
410        #[wrapper_impl(Borrow $(<$target:ty>)? )]
411        $($tt:tt)*
412    ) => {
413        $crate::wrapper! {
414            @INTERNAL IMPL
415            $($tt)*
416        }
417    };
418    (
419        @INTERNAL IMPL
420        #[wrapper_impl(BorrowMut $(<$target:ty>)? )]
421        $($tt:tt)*
422    ) => {
423        $crate::wrapper! {
424            @INTERNAL IMPL
425            $($tt)*
426        }
427    };
428    (
429        @INTERNAL IMPL
430        #[wrapper_impl(Deref $(<$target:ty>)? )]
431        $($tt:tt)*
432    ) => {
433        $crate::wrapper! {
434            @INTERNAL IMPL
435            $($tt)*
436        }
437    };
438    (
439        @INTERNAL IMPL
440        #[wrapper_impl(DerefMut $(<$target:ty>)? )]
441        $($tt:tt)*
442    ) => {
443        $crate::wrapper! {
444            @INTERNAL IMPL
445            $($tt)*
446        }
447    };
448    (
449        @INTERNAL IMPL
450        #[wrapper_impl(From)]
451        $($tt:tt)*
452    ) => {
453        $crate::wrapper! {
454            @INTERNAL IMPL
455            $($tt)*
456        }
457    };
458    (
459        @INTERNAL IMPL
460        #[wrapper_impl(Debug)]
461        $($tt:tt)*
462    ) => {
463        $crate::wrapper! {
464            @INTERNAL IMPL
465            $($tt)*
466        }
467    };
468    (
469        @INTERNAL IMPL
470        #[wrapper_impl(DebugName)]
471        $($tt:tt)*
472    ) => {
473        $crate::wrapper! {
474            @INTERNAL IMPL
475            $($tt)*
476        }
477    };
478    (
479        @INTERNAL IMPL
480        #[wrapper_impl(Display)]
481        $($tt:tt)*
482    ) => {
483        $crate::wrapper! {
484            @INTERNAL IMPL
485            $($tt)*
486        }
487    };
488
489    // The actual implementation of the wrapper type: `pub Name<...>(...)`
490    (
491        @INTERNAL IMPL
492        #[repr(align(cache))]
493        $(#[$outer:meta])*
494        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
495    ) => {
496        $crate::aligned! {
497            $(#[$outer])*
498            $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
499                /// Inner value
500                $inner_vis inner: $inner_ty,
501            }
502        }
503
504        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
505            #[inline(always)]
506            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
507            $inner_vis const fn from_inner(inner: $inner_ty) -> Self {
508                Self {
509                    inner,
510                }
511            }
512        }
513    };
514
515    (
516        @INTERNAL IMPL
517        $(#[$outer:meta])*
518        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
519    ) => {
520        $(#[$outer])*
521        $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
522            /// Inner value
523            $inner_vis inner: $inner_ty,
524        }
525
526        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
527            #[inline(always)]
528            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
529            $inner_vis const fn from_inner(inner: $inner_ty) -> Self {
530                Self {
531                    inner,
532                }
533            }
534        }
535    };
536
537    // The actual implementation of the wrapper type: `pub struct Name<...> { ... }`
538    // with field initial value provided, make `from_inner` const.
539    (
540        @INTERNAL IMPL
541        #[repr(align(cache))]
542        $(#[$outer:meta])*
543        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
544            $(#[$field_inner_meta:meta])*
545            $inner_vis:vis $inner:ident: $inner_ty:ty
546            $(
547                ,
548                $(#[$field_meta:meta])*
549                $field_vis:vis $field:ident: $field_ty:ty = $field_default: expr
550            )*
551            $(,)?
552        }
553    ) => {
554        $crate::aligned! {
555            $(#[$outer])*
556            $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
557                $(#[$field_inner_meta])*
558                $inner_vis $inner: $inner_ty,
559                $(
560                    $(#[$field_meta])*
561                    $field_vis $field: $field_ty
562                ),*
563            }
564        }
565
566        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
567            #[inline(always)]
568            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
569            $inner_vis const fn from_inner($inner: $inner_ty) -> Self {
570                Self {
571                    $inner,
572                    $(
573                        $field: $field_default,
574                    )*
575                }
576            }
577        }
578    };
579
580    (
581        @INTERNAL IMPL
582        $(#[$outer:meta])*
583        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
584            $(#[$field_inner_meta:meta])*
585            $inner_vis:vis $inner:ident: $inner_ty:ty
586            $(
587                ,
588                $(#[$field_meta:meta])*
589                $field_vis:vis $field:ident: $field_ty:ty = $field_default: expr
590            )*
591            $(,)?
592        }
593    ) => {
594        $(#[$outer])*
595        $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
596            $(#[$field_inner_meta])*
597            $inner_vis $inner: $inner_ty,
598            $(
599                $(#[$field_meta])*
600                $field_vis $field: $field_ty
601            ),*
602        }
603
604        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
605            #[inline(always)]
606            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
607            $inner_vis const fn from_inner($inner: $inner_ty) -> Self {
608                Self {
609                    $inner,
610                    $(
611                        $field: $field_default,
612                    )*
613                }
614            }
615        }
616    };
617
618    // The actual implementation of the wrapper type with fields: `pub struct Name<...> { ... }`
619    (
620        @INTERNAL IMPL
621        #[repr(align(cache))]
622        $(#[$outer:meta])*
623        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
624            $(#[$field_inner_meta:meta])*
625            $inner_vis:vis $inner:ident: $inner_ty:ty
626            $(
627                ,
628                $(#[$field_meta:meta])*
629                $field_vis:vis $field:ident: $field_ty:ty
630            )*
631            $(,)?
632        }
633    ) => {
634        $crate::aligned! {
635            $(#[$outer])*
636            $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
637                $(#[$field_inner_meta])*
638                $inner_vis $inner: $inner_ty
639                $(
640                    ,
641                    $(#[$field_meta])*
642                    $field_vis $field: $field_ty
643                )*
644            }
645        }
646    };
647
648    (
649        @INTERNAL IMPL
650        $(#[$outer:meta])*
651        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
652            $(#[$field_inner_meta:meta])*
653            $inner_vis:vis $inner:ident: $inner_ty:ty
654            $(
655                ,
656                $(#[$field_meta:meta])*
657                $field_vis:vis $field:ident: $field_ty:ty
658            )*
659            $(,)?
660        }
661    ) => {
662        $(#[$outer])*
663        $vis struct $name$(<$($lt$(:$clt$(+$dlt)*)?$(=$default)?),+>)? {
664            $(#[$field_inner_meta])*
665            $inner_vis $inner: $inner_ty
666            $(
667                ,
668                $(#[$field_meta])*
669                $field_vis $field: $field_ty
670            )*
671        }
672    };
673
674    // === Process all `wrapper_impl` attributes, and generate impls. ===
675
676    // Extract wrapper impl for `AsRef` trait.
677    (
678        @INTERNAL WRAPPER_IMPL
679        #[wrapper_impl(AsRef $(<$target:ty>)? )]
680        $($tt:tt)*
681    ) => {
682        $crate::wrapper! {
683            @INTERNAL WRAPPER_IMPL_AS_REF $(<$target>)?
684            $($tt)*
685        }
686
687        $crate::wrapper! {
688            @INTERNAL WRAPPER_IMPL
689            $($tt)*
690        }
691    };
692
693    // Extract wrapper impl for `AsMut` trait.
694    (
695        @INTERNAL WRAPPER_IMPL
696        #[wrapper_impl(AsMut $(<$target:ty>)? )]
697        $($tt:tt)*
698    ) => {
699        $crate::wrapper! {
700            @INTERNAL WRAPPER_IMPL_AS_MUT $(<$target>)?
701            $($tt)*
702        }
703
704        $crate::wrapper! {
705            @INTERNAL WRAPPER_IMPL
706            $($tt)*
707        }
708    };
709
710    // Extract wrapper impl for `AsMut` trait, const version.
711    (
712        @INTERNAL WRAPPER_IMPL
713        #[wrapper_impl(ConstAsMut $(<$target:ty>)? )]
714        $($tt:tt)*
715    ) => {
716        $crate::wrapper! {
717            @INTERNAL WRAPPER_IMPL_CONST_AS_MUT $(<$target>)?
718            $($tt)*
719        }
720
721        $crate::wrapper! {
722            @INTERNAL WRAPPER_IMPL
723            $($tt)*
724        }
725    };
726
727    // Extract wrapper impl for `Borrow` trait.
728    (
729        @INTERNAL WRAPPER_IMPL
730        #[wrapper_impl(Borrow $(<$target:ty>)? )]
731        $($tt:tt)*
732    ) => {
733        $crate::wrapper! {
734            @INTERNAL WRAPPER_IMPL_BORROW $(<$target>)?
735            $($tt)*
736        }
737
738        $crate::wrapper! {
739            @INTERNAL WRAPPER_IMPL
740            $($tt)*
741        }
742    };
743
744    // Extract wrapper impl for `BorrowMut` trait.
745    (
746        @INTERNAL WRAPPER_IMPL
747        #[wrapper_impl(BorrowMut $(<$target:ty>)? )]
748        $($tt:tt)*
749    ) => {
750        $crate::wrapper! {
751            @INTERNAL WRAPPER_IMPL_BORROW $(<$target>)?
752            $($tt)*
753        }
754
755        $crate::wrapper! {
756            @INTERNAL WRAPPER_IMPL_BORROW_MUT $(<$target>)?
757            $($tt)*
758        }
759
760        $crate::wrapper! {
761            @INTERNAL WRAPPER_IMPL
762            $($tt)*
763        }
764    };
765
766    // Extract wrapper impl for `Debug` trait.
767    (
768        @INTERNAL WRAPPER_IMPL
769        #[wrapper_impl(Debug)]
770        $($tt:tt)*
771    ) => {
772        $crate::wrapper! {
773            @INTERNAL WRAPPER_IMPL_DEBUG
774            $($tt)*
775        }
776
777        $crate::wrapper! {
778            @INTERNAL WRAPPER_IMPL
779            $($tt)*
780        }
781    };
782
783    // Extract wrapper impl for `Debug` trait  printing its name only.
784    (
785        @INTERNAL WRAPPER_IMPL
786        #[wrapper_impl(DebugName)]
787        $($tt:tt)*
788    ) => {
789        $crate::wrapper! {
790            @INTERNAL WRAPPER_IMPL_DEBUG_NAME
791            $($tt)*
792        }
793
794        $crate::wrapper! {
795            @INTERNAL WRAPPER_IMPL
796            $($tt)*
797        }
798    };
799
800    // Extract wrapper impl for `Display` trait.
801    (
802        @INTERNAL WRAPPER_IMPL
803        #[wrapper_impl(Display)]
804        $($tt:tt)*
805    ) => {
806        $crate::wrapper! {
807            @INTERNAL WRAPPER_IMPL_DISPLAY
808            $($tt)*
809        }
810
811        $crate::wrapper! {
812            @INTERNAL WRAPPER_IMPL
813            $($tt)*
814        }
815    };
816
817    // Extract wrapper impl for `Deref` trait.
818    (
819        @INTERNAL WRAPPER_IMPL
820        #[wrapper_impl(Deref $(<$target:ty>)? )]
821        $($tt:tt)*
822    ) => {
823        $crate::wrapper! {
824            @INTERNAL WRAPPER_IMPL_DEREF $(<$target>)?
825            $($tt)*
826        }
827
828        $crate::wrapper! {
829            @INTERNAL WRAPPER_IMPL
830            $($tt)*
831        }
832    };
833
834    // Extract wrapper impl for `DerefMut` trait (and `Deref`).
835    (
836        @INTERNAL WRAPPER_IMPL
837        #[wrapper_impl(DerefMut $(<$target:ty>)? )]
838        $($tt:tt)*
839    ) => {
840        $crate::wrapper! {
841            @INTERNAL WRAPPER_IMPL_DEREF $(<$target>)?
842            $($tt)*
843        }
844
845        $crate::wrapper! {
846            @INTERNAL WRAPPER_IMPL_DEREF_MUT $(<$target>)?
847            $($tt)*
848        }
849
850        $crate::wrapper! {
851            @INTERNAL WRAPPER_IMPL
852            $($tt)*
853        }
854    };
855
856    // Extract wrapper impl for `From` trait.
857    (
858        @INTERNAL WRAPPER_IMPL
859        #[wrapper_impl(From)]
860        $($tt:tt)*
861    ) => {
862        $crate::wrapper! {
863            @INTERNAL WRAPPER_IMPL_FROM
864            $($tt)*
865        }
866
867        $crate::wrapper! {
868            @INTERNAL WRAPPER_IMPL
869            $($tt)*
870        }
871    };
872
873    // ================ Impl `AsRef` trait for the wrapper type. ================
874    (
875        @INTERNAL WRAPPER_IMPL_AS_REF <$target:ty>
876        $(#[$meta:meta])*
877        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
878    ) => {
879        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsRef<$target> for $name$(<$($lt),+>)? {
880            fn as_ref(&self) -> &$target {
881                &self.inner
882            }
883        }
884    };
885    (
886        @INTERNAL WRAPPER_IMPL_AS_REF <$target:ty>
887        $(#[$meta:meta])*
888        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
889            $(#[$field_inner_meta:meta])*
890            $inner_vis:vis $inner:ident: $inner_ty:ty
891            $(
892                ,
893                $(#[$field_meta:meta])*
894                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
895            )*
896            $(,)?
897        }
898    ) => {
899        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsRef<$target> for $name$(<$($lt),+>)? {
900            fn as_ref(&self) -> &$target {
901                &self.$inner
902            }
903        }
904    };
905    (
906        @INTERNAL WRAPPER_IMPL_AS_REF
907        $(#[$meta:meta])*
908        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
909    ) => {
910        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsRef<$inner_ty> for $name$(<$($lt),+>)? {
911            fn as_ref(&self) -> &$inner_ty {
912                &self.inner
913            }
914        }
915
916        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
917            /// Returns a reference to the inner value.
918            #[inline(always)]
919            pub const fn as_inner(&self) -> &$inner_ty {
920                &self.inner
921            }
922        }
923    };
924    (
925        @INTERNAL WRAPPER_IMPL_AS_REF
926        $(#[$meta:meta])*
927        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
928            $(#[$field_inner_meta:meta])*
929            $inner_vis:vis $inner:ident: $inner_ty:ty
930            $(
931                ,
932                $(#[$field_meta:meta])*
933                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
934            )*
935            $(,)?
936        }
937    ) => {
938        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsRef<$inner_ty> for $name$(<$($lt),+>)? {
939            fn as_ref(&self) -> &$inner_ty {
940                &self.$inner
941            }
942        }
943
944        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
945            /// Returns a reference to the inner value.
946            #[inline(always)]
947            pub const fn as_inner(&self) -> &$inner_ty {
948                &self.$inner
949            }
950        }
951    };
952    // ================ Impl `AsRef` trait for the wrapper type. ================
953
954
955    // ================ Impl `AsMut` trait for the wrapper type. ================
956    (
957        @INTERNAL WRAPPER_IMPL_AS_MUT <$target:ty>
958        $(#[$meta:meta])*
959        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
960    ) => {
961        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$target> for $name$(<$($lt),+>)? {
962            #[inline(always)]
963            fn as_mut(&mut self) -> &mut $target {
964                &mut self.inner
965            }
966        }
967    };
968    (
969        @INTERNAL WRAPPER_IMPL_AS_MUT <$target:ty>
970        $(#[$meta:meta])*
971        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
972            $(#[$field_inner_meta:meta])*
973            $inner_vis:vis $inner:ident: $inner_ty:ty
974            $(
975                ,
976                $(#[$field_meta:meta])*
977                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
978            )*
979            $(,)?
980        }
981    ) => {
982        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$target> for $name$(<$($lt),+>)? {
983            #[inline(always)]
984            fn as_mut(&mut self) -> &mut $target {
985                &mut self.$inner
986            }
987        }
988    };
989    (
990        @INTERNAL WRAPPER_IMPL_AS_MUT
991        $(#[$meta:meta])*
992        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
993    ) => {
994        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$inner_ty> for $name$(<$($lt),+>)? {
995            #[inline(always)]
996            fn as_mut(&mut self) -> &mut $inner_ty {
997                &mut self.inner
998            }
999        }
1000
1001        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1002            #[inline(always)]
1003            /// Returns a mutable reference to the inner value.
1004            pub fn as_inner_mut(&mut self) -> &mut $inner_ty {
1005                &mut self.inner
1006            }
1007        }
1008    };
1009    (
1010        @INTERNAL WRAPPER_IMPL_AS_MUT
1011        $(#[$meta:meta])*
1012        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1013            $(#[$field_inner_meta:meta])*
1014            $inner_vis:vis $inner:ident: $inner_ty:ty
1015            $(
1016                ,
1017                $(#[$field_meta:meta])*
1018                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1019            )*
1020            $(,)?
1021        }
1022    ) => {
1023        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$inner_ty> for $name$(<$($lt),+>)? {
1024            #[inline(always)]
1025            fn as_mut(&mut self) -> &mut $inner_ty {
1026                &mut self.$inner
1027            }
1028        }
1029
1030        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1031            #[inline(always)]
1032            /// Returns a mutable reference to the inner value.
1033            pub fn as_inner_mut(&mut self) -> &mut $inner_ty {
1034                &mut self.$inner
1035            }
1036        }
1037    };
1038    (
1039        @INTERNAL WRAPPER_IMPL_CONST_AS_MUT <$target:ty>
1040        $(#[$meta:meta])*
1041        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1042    ) => {
1043        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$target> for $name$(<$($lt),+>)? {
1044            #[inline(always)]
1045            fn as_mut(&mut self) -> &mut $target {
1046                &mut self.inner
1047            }
1048        }
1049    };
1050    (
1051        @INTERNAL WRAPPER_IMPL_CONST_AS_MUT
1052        $(#[$meta:meta])*
1053        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1054            $(#[$field_inner_meta:meta])*
1055            $inner_vis:vis $inner:ident: $inner_ty:ty
1056            $(
1057                ,
1058                $(#[$field_meta:meta])*
1059                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1060            )*
1061            $(,)?
1062        }
1063    ) => {
1064        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$target> for $name$(<$($lt),+>)? {
1065            #[inline(always)]
1066            fn as_mut(&mut self) -> &mut $target {
1067                &mut self.$inner
1068            }
1069        }
1070    };
1071    (
1072        @INTERNAL WRAPPER_IMPL_CONST_AS_MUT
1073        $(#[$meta:meta])*
1074        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1075    ) => {
1076        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$inner_ty> for $name$(<$($lt),+>)? {
1077            #[inline(always)]
1078            fn as_mut(&mut self) -> &mut $inner_ty {
1079                &mut self.inner
1080            }
1081        }
1082
1083        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1084            #[inline(always)]
1085            /// Returns a mutable reference to the inner value.
1086            pub const fn as_inner_mut(&mut self) -> &mut $inner_ty {
1087                &mut self.inner
1088            }
1089        }
1090    };
1091    (
1092        @INTERNAL WRAPPER_IMPL_CONST_AS_MUT
1093        $(#[$meta:meta])*
1094        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1095            $(#[$field_inner_meta:meta])*
1096            $inner_vis:vis $inner:ident: $inner_ty:ty
1097            $(
1098                ,
1099                $(#[$field_meta:meta])*
1100                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1101            )*
1102            $(,)?
1103        }
1104    ) => {
1105        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::AsMut<$inner_ty> for $name$(<$($lt),+>)? {
1106            #[inline(always)]
1107            fn as_mut(&mut self) -> &mut $inner_ty {
1108                &mut self.$inner
1109            }
1110        }
1111
1112        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1113            #[inline(always)]
1114            /// Returns a mutable reference to the inner value.
1115            pub const fn as_inner_mut(&mut self) -> &mut $inner_ty {
1116                &mut self.$inner
1117            }
1118        }
1119    };
1120    // ================ Impl `AsMut` trait for the wrapper type. ================
1121
1122    // ================ Impl `Borrow` trait for the wrapper type. ================
1123    (
1124        @INTERNAL WRAPPER_IMPL_BORROW <$target:ty>
1125        $(#[$meta:meta])*
1126        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1127    ) => {
1128        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::Borrow<$target> for $name$(<$($lt),+>)? {
1129            fn borrow(&self) -> &$target {
1130                &self.inner
1131            }
1132        }
1133    };
1134    (
1135        @INTERNAL WRAPPER_IMPL_BORROW <$target:ty>
1136        $(#[$meta:meta])*
1137        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1138            $(#[$field_inner_meta:meta])*
1139            $inner_vis:vis $inner:ident: $inner_ty:ty
1140            $(
1141                ,
1142                $(#[$field_meta:meta])*
1143                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1144            )*
1145            $(,)?
1146        }
1147    ) => {
1148        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::Borrow<$target> for $name$(<$($lt),+>)? {
1149            fn borrow(&self) -> &$target {
1150                &self.$inner
1151            }
1152        }
1153    };
1154    (
1155        @INTERNAL WRAPPER_IMPL_BORROW
1156        $(#[$meta:meta])*
1157        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1158    ) => {
1159        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::Borrow<$inner_ty> for $name$(<$($lt),+>)? {
1160            fn borrow(&self) -> &$inner_ty {
1161                &self.inner
1162            }
1163        }
1164    };
1165    (
1166        @INTERNAL WRAPPER_IMPL_BORROW
1167        $(#[$meta:meta])*
1168        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1169            $(#[$field_inner_meta:meta])*
1170            $inner_vis:vis $inner:ident: $inner_ty:ty
1171            $(
1172                ,
1173                $(#[$field_meta:meta])*
1174                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1175            )*
1176            $(,)?
1177        }
1178    ) => {
1179        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::Borrow<$inner_ty> for $name$(<$($lt),+>)? {
1180            fn borrow(&self) -> &$inner_ty {
1181                &self.$inner
1182            }
1183        }
1184    };
1185    // ================ Impl `Borrow` trait for the wrapper type. ================
1186
1187    // ================ Impl `BorrowMut` trait for the wrapper type. ================
1188    (
1189        @INTERNAL WRAPPER_IMPL_BORROW_MUT <$target:ty>
1190        $(#[$meta:meta])*
1191        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1192    ) => {
1193        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::BorrowMut<$target> for $name$(<$($lt),+>)? {
1194            fn borrow_mut(&mut self) -> &mut $target {
1195                &mut self.inner
1196            }
1197        }
1198    };
1199    (
1200        @INTERNAL WRAPPER_IMPL_BORROW_MUT <$target:ty>
1201        $(#[$meta:meta])*
1202        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1203            $(#[$field_inner_meta:meta])*
1204            $inner_vis:vis $inner:ident: $inner_ty:ty
1205            $(
1206                ,
1207                $(#[$field_meta:meta])*
1208                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1209            )*
1210            $(,)?
1211        }
1212    ) => {
1213        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::BorrowMut<$target> for $name$(<$($lt),+>)? {
1214            fn borrow_mut(&mut self) -> &mut $target {
1215                &mut self.$inner
1216            }
1217        }
1218    };
1219    (
1220        @INTERNAL WRAPPER_IMPL_BORROW_MUT
1221        $(#[$meta:meta])*
1222        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1223    ) => {
1224        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::BorrowMut<$inner_ty> for $name$(<$($lt),+>)? {
1225            fn borrow_mut(&mut self) -> &mut $inner_ty {
1226                &mut self.inner
1227            }
1228        }
1229    };
1230    (
1231        @INTERNAL WRAPPER_IMPL_BORROW_MUT
1232        $(#[$meta:meta])*
1233        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1234            $(#[$field_inner_meta:meta])*
1235            $inner_vis:vis $inner:ident: $inner_ty:ty
1236            $(
1237                ,
1238                $(#[$field_meta:meta])*
1239                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1240            )*
1241            $(,)?
1242        }
1243    ) => {
1244        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::borrow::BorrowMut<$inner_ty> for $name$(<$($lt),+>)? {
1245            fn borrow_mut(&mut self) -> &mut $inner_ty {
1246                &mut self.$inner
1247            }
1248        }
1249    };
1250    // ================ Impl `Borrow` trait for the wrapper type. ================
1251
1252    // ================ Impl `Debug` trait for the wrapper type. ================
1253    (
1254        @INTERNAL WRAPPER_IMPL_DEBUG
1255        $(#[$meta:meta])*
1256        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1257    ) => {
1258        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Debug for $name$(<$($lt),+>)?
1259        where
1260            $inner_ty: ::core::fmt::Debug,
1261        {
1262            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1263                ::core::fmt::Debug::fmt(&self.inner, f)
1264            }
1265        }
1266    };
1267    (
1268        @INTERNAL WRAPPER_IMPL_DEBUG
1269        $(#[$meta:meta])*
1270        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1271            $(#[$field_inner_meta:meta])*
1272            $inner_vis:vis $inner:ident: $inner_ty:ty
1273            $(
1274                ,
1275                $(#[$field_meta:meta])*
1276                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1277            )*
1278            $(,)?
1279        }
1280    ) => {
1281        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Debug for $name$(<$($lt),+>)?
1282        where
1283            $inner_ty: ::core::fmt::Debug,
1284        {
1285            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1286                ::core::fmt::Debug::fmt(&self.$inner, f)
1287            }
1288        }
1289    };
1290    // ================ Impl `Debug` trait for the wrapper type. ================
1291
1292    // ================ Impl `DebugName` trait for the wrapper type. ================
1293    (
1294        @INTERNAL WRAPPER_IMPL_DEBUG_NAME
1295        $(#[$meta:meta])*
1296        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1297    ) => {
1298        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Debug for $name$(<$($lt),+>)? {
1299            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1300                f.debug_struct(stringify!($name)).finish()
1301            }
1302        }
1303    };
1304    (
1305        @INTERNAL WRAPPER_IMPL_DEBUG_NAME
1306        $(#[$meta:meta])*
1307        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1308            $(#[$field_inner_meta:meta])*
1309            $inner_vis:vis $inner:ident: $inner_ty:ty
1310            $(
1311                ,
1312                $(#[$field_meta:meta])*
1313                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1314            )*
1315            $(,)?
1316        }
1317    ) => {
1318        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Debug for $name$(<$($lt),+>)? {
1319            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1320                f.debug_struct(stringify!($name)).finish()
1321            }
1322        }
1323    };
1324    // ================ Impl `DebugName` trait for the wrapper type. ================
1325
1326    // ================ Impl `Display` trait for the wrapper type. ================
1327    (
1328        @INTERNAL WRAPPER_IMPL_DISPLAY
1329        $(#[$meta:meta])*
1330        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1331    ) => {
1332        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Display for $name$(<$($lt),+>)?
1333        where
1334            $inner_ty: ::core::fmt::Display,
1335        {
1336            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1337                ::core::fmt::Display::fmt(&self.inner, f)
1338            }
1339        }
1340    };
1341    (
1342        @INTERNAL WRAPPER_IMPL_DISPLAY
1343        $(#[$meta:meta])*
1344        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1345            $(#[$field_inner_meta:meta])*
1346            $inner_vis:vis $inner:ident: $inner_ty:ty
1347            $(
1348                ,
1349                $(#[$field_meta:meta])*
1350                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1351            )*
1352            $(,)?
1353        }
1354    ) => {
1355        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::fmt::Display for $name$(<$($lt),+>)?
1356        where
1357            $inner_ty: ::core::fmt::Display,
1358        {
1359            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
1360                ::core::fmt::Display::fmt(&self.$inner, f)
1361            }
1362        }
1363    };
1364    // ================ Impl `Display` trait for the wrapper type. ================
1365
1366    // ================ Impl `Deref` trait for the wrapper type. ================
1367    (
1368        @INTERNAL WRAPPER_IMPL_DEREF <$target:ty>
1369        $(#[$meta:meta])*
1370        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1371    ) => {
1372        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::Deref for $name$(<$($lt),+>)? {
1373            type Target = $target;
1374
1375            fn deref(&self) -> &Self::Target {
1376                &self.inner
1377            }
1378        }
1379    };
1380    (
1381        @INTERNAL WRAPPER_IMPL_DEREF <$target:ty>
1382        $(#[$meta:meta])*
1383        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1384            $(#[$field_inner_meta:meta])*
1385            $inner_vis:vis $inner:ident: $inner_ty:ty
1386            $(
1387                ,
1388                $(#[$field_meta:meta])*
1389                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1390            )*
1391            $(,)?
1392        }
1393    ) => {
1394        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::Deref for $name$(<$($lt),+>)? {
1395            type Target = $target;
1396
1397            fn deref(&self) -> &Self::Target {
1398                &self.$inner
1399            }
1400        }
1401    };
1402    (
1403        @INTERNAL WRAPPER_IMPL_DEREF
1404        $(#[$meta:meta])*
1405        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1406    ) => {
1407        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::Deref for $name$(<$($lt),+>)? {
1408            type Target = $inner_ty;
1409
1410            fn deref(&self) -> &Self::Target {
1411                &self.inner
1412            }
1413        }
1414    };
1415    (
1416        @INTERNAL WRAPPER_IMPL_DEREF
1417        $(#[$meta:meta])*
1418        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1419            $(#[$field_inner_meta:meta])*
1420            $inner_vis:vis $inner:ident: $inner_ty:ty
1421            $(
1422                ,
1423                $(#[$field_meta:meta])*
1424                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1425            )*
1426            $(,)?
1427        }
1428    ) => {
1429        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::Deref for $name$(<$($lt),+>)? {
1430            type Target = $inner_ty;
1431
1432            fn deref(&self) -> &Self::Target {
1433                &self.$inner
1434            }
1435        }
1436    };
1437    // ================ Impl `Deref` trait for the wrapper type. ================
1438
1439    // ================ Impl `DerefMut` traits for the wrapper type. ================
1440    (
1441        @INTERNAL WRAPPER_IMPL_DEREF_MUT <$target:ty>
1442        $(#[$meta:meta])*
1443        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1444    ) => {
1445        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::DerefMut for $name$(<$($lt),+>)? {
1446            fn deref_mut(&mut self) -> &mut Self::Target {
1447                &mut self.inner
1448            }
1449        }
1450    };
1451    (
1452        @INTERNAL WRAPPER_IMPL_DEREF_MUT <$target:ty>
1453        $(#[$meta:meta])*
1454        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1455            $(#[$field_inner_meta:meta])*
1456            $inner_vis:vis $inner:ident: $inner_ty:ty
1457            $(
1458                ,
1459                $(#[$field_meta:meta])*
1460                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1461            )*
1462            $(,)?
1463        }
1464    ) => {
1465        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::DerefMut for $name$(<$($lt),+>)? {
1466            fn deref_mut(&mut self) -> &mut Self::Target {
1467                &mut self.$inner
1468            }
1469        }
1470    };
1471    (
1472        @INTERNAL WRAPPER_IMPL_DEREF_MUT
1473        $(#[$meta:meta])*
1474        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1475    ) => {
1476        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::DerefMut for $name$(<$($lt),+>)? {
1477            fn deref_mut(&mut self) -> &mut Self::Target {
1478                &mut self.inner
1479            }
1480        }
1481    };
1482    (
1483        @INTERNAL WRAPPER_IMPL_DEREF_MUT
1484        $(#[$meta:meta])*
1485        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1486            $(#[$field_inner_meta:meta])*
1487            $inner_vis:vis $inner:ident: $inner_ty:ty
1488            $(
1489                ,
1490                $(#[$field_meta:meta])*
1491                $field_vis:vis $field:ident: $field_ty:ty$( = $field_default: expr)?
1492            )*
1493            $(,)?
1494        }
1495    ) => {
1496        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::ops::DerefMut for $name$(<$($lt),+>)? {
1497            fn deref_mut(&mut self) -> &mut Self::Target {
1498                &mut self.$inner
1499            }
1500        }
1501    };
1502    // ================ Impl `DerefMut` traits for the wrapper type. ================
1503
1504    // ================ Impl `From` trait for the wrapper type. ================
1505    (
1506        @INTERNAL WRAPPER_IMPL_FROM
1507        $(#[$meta:meta])*
1508        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? ($inner_vis:vis $inner_ty:ty);
1509    ) => {
1510        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::From<$inner_ty> for $name$(<$($lt),+>)? {
1511            fn from(inner: $inner_ty) -> Self {
1512                Self::from_inner(inner)
1513            }
1514        }
1515
1516        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1517            #[allow(unreachable_pub)]
1518            #[inline(always)]
1519            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
1520            pub const fn from(inner: $inner_ty) -> Self {
1521                Self::from_inner(inner)
1522            }
1523        }
1524    };
1525    (
1526        @INTERNAL WRAPPER_IMPL_FROM
1527        $(#[$meta:meta])*
1528        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1529            $(#[$field_inner_meta:meta])*
1530            $inner_vis:vis $inner:ident: $inner_ty:ty
1531            $(
1532                ,
1533                $(#[$field_meta:meta])*
1534                $field_vis:vis $field:ident: $field_ty:ty = $field_default:expr
1535            )*
1536            $(,)?
1537        }
1538    ) => {
1539        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? ::core::convert::From<$inner_ty> for $name$(<$($lt),+>)? {
1540            fn from($inner: $inner_ty) -> Self {
1541                Self::from_inner($inner)
1542            }
1543        }
1544
1545        impl$(<$($lt$(:$clt$(+$dlt)*)?),+>)? $name$(<$($lt),+>)? {
1546            #[allow(unreachable_pub)]
1547            #[inline(always)]
1548            #[doc = concat!("Creates [`", stringify!($name), "`] from the inner value.")]
1549            pub const fn from($inner: $inner_ty) -> Self {
1550                Self::from_inner($inner)
1551            }
1552        }
1553    };
1554    (
1555        @INTERNAL WRAPPER_IMPL_FROM
1556        $(#[$meta:meta])*
1557        $vis:vis struct $name:ident$(<$($lt:tt$(:$clt:tt$(+$dlt:tt)*)?$(=$default:tt)?),+>)? {
1558            $(#[$field_inner_meta:meta])*
1559            $inner_vis:vis $inner:ident: $inner_ty:ty
1560            $(
1561                ,
1562                $(#[$field_meta:meta])*
1563                $field_vis:vis $field:ident: $field_ty:ty
1564            )*
1565            $(,)?
1566        }
1567    ) => {
1568        compile_error!(
1569            "Invalid usage of `wrapper!` macro, cannot implement \
1570            `From` trait for wrapper types with multiple fields\
1571            but no default values given."
1572        );
1573    };
1574    // ================ Impl `From` trait for the wrapper type. ================
1575
1576    // No other wrapper_impl meta
1577    (@INTERNAL WRAPPER_IMPL $($tt:tt)*) => {};
1578
1579    // Catch-all for invalid usage of the macro.
1580    (@INTERNAL $($tt:tt)*) => {
1581        compile_error!(
1582            "Invalid usage of `wrapper!` macro. @INTERNAL \
1583            Please refer to the documentation for the correct syntax."
1584        );
1585    };
1586
1587    // Core macro for the wrapper type.
1588    ($($tt:tt)*) => {
1589        $crate::wrapper!(@INTERNAL IMPL $($tt)*);
1590        $crate::wrapper!(@INTERNAL WRAPPER_IMPL $($tt)*);
1591    };
1592}
wrapper_lite/lib.rs

wrapper_lite/
lib.rs
