#flag

macro no-std ghost

Define your own PhantomData

10 releases

new 0.1.9 Mar 18, 2023
0.1.7 Dec 17, 2022
0.1.6 Aug 3, 2022
0.1.5 Jun 28, 2022
0.1.0 Dec 23, 2018

#204 in Rust patterns

Download history 70235/week @ 2022-11-27 67342/week @ 2022-12-04 66836/week @ 2022-12-11 62261/week @ 2022-12-18 35014/week @ 2022-12-25 53784/week @ 2023-01-01 64223/week @ 2023-01-08 69401/week @ 2023-01-15 72183/week @ 2023-01-22 77676/week @ 2023-01-29 67403/week @ 2023-02-05 70889/week @ 2023-02-12 68176/week @ 2023-02-19 69990/week @ 2023-02-26 77293/week @ 2023-03-05 77306/week @ 2023-03-12

297,174 downloads per month
Used in 394 crates (3 directly)

MIT/Apache

28KB
429 lines

Define your own PhantomData

github crates.io docs.rs build status

This crate makes it possible to define your own PhantomData and similarly behaved unit types with generic parameters, which is not permitted in ordinary Rust.

[dependencies]
ghost = "0.1"

Supports rustc 1.31+

Background

PhantomData as defined by the Rust standard library is magical in that the same type is impossible to define in ordinary Rust code. It is defined in the standard library like this:

#[lang = "phantom_data"]
pub struct PhantomData<T: ?Sized>;

The #[lang = "..."] attribute indicates that this is a lang item, a special case known to the compiler. It is the only type permitted to carry an unused type parameter.

If we try to define an equivalent unit struct with type parameter, the compiler rejects that.

struct MyPhantom<T: ?Sized>;
error[E0392]: parameter `T` is never used
 --> src/main.rs:1:18
  |
1 | struct MyPhantom<T: ?Sized>;
  |                  ^ unused type parameter
  |
  = help: consider removing `T` or using a marker such as `std::marker::PhantomData`

This crate provides a #[phantom] attribute that makes it possible to define unit structs with generic parameters.

Examples

use ghost::phantom;

#[phantom]
struct MyPhantom<T: ?Sized>;

fn main() {
    // Proof that MyPhantom behaves like PhantomData.
    let _: MyPhantom<u8> = MyPhantom::<u8>;
    assert_eq!(0, std::mem::size_of::<MyPhantom<u8>>());
}

// Proof that MyPhantom is not just a re-export of PhantomData.
// If it were a re-export, these would be conflicting impls.
trait Trait {}
impl<T> Trait for std::marker::PhantomData<T> {}
impl<T> Trait for MyPhantom<T> {}

// Proof that MyPhantom is local to the current crate.
impl<T> MyPhantom<T> {
}

The implementation accepts where-clauses, lifetimes, multiple generic parameters, and derives. Here is a contrived invocation that demonstrates everything at once:

use ghost::phantom;

#[phantom]
#[derive(Copy, Clone, Default, Hash, PartialOrd, Ord, PartialEq, Eq, Debug)]
struct Crazy<'a, V: 'a, T> where &'a V: IntoIterator<Item = T>;

fn main() {
    let _ = Crazy::<'static, Vec<String>, &'static String>;

    // Lifetime elision.
    let crazy = Crazy::<Vec<String>, &String>;
    println!("{:?}", crazy);
}

Variance

The #[phantom] attribute accepts attributes on individual generic parameters (both lifetime and type parameters) to make them contravariant or invariant. The default is covariance.

  • #[contra] — contravariant generic parameter
  • #[invariant] — invariant generic parameter

The implications of variance are explained in more detail by the Subtyping chapter of the Rustonomicon.

use ghost::phantom;

#[phantom]
struct ContravariantLifetime<#[contra] 'a>;

fn f<'a>(arg: ContravariantLifetime<'a>) -> ContravariantLifetime<'static> {
    // This coercion is only legal because the lifetime parameter is
    // contravariant. If it were covariant (the default) or invariant,
    // this would not compile.
    arg
}

#[phantom]
struct Demo<A, #[contra] B, #[invariant] C>;

Use cases

Entirely up to your imagination. Just to name one, how about a typed registry library that admits the following syntax for iterating over values registered of a particular type:

for flag in Registry::<Flag> {
    /* ... */
}

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0.7–1MB
~26K SLoC