Derive macro to simplify deriving standard and other traits with custom generic type bounds.
The derive_where macro 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 {}
struct Example
But more complex trait bounds are possible as well.
The example below will restrict the 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
Deriving [Default] on an enum is not possible in Rust at the moment.
Derive-where allows this with a 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
assert_eq!(format!("{:?}", StructExample(42)), "StructExample");
enum EnumExample
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: 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::<()>) ); ```
Zeroize options[Zeroize] 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@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.
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. Without this feature transmute is
used to convert Discriminant to a i32,
which is the underlying type.safe: Implements Ord and PartialOrd manually. This is much
slower, but might be preferred if you don't trust derive-where. 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 [method@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.
derivative
(
)
is a great alternative with many options. Notably it doesn't support no_std
and requires an extra #[derive(Derivative)] to use.
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.