diff --git a/doc/PhantomData.md b/doc/PhantomData.md new file mode 100644 index 0000000..7677f29 --- /dev/null +++ b/doc/PhantomData.md @@ -0,0 +1,63 @@ +# PhantomData +[PhantomData](https://doc.rust-lang.org/std/marker/struct.PhantomData.html) implements all of the derivable traits without placing bounds on the type it is given. Because of this, if a generic type is only used in a `PhantomData`, no bounds are placed on it. This is in contrast to Rust's `derive` which will add the trait bound regardless. + +## Example +This: +```rust +# extern crate derivative; +# use derivative::Derivative; +# use std::{marker::PhantomData, fmt::Debug}; +# +# struct NonDebug (); +# +#[derive(Derivative)] +#[derivative(Debug(bound = "A: Debug"))] // bound not needed. +struct Foo { + a: A, + b: PhantomData, +} + +fn main() { + let foo: Foo = Foo{ a: 1, b: PhantomData }; + println!("{:?}", foo); +} +``` + +is equivalent to this: +```rust +# extern crate derivative; +# use derivative::Derivative; +# use std::{marker::PhantomData, fmt::Debug}; +# +# struct NonDebug (); +# +#[derive(Derivative)] +#[derivative(Debug)] +struct Foo { + a: A, + b: PhantomData, +} + +fn main() { + let foo: Foo = Foo{ a: 1, b: PhantomData }; + println!("{:?}", foo); +} +``` + +Rust's derive which does not compile because it adds the bound `B: Debug`: +```rust, compile_fail +# use std::{marker::PhantomData, fmt::Debug}; +# +# struct NonDebug (); +# +#[derive(Debug)] // This will added the bounds: A: Debug, B: Debug +struct Foo { + a: A, + b: PhantomData, +} + +fn main() { + let foo: Foo = Foo{ a: 1, b: PhantomData }; + println!("{:?}", foo); // Won't compile because NonDebug does not implement Debug. +} +``` \ No newline at end of file diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md index 6676293..906aa27 100644 --- a/doc/SUMMARY.md +++ b/doc/SUMMARY.md @@ -23,3 +23,4 @@ +* [PhantomData](PhantomData.md) \ No newline at end of file