Unused

About Unused

The unused crate allows types to have unused generic parameters that do not act like they are owned.

Example

Imagine we have a struct LazyFromStr, which contains a &'static str and can lazily create a T using its FromStr impl.

To have T be a generic parameter of LazyFromStr, we can use a PhantomData. Otherwise, we get a compilation error that the parameter T is never used.

use std::marker::PhantomData;
use std::str::FromStr;

struct LazyFromStr<T> {
    str: &'static str,
    phantom: PhantomData<T>,
}

impl<T: FromStr> LazyFromStr<T> {
    fn create(&self) -> T {
        match T::from_str(self.str) {
            Ok(t) => t,
            Err(_) => panic!(),
        }
    }
}

The issue with using PhantomData is that LazyFromStr<T> is only Send and Sync if T also is, even though our LazyFromStr<T> does not own a T.

This is where unused comes in.

// We need to import `Unused`.
use unused::Unused;

struct LazyFromStr<T> {
    str: &'static str,
    // Use the `Unused` macro instead of `PhantomData`.
    unused: Unused!(T),
}

use std::convert::Infallible;
use std::rc::Rc;

// `RcString` is not `Send` or `Sync`.
struct RcString(Rc<String>);

impl FromStr for RcString {
    type Err = Infallible;

    fn from_str(str: &str) -> Result<Self, Self::Err> {
        Ok(Self(Rc::new(str.to_owned())))
    }
}

let lazy: LazyFromStr<RcString> = LazyFromStr {
    str: "a",
    // Use `Unused` as a value.
    unused: Unused,
};

use std::thread;

// `lazy` is `Send` (even though `RcString` is not), so we can send it between threads.
thread::spawn(move ||{
    let _ = lazy.create();
})
.join()
.unwrap();

Usage

First, add unused to your dependencies in Cargo.toml:

unused = "0.1"

Create a simple struct with an unused generic parameter:

use unused::Unused;

struct Foo<T> {
    some_string: String,
    unused: Unused!(T),
}

let foo: Foo<usize> = Foo {
    some_string: "hello".to_owned(),
    unused: Unused,
};

See the docs for the full documentation.

Feedback

If you experience any issues or have any feedback, please feel free to open an issue on the GitHub repository.

Related/Similar Crates

• type_variance - Marker traits for subtype variance
• ghost - Define your own PhantomData
• rich-phantoms - Phantom types with control over variance and sync/sync inheritance

License

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.

Contribution

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.