Crate derive_where
source · [−]Expand description
Description
Derive macro to simplify deriving standard and other traits with custom generic type bounds.
Usage
The derive_where
macro can be used just like std’s #[derive(...)]
statements:
#[derive_where(Clone, Debug)]
struct Example<T>(PhantomData<T>);
This will generate trait implementations for Example
for any T
,
as opposed to std’s derives, which would only implement these traits with
T: Trait
bound to the corresponding trait.
Multiple derive_where
attributes can be added to an item, but only the
first one must use any path qualifications.
#[derive_where::derive_where(Clone)]
#[derive_where(Debug)]
struct Example1<T>(PhantomData<T>);
If using a different package name, you must specify this:
#[derive_where(crate = "derive_where_")]
#[derive_where(Clone, Debug)]
struct Example<T>(PhantomData<T>);
In addition, the following convenience options are available:
Generic type bounds
Separated from the list of traits with a semi-colon, types to bind to can be
specified. This example will restrict the implementation for Example
to
T: Clone
:
#[derive_where(Clone; T)]
struct Example<T, U>(T, PhantomData<U>);
It is also possible to specify the bounds to be applied. This will
bind implementation for Example
to T: Super
:
trait Super: Clone {}
#[derive_where(Clone; T: Super)]
struct Example<T>(PhantomData<T>);
But more complex trait bounds are possible as well.
The example below will restrict the implementation for Example
to
T::Type: Clone
:
trait Trait {
type Type;
}
struct Impl;
impl Trait for Impl {
type Type = i32;
}
#[derive_where(Clone; T::Type)]
struct Example<T: Trait>(T::Type);
Any combination of options listed here can be used to satisfy a specific constrain. It is also possible to use multiple separate constrain specifications when required:
#[derive_where(Clone; T)]
#[derive_where(Debug; U)]
struct Example<T, U>(PhantomData<T>, PhantomData<U>);
Enum default
Deriving Default
on an enum is not possible in Rust at the moment.
Derive-where allows this with a default
attribute:
#[derive_where(Default)]
enum Example<T> {
#[derive_where(default)]
A(PhantomData<T>),
}
Skipping fields
With a skip
or skip_inner
attribute fields can be skipped for traits
that allow it, which are: Debug
, Hash
, Ord
, PartialOrd
,
PartialEq
, Zeroize
and ZeroizeOnDrop
.
#[derive_where(Debug, PartialEq; T)]
struct Example<T>(#[derive_where(skip)] T);
assert_eq!(format!("{:?}", Example(42)), "Example");
assert_eq!(Example(42), Example(0));
It is also possible to skip all fields in an item or variant if desired:
#[derive_where(Debug)]
#[derive_where(skip_inner)]
struct StructExample<T>(T);
assert_eq!(format!("{:?}", StructExample(42)), "StructExample");
#[derive_where(Debug)]
enum EnumExample<T> {
#[derive_where(skip_inner)]
A(T),
}
assert_eq!(format!("{:?}", EnumExample::A(42)), "A");
Selective skipping of fields for certain traits is also an option, both in
skip
and skip_inner
. To prevent breaking invariants defined for these
traits, some of them can only be skipped in groups. The following groups are
available:
Debug
EqHashOrd
: SkipsEq
,Hash
,Ord
,PartialOrd
andPartialEq
.Hash
Zeroize
: SkipsZeroize
andZeroizeOnDrop
.
#[derive_where(Debug, PartialEq)]
#[derive_where(skip_inner(Debug))]
struct Example<T>(i32, PhantomData<T>);
assert_eq!(format!("{:?}", Example(42, PhantomData::<()>)), "Example");
assert_ne!(
Example(42, PhantomData::<()>),
Example(0, PhantomData::<()>)
);
Zeroize
options
Zeroize
has two options:
crate
: an item-level option which specifies a path to thezeroize
crate in case of a re-export or rename.fqs
: a field -level option which will use fully-qualified-syntax instead of calling thezeroize
method onself
directly. This is to avoid ambiguity between another method also calledzeroize
.
#[derive_where(Zeroize(crate = "zeroize_"))]
struct Example(#[derive_where(Zeroize(fqs))] i32);
impl Example {
// If we didn't specify the `fqs` option, this would lead to a compile
//error because of method ambiguity.
fn zeroize(&mut self) {
self.0 = 1;
}
}
let mut test = Example(42);
// Will call the struct method.
test.zeroize();
assert_eq!(test.0, 1);
// WIll call the `Zeroize::zeroize` method.
Zeroize::zeroize(&mut test);
assert_eq!(test.0, 0);
ZeroizeOnDrop
options
If the zeroize-on-drop
feature is enabled, it implements ZeroizeOnDrop
and can be implemented without Zeroize
, otherwise it only implements
Drop
and requires Zeroize
to be implemented.
ZeroizeOnDrop
has one option:
crate
: an item-level option which specifies a path to thezeroize
crate in case of a re-export or rename.
#[derive_where(ZeroizeOnDrop(crate = "zeroize_"))]
struct Example(i32);
assert!(core::mem::needs_drop::<Example>());
Supported traits
The following traits can be derived with derive-where:
Clone
Copy
Debug
Default
Eq
Hash
Ord
PartialEq
PartialOrd
Zeroize
: Only available with thezeroize
crate feature.ZeroizeOnDrop
: Only available with thezeroize
crate feature. If thezeroize-on-drop
feature is enabled, it implementsZeroizeOnDrop
, otherwise it only implementsDrop
.
Supported items
Structs, tuple structs, unions and enums are supported. Derive-where tries
it’s best to discourage usage that could be covered by std’s derive
. For
example unit structs and enums only containing unit variants aren’t
supported.
Unions only support Clone
and Copy
.
no_std
support
no_std
support is provided by default.
Crate features
nightly
: ImplementsOrd
andPartialOrd
with the help ofcore::intrinsics::discriminant_value
, which is what Rust does by default too. Without this featuretransmute
is used to convertDiscriminant
to ai32
, which is the underlying type.safe
: ImplementsOrd
andPartialOrd
manually. This is much slower, but might be preferred if you don’t trust derive-where. It also replaces all cases ofcore::hint::unreachable_unchecked
inOrd
,PartialEq
andPartialOrd
, which is what std uses, withunreachable
.zeroize
: Allows derivingZeroize
andmethod@zeroize
onDrop
.zeroize-on-drop
: Allows derivingZeroize
andZeroizeOnDrop
and requires zeroize v1.5.
MSRV
The current MSRV is 1.57 and is being checked by the CI. A change will be
accompanied by a minor version bump. If MSRV is important to you, use
derive-where = "~1.x"
to pin a specific minor version to your crate.
Alternatives
derivative
()
is a great alternative with many options. Notably it doesn’t support
no_std
and requires an extra #[derive(Derivative)]
to use.
Changelog
See the CHANGELOG file for details.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Attribute Macros
Item-level options: