Crate projecture

source · [−]
Expand description

Projecture

This is in a proof of concept state and also internally uses a lot of not yet battle-tested unsafe code so use it on your own risk meanwhile if you are good with unsafe rust i would appreciate a soundness review

Allows to do an arbitrary projections without procedural macros, and as such does not have additional requirements on target struct, so in comparison to other crates that do similar things if target struct is located in external crate that crate does not have to explicitly add a support such projection.

Although as of now this crate doesn’t support enums yet, but it will be added soon.

Currently can do following type of projections
  • Destructuring projection (similar to usual let <pattern> but also supports deref pattern, and also works if struct implements Drop which is just not called)
  • Reference projection (similar to match ergonomics in let <pattern> but also supports deref pattern)
  • Mutable reference projection (similar to match ergonomics in let <pattern> but also supports deref pattern)
  • Pin projection
  • Cell projection
  • MaybeUninit projection
  • Atomic(from atomic crate) projection
  • Option projection (which works together with other kinds of projections)
  • RefCell guards projection
  • raw pointers projections (*const T, *mut T, NonNull<T>)

Also, where possible, projections can additionally project through a Deref type

See project! macro for usage examples.

Also allows dependent crates to define their own projections via traits. see atomic module for example of how to do a projection of a transparent field wrapper or Pin for doing projections on a custom reference type

MSRV: 1.53

Macros

pin_drop
project

Macro to do all kinds of projections

Structs

Marker

Marker type for the projections used in this crate. You can use that if you need to reuse existing projections.

Unpinned

Transparent wrapper to indicate that a type should not be pin projected. It will be removed after projection

Traits

CustomWrapper

Trait to, if necessary, transparently wrap type to prevent conflicting implementations

DerefOwned

Implement this if your type can be unwrapped on a dereference operation when doing destructuring projection

DerefProjectable

Implement it if your projection can meaningfully project through a deref operation

FinalizeProjection

Implement that if you need to do some kind of post processing like unwrap something or panic if some soundness requirements are not satisfied

PinDrop

For Pin projection to work soundly if struct wants to implement custom Drop it needs to always go through Pin<&mut Self>. So Drop implementation must directly delegate to PinDrop. Similar to what pin_project::pinned_drop is doing but without proc macros You can use pin_drop macro to implement that without unsafe

Projectable

Trait to get raw pointer to underlying struct

ProjectableMarker

Trait to wrap raw pointer to a field with a type that corresponds to a projection being done.

SupportsPacked

Implement this only if your projection can work with #[repr(packed)] structs.