derive_more/
lib.rs

1// These links overwrite the ones in `README.md`
2// to become proper intra-doc links in Rust docs.
3//! [`From`]: macro@crate::From
4//! [`Into`]: macro@crate::Into
5//! [`FromStr`]: macro@crate::FromStr
6//! [`TryFrom`]: macro@crate::TryFrom
7//! [`TryInto`]: macro@crate::TryInto
8//! [`IntoIterator`]: macro@crate::IntoIterator
9//! [`AsRef`]: macro@crate::AsRef
10//!
11//! [`Debug`]: macro@crate::Debug
12//! [`Display`-like]: macro@crate::Display
13//!
14//! [`Error`]: macro@crate::Error
15//!
16//! [`Index`]: macro@crate::Index
17//! [`Deref`]: macro@crate::Deref
18//! [`Not`-like]: macro@crate::Not
19//! [`Add`-like]: macro@crate::Add
20//! [`Mul`-like]: macro@crate::Mul
21//! [`Sum`-like]: macro@crate::Sum
22//! [`IndexMut`]: macro@crate::IndexMut
23//! [`DerefMut`]: macro@crate::DerefMut
24//! [`AddAssign`-like]: macro@crate::AddAssign
25//! [`MulAssign`-like]: macro@crate::MulAssign
26//!
27//! [`Constructor`]: macro@crate::Constructor
28//! [`IsVariant`]: macro@crate::IsVariant
29//! [`Unwrap`]: macro@crate::Unwrap
30//! [`TryUnwrap`]: macro@crate::TryUnwrap
31
32// The README includes doctests requiring these features. To make sure that
33// tests pass when not all features are provided we exclude it when the
34// required features are not available.
35#![cfg_attr(
36    all(
37        feature = "add",
38        feature = "display",
39        feature = "from",
40        feature = "into"
41    ),
42    doc = include_str!("../README.md")
43)]
44#![cfg_attr(not(feature = "std"), no_std)]
45#![cfg_attr(docsrs, feature(doc_auto_cfg))]
46#![cfg_attr(any(not(docsrs), ci), deny(rustdoc::all))]
47#![forbid(non_ascii_idents, unsafe_code)]
48#![warn(clippy::nonstandard_macro_braces)]
49
50// For macro expansion internals only.
51// Ensures better hygiene in case a local crate `core` is present in workspace of the user code,
52// or some other crate is renamed as `core`.
53#[doc(hidden)]
54pub use core;
55
56// Not public, but exported API. For macro expansion internals only.
57#[doc(hidden)]
58pub mod __private {
59    #[cfg(feature = "as_ref")]
60    pub use crate::r#as::{Conv, ExtractRef};
61
62    #[cfg(feature = "debug")]
63    pub use crate::fmt::{debug_tuple, DebugTuple};
64
65    #[cfg(feature = "error")]
66    pub use crate::vendor::thiserror::aserror::AsDynError;
67}
68
69// The modules containing error types and other helpers.
70
71#[cfg(feature = "add")]
72mod add;
73#[cfg(feature = "add")]
74pub use crate::add::{BinaryError, WrongVariantError};
75
76#[cfg(any(feature = "add", feature = "not"))]
77mod ops;
78#[cfg(any(feature = "add", feature = "not"))]
79pub use crate::ops::UnitError;
80
81#[cfg(feature = "as_ref")]
82mod r#as;
83
84#[cfg(feature = "debug")]
85mod fmt;
86
87#[cfg(feature = "error")]
88mod vendor;
89
90#[cfg(feature = "from_str")]
91mod r#str;
92#[cfg(feature = "from_str")]
93#[doc(inline)]
94pub use crate::r#str::FromStrError;
95
96#[cfg(any(feature = "try_into", feature = "try_from"))]
97mod convert;
98#[cfg(feature = "try_from")]
99#[doc(inline)]
100pub use crate::convert::TryFromReprError;
101#[cfg(feature = "try_into")]
102#[doc(inline)]
103pub use crate::convert::TryIntoError;
104
105#[cfg(feature = "try_unwrap")]
106mod try_unwrap;
107#[cfg(feature = "try_unwrap")]
108#[doc(inline)]
109pub use crate::try_unwrap::TryUnwrapError;
110
111// This can be unused if no feature is enabled. We already error in that case, but this warning
112// distracts from that error. So we suppress the warning.
113#[allow(unused_imports)]
114#[doc(inline)]
115pub use derive_more_impl::*;
116
117/// Module containing derive definitions only, without their corresponding traits.
118///
119/// Use it in your import paths, if you don't want to import traits, but only macros.
120pub mod derive {
121    // This can be unused if no feature is enabled. We already error in that case, but this warning
122    // distracts from that error. So we suppress the warning.
123    #[allow(unused_imports)]
124    #[doc(inline)]
125    pub use derive_more_impl::*;
126}
127
128/// Module containing derive definitions with their corresponding traits along.
129///
130/// Use it in your import paths, if you do want to import derives along with their traits.
131pub mod with_trait {
132    // When re-exporting traits from `std` we need to do a pretty crazy trick, because we ONLY want
133    // to re-export the traits and not derives that are called the same in the `std` module, because
134    // those would conflict with our own ones. The way we do this is by first importing both the
135    // trait and possible derive into a separate module and re-export them. Then, we wildcard-import
136    // all the things from that module into the main module, but we also import our own derive by
137    // its exact name. Due to the way wildcard imports work in Rust, that results in our own derive
138    // taking precedence over any derive from `std`. For some reason the named re-export of our own
139    // derive cannot be in this (or really any) macro too. It will somehow still consider it a
140    // wildcard then and will result in this warning `ambiguous_glob_reexports`, and not actually
141    // exporting of our derive.
142    macro_rules! re_export_traits((
143        $feature:literal, $new_module_name:ident, $module:path $(, $traits:ident)* $(,)?) => {
144            #[cfg(all(feature = $feature, any(not(docsrs), ci)))]
145            mod $new_module_name {
146                #[doc(hidden)]
147                pub use $module::{$($traits),*};
148            }
149
150            #[cfg(all(feature = $feature, any(not(docsrs), ci)))]
151            #[doc(hidden)]
152            pub use crate::with_trait::all_traits_and_derives::$new_module_name::*;
153        }
154    );
155
156    mod all_traits_and_derives {
157        re_export_traits!(
158            "add",
159            add_traits,
160            core::ops,
161            Add,
162            BitAnd,
163            BitOr,
164            BitXor,
165            Sub,
166        );
167        re_export_traits!(
168            "add_assign",
169            add_assign_traits,
170            core::ops,
171            AddAssign,
172            BitAndAssign,
173            BitOrAssign,
174            BitXorAssign,
175            SubAssign,
176        );
177        re_export_traits!("as_ref", as_ref_traits, core::convert, AsMut, AsRef);
178        re_export_traits!("debug", debug_traits, core::fmt, Debug);
179        re_export_traits!("deref", deref_traits, core::ops, Deref);
180        re_export_traits!("deref_mut", deref_mut_traits, core::ops, DerefMut);
181        re_export_traits!(
182            "display",
183            display_traits,
184            core::fmt,
185            Binary,
186            Display,
187            LowerExp,
188            LowerHex,
189            Octal,
190            Pointer,
191            UpperExp,
192            UpperHex,
193        );
194
195        #[cfg(not(feature = "std"))]
196        re_export_traits!("error", error_traits, core::error, Error);
197        #[cfg(feature = "std")]
198        re_export_traits!("error", error_traits, std::error, Error);
199
200        re_export_traits!("from", from_traits, core::convert, From);
201
202        re_export_traits!("from_str", from_str_traits, core::str, FromStr);
203
204        re_export_traits!("index", index_traits, core::ops, Index);
205
206        re_export_traits!("index_mut", index_mut_traits, core::ops, IndexMut);
207
208        re_export_traits!("into", into_traits, core::convert, Into);
209
210        re_export_traits!(
211            "into_iterator",
212            into_iterator_traits,
213            core::iter,
214            IntoIterator,
215        );
216
217        re_export_traits!("mul", mul_traits, core::ops, Div, Mul, Rem, Shl, Shr);
218
219        #[cfg(feature = "mul_assign")]
220        re_export_traits!(
221            "mul_assign",
222            mul_assign_traits,
223            core::ops,
224            DivAssign,
225            MulAssign,
226            RemAssign,
227            ShlAssign,
228            ShrAssign,
229        );
230
231        re_export_traits!("not", not_traits, core::ops, Neg, Not);
232
233        re_export_traits!("sum", sum_traits, core::iter, Product, Sum);
234
235        re_export_traits!("try_from", try_from_traits, core::convert, TryFrom);
236
237        re_export_traits!("try_into", try_into_traits, core::convert, TryInto);
238
239        // Now re-export our own derives by their exact name to overwrite any derives that the trait
240        // re-exporting might inadvertently pull into scope.
241        #[cfg(feature = "add")]
242        pub use derive_more_impl::{Add, BitAnd, BitOr, BitXor, Sub};
243
244        #[cfg(feature = "add_assign")]
245        pub use derive_more_impl::{
246            AddAssign, BitAndAssign, BitOrAssign, BitXorAssign, SubAssign,
247        };
248
249        #[cfg(feature = "as_ref")]
250        pub use derive_more_impl::{AsMut, AsRef};
251
252        #[cfg(feature = "constructor")]
253        pub use derive_more_impl::Constructor;
254
255        #[cfg(feature = "debug")]
256        pub use derive_more_impl::Debug;
257
258        #[cfg(feature = "deref")]
259        pub use derive_more_impl::Deref;
260
261        #[cfg(feature = "deref_mut")]
262        pub use derive_more_impl::DerefMut;
263
264        #[cfg(feature = "display")]
265        pub use derive_more_impl::{
266            Binary, Display, LowerExp, LowerHex, Octal, Pointer, UpperExp, UpperHex,
267        };
268
269        #[cfg(feature = "error")]
270        pub use derive_more_impl::Error;
271
272        #[cfg(feature = "from")]
273        pub use derive_more_impl::From;
274
275        #[cfg(feature = "from_str")]
276        pub use derive_more_impl::FromStr;
277
278        #[cfg(feature = "index")]
279        pub use derive_more_impl::Index;
280
281        #[cfg(feature = "index_mut")]
282        pub use derive_more_impl::IndexMut;
283
284        #[cfg(feature = "into")]
285        pub use derive_more_impl::Into;
286
287        #[cfg(feature = "into_iterator")]
288        pub use derive_more_impl::IntoIterator;
289
290        #[cfg(feature = "is_variant")]
291        pub use derive_more_impl::IsVariant;
292
293        #[cfg(feature = "mul")]
294        pub use derive_more_impl::{Div, Mul, Rem, Shl, Shr};
295
296        #[cfg(feature = "mul_assign")]
297        pub use derive_more_impl::{
298            DivAssign, MulAssign, RemAssign, ShlAssign, ShrAssign,
299        };
300
301        #[cfg(feature = "not")]
302        pub use derive_more_impl::{Neg, Not};
303
304        #[cfg(feature = "sum")]
305        pub use derive_more_impl::{Product, Sum};
306
307        #[cfg(feature = "try_from")]
308        pub use derive_more_impl::TryFrom;
309
310        #[cfg(feature = "try_into")]
311        pub use derive_more_impl::TryInto;
312
313        #[cfg(feature = "try_unwrap")]
314        pub use derive_more_impl::TryUnwrap;
315
316        #[cfg(feature = "unwrap")]
317        pub use derive_more_impl::Unwrap;
318    }
319
320    // Now re-export our own derives and the std traits by their exact name to make rust-analyzer
321    // recognize the #[doc(hidden)] flag.
322    // See issues:
323    // 1. https://github.com/rust-lang/rust-analyzer/issues/11698
324    // 2. https://github.com/rust-lang/rust-analyzer/issues/14079
325    #[cfg(feature = "add")]
326    #[doc(hidden)]
327    pub use all_traits_and_derives::{Add, BitAnd, BitOr, BitXor, Sub};
328
329    #[cfg(feature = "add_assign")]
330    #[doc(hidden)]
331    pub use all_traits_and_derives::{
332        AddAssign, BitAndAssign, BitOrAssign, BitXorAssign, SubAssign,
333    };
334
335    #[cfg(feature = "as_ref")]
336    #[doc(hidden)]
337    pub use all_traits_and_derives::{AsMut, AsRef};
338
339    #[cfg(feature = "constructor")]
340    #[doc(hidden)]
341    pub use all_traits_and_derives::Constructor;
342
343    #[cfg(feature = "debug")]
344    #[doc(hidden)]
345    pub use all_traits_and_derives::Debug;
346
347    #[cfg(feature = "deref")]
348    #[doc(hidden)]
349    pub use all_traits_and_derives::Deref;
350
351    #[cfg(feature = "deref_mut")]
352    #[doc(hidden)]
353    pub use all_traits_and_derives::DerefMut;
354
355    #[cfg(feature = "display")]
356    #[doc(hidden)]
357    pub use all_traits_and_derives::{
358        Binary, Display, LowerExp, LowerHex, Octal, Pointer, UpperExp, UpperHex,
359    };
360
361    #[cfg(feature = "error")]
362    #[doc(hidden)]
363    pub use all_traits_and_derives::Error;
364
365    #[cfg(feature = "from")]
366    #[doc(hidden)]
367    pub use all_traits_and_derives::From;
368
369    #[cfg(feature = "from_str")]
370    #[doc(hidden)]
371    pub use all_traits_and_derives::FromStr;
372
373    #[cfg(feature = "index")]
374    #[doc(hidden)]
375    pub use all_traits_and_derives::Index;
376
377    #[cfg(feature = "index_mut")]
378    #[doc(hidden)]
379    pub use all_traits_and_derives::IndexMut;
380
381    #[cfg(feature = "into")]
382    #[doc(hidden)]
383    pub use all_traits_and_derives::Into;
384
385    #[cfg(feature = "into_iterator")]
386    #[doc(hidden)]
387    pub use all_traits_and_derives::IntoIterator;
388
389    #[cfg(feature = "is_variant")]
390    #[doc(hidden)]
391    pub use all_traits_and_derives::IsVariant;
392
393    #[cfg(feature = "mul")]
394    #[doc(hidden)]
395    pub use all_traits_and_derives::{Div, Mul, Rem, Shl, Shr};
396
397    #[cfg(feature = "mul_assign")]
398    #[doc(hidden)]
399    pub use all_traits_and_derives::{
400        DivAssign, MulAssign, RemAssign, ShlAssign, ShrAssign,
401    };
402
403    #[cfg(feature = "not")]
404    #[doc(hidden)]
405    pub use all_traits_and_derives::{Neg, Not};
406
407    #[cfg(feature = "sum")]
408    #[doc(hidden)]
409    pub use all_traits_and_derives::{Product, Sum};
410
411    #[cfg(feature = "try_from")]
412    #[doc(hidden)]
413    pub use all_traits_and_derives::TryFrom;
414
415    #[cfg(feature = "try_into")]
416    #[doc(hidden)]
417    pub use all_traits_and_derives::TryInto;
418
419    #[cfg(feature = "try_unwrap")]
420    #[doc(hidden)]
421    pub use all_traits_and_derives::TryUnwrap;
422
423    #[cfg(feature = "unwrap")]
424    #[doc(hidden)]
425    pub use all_traits_and_derives::Unwrap;
426
427    // Re-export the derive macros again to show docs for our derives (but not for traits). This is
428    // done using a glob import to not hit E0252.
429    #[allow(unused_imports)]
430    pub use derive_more_impl::*;
431}
432
433// Check if any feature is enabled
434#[cfg(not(any(
435    feature = "full",
436    feature = "add",
437    feature = "add_assign",
438    feature = "as_ref",
439    feature = "constructor",
440    feature = "debug",
441    feature = "deref",
442    feature = "deref_mut",
443    feature = "display",
444    feature = "error",
445    feature = "from",
446    feature = "from_str",
447    feature = "index",
448    feature = "index_mut",
449    feature = "into",
450    feature = "into_iterator",
451    feature = "is_variant",
452    feature = "mul",
453    feature = "mul_assign",
454    feature = "not",
455    feature = "sum",
456    feature = "try_from",
457    feature = "try_into",
458    feature = "try_unwrap",
459    feature = "unwrap",
460)))]
461compile_error!(
462    "at least one derive feature must be enabled (or the \"full\" feature enabling all the derives)"
463);
derive_more/lib.rs

derive_more/
lib.rs
