Idea for ergonomic field projection API

[joshlf]

The API proposed in #196 looks like this:

// In these examples, `C<T>` is the container type, and `F` is the field type.

// Supports immutable and mutable references.
let _: &C<F> = project!(&c.f);
let _: &mut C<F> = project!(&mut c.f);

// Supports arbitrary expressions to generate the container reference.
let ident = |x| x;
let _: &C<F> = project!(&(ident(&c)).f);

// Supports chained field accesses.
let _: &C<G> = project!(&c.f.g);

// Supports indexing operations for elements and slices (bounds-checked at runtime).
let _: &C<H> = project!(&c.f.g[0]);
let _: &C<[H]> = project!(&c.f.g[1..3]);

This API is clean, but not that discoverable if you're looking at the rustdoc for a particular container type. Ideally, projection would be accomplished with a method which would show up in the container's rustdoc. Here's an idea for how to support projection via a method that is still reasonably ergonomic.

First, introduce a Projection type which represents projection into a particular field. This type is constructible using a macro.

/// The projection of `T`'s field of type `F`.
struct Projection<T, F> { ... }

let _: Projection<T, F> = project!(f);

Then a particular container type can add a project method which takes a Projection:

impl<T> Container<T> {
    fn project<F>(&self, projection: Projection<T, F>) -> &Container<F> { ... }
    fn project_mut<F>(&mut self, projection: Projection<T, F>) -> &mut Container<F> { ... }
}

Using the examples from the top, we could modify them as:

// In these examples, `C<T>` is the container type, and `F` is the field type.

// Supports immutable and mutable references.
let _: &C<F> = project!(&c.f);
let _: &C<F> = c.project(project!(f));

let _: &mut C<F> = project!(&mut c.f);
let _: &mut C<F> = c.project_mut(project!(f));

// Supports arbitrary expressions to generate the container reference.
let ident = |x| x;
let _: &C<F> = project!(&(ident(&c)).f);
let _: &C<F> = ident(&x).project(project!(f));

// Supports chained field accesses.
let _: &C<G> = project!(&c.f.g);
let _: &C<G> = c.project(project!(f.g));

// Supports indexing operations for elements and slices (bounds-checked at runtime).
let _: &C<H> = project!(&c.f.g[0]);
let _: &C<H> = c.project(project!(f.g[0]));

let _: &C<[H]> = project!(&c.f.g[1..3]);
let _: &C<[H]> = c.project(project!(f.g[1..3]));