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:
```rust
struct Example
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.
```rust
struct Example1
If using a different package name, you must specify this:
```rust
struct Example
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:
```rust
struct Example
It is also possible to specify the bounds to be applied. This will
bind implementation for Example to T: Super:
```rust trait Super: Clone + Debug {}
struct Example
But more complex trait bounds are possible as well.
The example below will restrict the [Clone] implementation for Example
to T::Type: Clone:
```rust trait Trait { type Type; }
struct Impl;
impl Trait for Impl { type Type = i32; }
struct Example
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:
```rust
struct Example
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:
```rust
enum Example
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].
```rust
struct Example
asserteq!(format!("{:?}", Example(42)), "Example"); asserteq!(Example(42), Example(0)); ```
It is also possible to skip all fields in an item or variant if desired:
```rust
struct StructExample
asserteq!(format!("{:?}", StructExample(42)), "StructExample"); asserteq!(StructExample(42), StructExample(0));
enum EnumExample
asserteq!(format!("{:?}", EnumExample::A(42)), "A"); asserteq!(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: Skips [Eq], [Hash], [Ord], [PartialOrd] and
[PartialEq].
- [Hash]
- Zeroize: Skips [Zeroize] and [ZeroizeOnDrop].
```rust
struct Example
asserteq!(format!("{:?}", Example(42, PhantomData::<()>)), "Example"); assertne!( 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.
```rust
enum EnumExample { #[derivewhere(incomparable)] Incomparable, Comparable, } asserteq!(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));
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 optionsZeroize has two options:
- crate: an item-level option which specifies a path to the [zeroize]
crate in case of a re-export or rename.
- fqs: a field-level option which will use fully-qualified-syntax instead
of calling the zeroize method on self directly. This
is to avoid ambiguity between another method also called zeroize.
```rust
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 optionsIf 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 the [zeroize]
crate in case of a re-export or rename.
```rust
struct Example(i32);
assert!(core::mem::needs_drop::
The following traits can be derived with derive-where:
- [Clone]
- [Copy]
- [Debug]
- [Default]
- [Eq]
- [Hash]
- [Ord]
- [PartialEq]
- [PartialOrd]
- [Zeroize]: Only available with the zeroize crate feature.
- [ZeroizeOnDrop]: Only available with the zeroize crate feature. If the
zeroize-on-drop feature is enabled, it implements [ZeroizeOnDrop],
otherwise it only implements [Drop].
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 supportno_std support is provided by default.
nightly: Implements [Ord] and [PartialOrd] with the help of
[core::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
for [Ord] and [PartialOrd]. It also replaces all cases of
[core::hint::unreachable_unchecked] in [Ord], [PartialEq] and
[PartialOrd], which is what std uses, with [unreachable].zeroize: Allows deriving [Zeroize] and zeroize on
[Drop].zeroize-on-drop: Allows deriving [Zeroize] and [ZeroizeOnDrop] and
requires [zeroize] 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.
is a great alternative with many options. Notably it doesn't support
no_std and requires an extra #[derive(Derivative)] to use.
is a new alternative still in development.See the [CHANGELOG] file for details.
Licensed under either of
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.