A convenient alternative to the newtype pattern

When building an API in Rust, a common dilemma is the choice between type aliases and the newtype pattern.

Consider an application-specific collection of IDs with an underlying type of Vec<usize>;

Using a type alias, one may choose to define it as pub type Identifiers = Vec<usize> in order to provide consumers of the type with unfettered access to the underlying Vec methods, and allow Identifiers to be used interchangeably with Vec<usize>.

Conversely, it could also be defined via newtype as pub struct Identifiers(Vec<usize>). This creates a semantically-distinct type from Vec<usize>, but obscures access to its underlying methods.

Creating distinct types like this is one of the strengths of Rust's type system, as it allows data dependencies to be encoded at type-time instead of runtime:

pub struct Identifiers(Vec<usize>);

pub fn create_ids() -> Identifiers {
    Identifiers(vec![0, 1, 2, 3])
}

pub fn munge_ids(ids: Identifiers) {
    // ...
}

// Valid
let ids: Identifiers = create_ids(); // Known-correct IDs provided by a trusted function
munge_ids(ids);

// Not valid
// let ids = vec![999, 6, 876]; // IDs created arbitrarily, no guarantee of correctness
// munge_ids(ids); // Compiler error, incorrect type

In some cases, obscuring access to the underlying type's methods can be desirable, as it allows the available functionality to be determined by the API, thus implicitly providing information about its usage to the library consumer.

However, this is not true in all cases. Collection types like Vec are case-in-point; they have so many useful methods and trait implementations that manually re-exposing each one on a newtype becomes impractical, possibly resulting in an overly restrictive design.

In these cases, the inner type can be marked as pub, and / or certain useful access traits like Into, Borrow and Deref can be implemented.

From an API standpoint, this combines the qualities of both type aliasing and newtype: The type is distinct, but provides direct access to its underlying data. (Though note that this also means breaking changes to the inner type will propagate outward.)

Usage aims to model this sub-pattern as a generalized, reusable struct with intuitive implementations for standard derivable, construction and access traits.

Implementation

It does this by using two generic parameters: Type U to act as a tag identifying it as a distinct type, and type T for underlying data.

U is represented by a PhantomData, thus decoupling its trait implementations from those of the Usage.

Construction and access trait implementations are predicated on T, allowing the Usage to transparently act like its underlying type in as many contexts as possible.

Limitations

Due to coherence rules, foreign traits may not be implemented for foreign types. Thus, it's infeasible to implement foreign traits on Usage; as a library type, it's foreign by design.

This can be worked around by implementing the foreign trait over the Usage's T parameter , or by using a newtype that implements said trait as the T instead.

For cases where implementing over Usage is unavoidable, such as compatibility with certain std traits or those from commonly-used crates, feel free to send a pull request with the new functionality gated behind a feature flag as per the existing rayon and bytemuck implementations.