Attribute proc-macro to simplify deriving standard and other traits with custom generic type bounds.
The derive_where
attribute 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, Debug)]
#[derive_where(Eq, PartialEq)]
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:
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, Debug; 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 Debug {}
#[derive_where(Clone, Debug; T: Super)]
struct Example<T>(PhantomData<T>);
But more complex trait bounds are possible as well.
The example below will restrict the Clone
implementation for Example
to T::Type: Clone
:
trait Trait {
type Type;
}
struct Impl;
impl Trait for Impl {
type Type = i32;
}
#[derive_where(Clone, Debug; 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, Debug; T)]
#[derive_where(Eq, PartialEq; U)]
struct Example<T, U>(PhantomData<T>, PhantomData<U>);
Since Rust 1.62 deriving Default
on an enum is possible with the
#[default]
attribute. Derive-where allows this with a
#[derive_where(default)]
attribute:
#[derive_where(Clone, Default)]
enum Example<T> {
#[derive_where(default)]
A(PhantomData<T>),
}
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, PartialEq)]
#[derive_where(skip_inner)]
struct StructExample<T>(T);
assert_eq!(format!("{:?}", StructExample(42)), "StructExample");
assert_eq!(StructExample(42), StructExample(0));
#[derive_where(Debug, PartialEq)]
enum EnumExample<T> {
#[derive_where(skip_inner)]
A(T),
}
assert_eq!(format!("{:?}", EnumExample::A(42)), "A");
assert_eq!(EnumExample::A(42), EnumExample::A(0));
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::<()>)
);
Similar to the skip
attribute, incomparable
can be used to skip variants
or items in PartialEq
and PartialOrd
trait implementations, meaning
they will always yield false
for eq
and None
for partial_cmp
. This
results in all comparisons but !=
, i.e. ==
, <
, <=
, >=
and >
,
with the marked variant or struct evaluating to false
.
# use derive_where::derive_where;
#[derive(Debug)]
#[derive_where(PartialEq, PartialOrd)]
enum EnumExample {
#[derive_where(incomparable)]
Incomparable,
Comparable,
}
assert_eq!(EnumExample::Comparable, EnumExample::Comparable);
assert_ne!(EnumExample::Incomparable, EnumExample::Incomparable);
assert!(!(EnumExample::Comparable >= EnumExample::Incomparable));
assert!(!(EnumExample::Comparable <= EnumExample::Incomparable));
assert!(!(EnumExample::Incomparable >= EnumExample::Incomparable));
assert!(!(EnumExample::Incomparable <= EnumExample::Incomparable));
#[derive(Debug)]
#[derive_where(PartialEq, PartialOrd)]
#[derive_where(incomparable)]
struct StructExample;
assert_ne!(StructExample, StructExample);
assert!(!(StructExample >= StructExample));
assert!(!(StructExample <= StructExample));
Note that it is not possible to use incomparable
with Eq
or Ord
as
that would break their invariants.
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);
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>());
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
.
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
.
PartialOrd
and Ord
need to determine the discriminant type to
function correctly. To protect against a potential future change to the
default discriminant type, some compile-time validation is inserted to
ascertain that the type remains isize
.
no_std
support is provided by default.
nightly
: ImplementsOrd
andPartialOrd
with the help ofcore::intrinsics::discriminant_value
, which is what Rust does by default too. This requires a nightly version of the Rust compiler.safe
:safe
: Uses only safe ways to access the discriminant of the enum forOrd
andPartialOrd
. It also replaces all cases ofcore::hint::unreachable_unchecked
inOrd
,PartialEq
andPartialOrd
, which is what std uses, withunreachable
.zeroize
: Allows derivingZeroize
andzeroize
onDrop
.zeroize-on-drop
: Allows derivingZeroize
andZeroizeOnDrop
and requireszeroize
v1.5.
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.
- derivative
is a great alternative with many options. Notably it doesn't support
no_std
and requires an extra#[derive(Derivative)]
to use. - derive_bounded is a new alternative still in development.
See the CHANGELOG file for details.
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.
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.