Add more clarifying examples to Sculptor documentation

[Lindamust]

/// Trait for borrowing multiple HList elements by type
pub trait Projector<Targets, Indices> {
    /// The projected view into the list
    type Projection<'a>
    where
        Self: 'a,
        Targets: 'a;

    /// Borrow multiple elements by type from an HList.
    fn project(&self) -> Self::Projection<'_>;
}

Usage example:

fn main () {
    use frunk_core::{hlist, HList, hlist_pat};
    let h = hlist![123u32, "hello world", true];
    type S = HList![bool, u32];

    let projection: HList![&bool, &u32] = h.project::<S, _>();
    let hlist_pat![bool_ref, u32_ref] = projection;
    assert_eq!(bool_ref, &true);
    assert_eq!(u32_ref, &123);
}

Description:
HList projection is an operation that views a heterogeneous list through a type-level “lens” of sorts, producing a new HList of shared references to selected elements. This is similar to how Sculptor is like a generalized version Plucker. Projector aims to be a more generalized version of Selector. It works by recursively calling get on the target types and accumulating their references in a HList. Though, this does come at a bit of a caveat...

We are calling get multiple times, which is fine because its a shared reference. The problem is that this locks us out of a possible fn project_mut in the future because Rust disallows multiple mutable references. Though, there could create a separate ProjectMut trait in the future, but the question of how to safely handle multiple dangling mutable references is still at large. I have documented a few possible workarounds in the footnotes of my crate: https://crates.io/crates/rust-hlist-projection/0.1.0

There is also another factor to consider. Right now the associated type Projection<'a> is generic over some lifetime 'a, so the trait as a whole is inherently not dyn compatible. This could be a limitation in some use cases, so a potential solution might be to move the lifetime to the trait generics. I didn't opt for it initially as it might not fit the style considering that Selector doesn't specify a lifetime on the trait generics even though its function is to borrow values.

Motivation:
I'm fairly new to functional programming, so when I stumbled upon your article on BeachApe I was quite intrigued by the type recursion. Looking into the code base I noticed that there is a missing link of abstraction of sorts. As mentioned before, one could think that Sculptor is a generalized version of Plucker. However, I couldn't find any clean or explicitly documented "generalized" Selector, which is where this PR comes into play. I hope some people find this interesting and useful as I don't really have any decent real-world use cases for something like this yet, though having the functionality available for the future wouldn't be a bad thing.

Also:
Is project a good name for this? I wouldn't mind if it was changed.

[Copilot]

Pull request overview

Adds an HList “projection” API to borrow multiple elements by type (without moving them), returning a new HList of shared references. This complements existing selection/sculpting capabilities by providing a generalized multi-get operation.

Changes:

• Introduce HCons::project inherent method for projecting an HList into a target “shape” as shared references.
• Add the Projector<Targets, Indices> trait with recursive implementations built on top of Selector.
• Add unit tests covering simple, multi-type, reordered, and “borrow doesn’t move” scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lloydmeta]

Very cool stuff ; I'm intrigued and think this would fit in the library yes.

I'm going to take a closer look when I have some more time, and maybe have a think about the name (I've tried hard to pick names that are extremely concrete, and obvious), though at the moment I don't have anything better than what you came up with :) thanks for the PR!

[lloydmeta]

Sorry that I didn't remember this (been a while since I've done much work here) but I think this accomplishes something similar and is supported today (takes an extra .to_ref() step which I had forgotten existed...):

Added in hlist.rs

    #[test]
    fn test_sculpt_after_ref() {
        let non_ref = hlist![9000, "joe", 41f32];
        let h = non_ref.to_ref();
        let (reshaped, remainder): (HList!(&f32, &i32), _) = h.sculpt();
        assert_eq!(reshaped, hlist![&41f32, &9000]);
        assert_eq!(remainder, hlist![&"joe"])
    }

    #[test]
    fn test_sculpt_after_ref_yours() {
        let non_ref = hlist![123u32, "hello world", true];
        let h = non_ref.to_ref();
        let (reshaped, remainder): (HList!(&bool, &u32), _) = h.sculpt();
        assert_eq!(reshaped, hlist![&true, &123]);
        assert_eq!(remainder, hlist![&"hello world"])
    }

[Lindamust]

Ah I see... My main concern was whether or not the original non_ref would be moved.
Like being able to take out the references while still being able to use the original at a later point.

[lloydmeta]

Ah I see... My main concern was whether or not the original non_ref would be moved. Like being able to take out the references while still being able to use the original at a later point.

    #[test]
    fn test_sculpt_after_ref_yours() {
        let non_ref = hlist![123u32, "hello world", true];
        let h = non_ref.to_ref();
        let (reshaped, remainder): (HList!(&bool, &u32), _) = h.sculpt();
        assert_eq!(reshaped, hlist![&true, &123]);
        assert_eq!(remainder, hlist![&"hello world"]);
        assert_eq!(non_ref.head, 123u32);
    }

I think that works, because to_ref() takes a reference

frunk/core/src/traits.rs

Lines 3 to 19 in a95af41

	/// An alternative to AsRef that does not force the reference type to be a pointer itself.
	///
	/// This lets us create implementations for our recursive traits that take the resulting
	/// Output reference type, without having to deal with strange, spurious overflows
	/// that sometimes occur when trying to implement a trait for &'a T (see this comment:
	/// <https://github.com/lloydmeta/frunk/pull/106#issuecomment-377927198>)
	///
	/// This functionality is also provided as an inherent method [on HLists] and [on Coproducts].
	/// However, you may find this trait useful in generic contexts.
	///
	/// [on HLists]: ../hlist/struct.HCons.html#method.to_ref
	/// [on Coproducts]: ../coproduct/enum.Coproduct.html#method.to_ref
	pub trait ToRef<'a> {
	type Output;
	fn to_ref(&'a self) -> Self::Output;
	}

Just now, I was confused by this as well (why did I name it **To**Ref even though it doesn't consume the original.... and it's because AsRef forces the returned thing to be a reference. It's not great and maybe I could have named it better 🤦🏼

[Lindamust]

I guess this is bit of a facepalm for both of us... Though the exposure to type-level programming has been a great experience so far. Therefore, I think moving forward it would be nice to have something like this explicitly documented as I think its actually quite a nice feature.

[lloydmeta]

I guess this is bit of a facepalm for both of us... Though the exposure to type-level programming has been a great experience so far. Therefore, I think moving forward it would be nice to have something like this explicitly documented as I think its actually quite a nice feature.

++ happy to have this documented; there's so many ways to compose this stuff that it certainly can be good to have it written down if you consider it useful.

[Lindamust]

Alright I've removed the Projector trait and replaced it with extra documentation on the Sculptor method. ToRef achieves the same effect and ToMut also allows for the mutable projections I was concerned about.

[lloydmeta]

Thanks, just a tiny fix.