Struct linotype::OwnedProjection

pub struct OwnedProjection<K, V> { /* private fields */ }

A lingering projection/keyed sequence reprojector.

This type acts as stable multi-map from items in the input sequence (or rather: derived stored keys) to mutable stored values.

Stored keys and values persist across reprojections, as long as the necessary items appear in each sequence to warrant it.

An OwnedProjection can be converted into a value-pinning version of itself by through its .pin(self) method.
This pinning variant is still mutable, but won’t release stored values by value, always dropping them in place instead.

Implementations

impl<K, V> OwnedProjection<K, V>

Generics Glossary

• 'a: Lifetime of the OwnedProjection.
• 'b: Lifetime of the in-progress reprojection (i.e. the returned iterator).
• K: (Stored) Key.
• V: (Stored) Value.
• T: (Examined) Item.
• Q: ?Sized: Query or Quality, borrowed from T.
• S: Selector, projects (&mut T) -> &Q.
• F: Factory, projects (&mut T, &K) -> V.
• I: Input Iterator, with varying Iterator::Item.
• E: Arbitrary payload for Result::Err.

The selector will generally run once per item, the factory only to generate one value for each new entry.

The quality must be Eq to prevent edge cases where values cannot be kept, and stored keys are derived from the quality using ToOwned as necessary.

Note that in the resulting (T, &mut V) (i.e. just-confirmed item-value entries), the T is by value and the V is valid for the entirety of 'b.

Implementation Notes

This currently uses at least

K: Borrow<Q>,
T: 'b,
Q: ?Sized + Eq + ToOwned<Owned = K>,
S: 'b + FnOnce(&mut T) -> Result<Qr, E>,
F: 'b + FnOnce(&mut T, &K) -> Result<V, E>,

instead of

K: Borrow<Qr::Target>,
T: 'b,
Qr: Deref,
Qr::Target: ?Sized + Eq + ToOwned<Owned = K>,
S: 'b + FnOnce(&mut T) -> Result<Qr, E>,
F: 'b + FnOnce(&mut T, &K) -> Result<V, E>,

because the latter has the compiler ask for lifetime bounds on Qr, or a duplicate implementation entirely.

A Q: 'b bound is present on most methods, but usually not a problem.

pub fn new() -> Self

Creates a new non-pinning OwnedProjection instance.

FIXME:

This can nearly be const. It may be worthwhile to contribute a second constructor to Arena.

pub const fn pin(self) -> Pin<Self>

Turns this OwnedProjection into a Pin of its values.

Note that a panic in a K or V Drop implementation will abort the process via double-panic unless the "std" feature is enabled, as long as this instance remains pinning.

With the "std" feature enabled, OwnedProjection will always continue to clean up as needed, then re-panic the first panic it encountered.

Safety Notes

Note that this sets a flag to abort on panics from key and value Drop implementations iff the "std" feature is not active.

This means that transmuting an OwnedProjection to wrap it in a Pin is normally not a sound operation.
However, OwnedProjection itself never relies on this flag in other circumstances.

See also

PinningOwnedProjection, for the pinning API.

pub fn get<Q>(&self, key: &Q) -> Option<&V> where
    K: Borrow<Q>,
    Q: ?Sized + Eq, 

Retrieves a reference to the first value associated with key, iff available.

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V> where
    K: Borrow<Q>,
    Q: ?Sized + Eq, 

Retrieves a mutable reference to the first value associated with key, iff available.

pub fn reproject_try_by_keyed_try_with_keyed<'a: 'b, 'b, T, Q, S, F, I, E>(
    &'a mut self,
    items_selectors_factories: I
) -> impl 'b + Iterator<Item = Result<(T, &'a mut V), E>> where
    K: Borrow<Q>,
    T: 'b,
    Q: ?Sized + Eq + ToOwned<Owned = K>,
    S: 'b + FnOnce(&mut T) -> Result<&Q, E>,
    F: 'b + FnOnce(&mut T, &K) -> Result<V, E>,
    I: 'b + IntoIterator<Item = (T, S, F)>,
    E: 'b, 

Lazily updates this map according to a sequence of item, fallible selector and fallible factory triples.

Values that aren’t reused are dropped together with the returned iterator or on the next .reproject… method call.

pub fn reproject_try_by_try_with<'a: 'b, 'b, T, Q, S, F, I, E>(
    &'a mut self,
    items: I,
    selector: S,
    factory: F
) -> impl 'b + Iterator<Item = Result<(T, &'a mut V), E>> where
    K: Borrow<Q>,
    T: 'b,
    Q: 'b + ?Sized + Eq + ToOwned<Owned = K>,
    S: 'b + FnMut(&mut T) -> Result<&Q, E>,
    F: 'b + FnMut(&mut T, &K) -> Result<V, E>,
    I: 'b + IntoIterator<Item = T>,
    E: 'b, 

Lazily updates this map according to a sequence of items, a fallible selector and fallible factory.

Values that aren’t reused are dropped together with the returned iterator or on the next .reproject… method call.

pub fn reproject_by_keyed_with_keyed<'a: 'b, 'b, T, Q, S, F, I>(
    &'a mut self,
    items_selectors_factories: I
) -> impl 'b + Iterator<Item = (T, &'a mut V)> where
    K: Borrow<Q>,
    T: 'b,
    Q: 'b + ?Sized + Eq + ToOwned<Owned = K>,
    S: 'b + FnOnce(&mut T) -> &Q,
    F: 'b + FnOnce(&mut T, &K) -> V,
    I: 'b + IntoIterator<Item = (T, S, F)>, 

Lazily updates this map according to a sequence of item, selector and factory triples.

Values that aren’t reused are dropped together with the returned iterator or on the next .reproject… method call.

pub fn reproject_by_with<'a: 'b, 'b, T, Q, S, F, I>(
    &'a mut self,
    items: I,
    selector: S,
    factory: F
) -> impl 'b + Iterator<Item = (T, &'a mut V)> where
    K: Borrow<Q>,
    T: 'b,
    Q: 'b + ?Sized + Eq + ToOwned<Owned = K>,
    S: 'b + FnMut(&mut T) -> &Q,
    F: 'b + FnMut(&mut T, &K) -> V,
    I: 'b + IntoIterator<Item = T>, 

Lazily updates this map according to a sequence of items, a selector and a factory.

Values that aren’t reused are dropped together with the returned iterator or on the next .reproject… method call.

Trait Implementations

impl<K, V> Default for OwnedProjection<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<K, V> Drop for OwnedProjection<K, V>

fn drop(&mut self)

Executes the destructor for this type.