add initial implementation of crate

Author: vadixidav

README.md

@@ -18,3 +18,5 @@
 Proxy GAT: Abstractions for generic proxy views with GAT to enable generic container types
 
 The purpose of this crate is to make it possible to construct containers that allow comparing internal data which may be represented entirely differently than its original form to views of that data that may exist in an entirely different form and have to be constructed from lifetimes. The specific example that forced the creation of this crate was the use of ndarray using Array2 as a storage structure for Array1 values. A container might wish to store clusters of Array2 or use a single Array2 to store a set of Array1 values, but in doing so it makes it impossible to get a reference to the underlying Array1. When inserting or adding new Array1 values, most container types need to be able to compare the underlying data in some way, and this crate provides abstractions to create unifying view types from internal and external data for comparison. Because the [`ProxyView`] type created by this crate has no associated lifetime, it makes it possible to compare data through views of the underlying data that can be created arbitrarily and with their own lifetimes. No reference type is needed. This enables abstracting downstream code over the container type and also allows abstracting containers over the intermediary view type the user wishes.
+
+A trivial implementation that allows the view to be a basic reference &T is provided as [`ReferenceProxy`]. It is recommended for container authors to use this proxy as a default type argument for the majority of users. For containers that need to use specific proxies, they can create their own proxy, such as a wrapper around ArrayView1, and then downstream users can override the defaults on containers that are permissive to match their view to yours. Users which require specific proxies for their own uses may also override them for permissive containers. Containers that use specialized storage methods might not store the owned version of the value directly, and so those are encouraged to create unique views for their type.

src/lib.rs

@@ -2,3 +2,65 @@
 
 #![no_std]
 doc_comment::doctest!("../README.md");
+
+use core::marker::PhantomData;
+
+/// A convenience type alias to get a view from a proxy and a lifetime.
+pub type View<'a, P> = <P as ProxyView>::View<'a>;
+
+/// A type generator that produces a view type for a given lifetime.
+///
+/// The owned value associated with the proxy is required to outlive any borrow lifetime,
+/// so it's type must be known when this trait is implemented.
+///
+/// It also provides a static method to generate a view from a reference to an owned value,
+/// though views may be generated in alternative ways. The view must always be generatable
+/// from a reference to the owned value. An example is ndarray arrays, which can be viewed
+/// as sub-slices, but you can always create a view from a single owned array. For instance,
+/// you might store multiple Array1 using Array2 and create views using rows/columns, but
+/// it is important that new points being added to the space can be viewed using an ArrayView1
+/// just like you can for points stored in the Array2 so that they can be compared.
+pub trait ProxyView {
+    /// The concrete type that this proxy borrows from.
+    type Owned;
+
+    /// The borrowed view type for a given lifetime.
+    /// `Self::Owned` must outlive the borrow lifetime to ensure safety.
+    type View<'a>
+    where
+        Self::Owned: 'a;
+
+    fn view<'a>(owned: &'a Self::Owned) -> Self::View<'a>;
+}
+
+/// Provides a generic way to clone owned values from arbitrary proxies.
+pub trait ProxyToOwned: ProxyView {
+    fn to_owned_proxy<'a>(view: Self::View<'a>) -> Self::Owned;
+}
+
+/// A proxy that simply returns a reference to the owned value.
+pub struct ReferenceProxy<T>(pub PhantomData<T>);
+
+impl<T> ReferenceProxy<T> {
+    pub fn new() -> Self {
+        ReferenceProxy(PhantomData)
+    }
+}
+
+impl<T> Default for ReferenceProxy<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<T> ProxyView for ReferenceProxy<T> {
+    type Owned = T;
+    type View<'a>
+        = &'a T
+    where
+        Self::Owned: 'a;
+
+    fn view<'a>(owned: &'a Self::Owned) -> Self::View<'a> {
+        owned
+    }
+}