Trait image_texel::layout::Decay

source · [−]

pub trait Decay<T>: Layout {
    fn decay(from: T) -> Self;
}

Expand description

Convert one layout to a less strict one.

In contrast to From/Into which is mostly assumed to model a lossless conversion the conversion here may generalize but need not be lossless. For example, the Bytes layout is the least descriptive layout that exists and any layout can decay into it. However, it should be clear that this conversion is never lossless.

In general, a layout L should implement Decay<T> if any image with layouts of type T is also valid for some layout of type L. A common example would be if a crate strictly adds more information to a predefined layout, then it should also decay to that layout.

Also note that this trait is not reflexive, in contrast to From and Into which are. This avoids collisions in impls. In particular, it allows adding blanket impls of the form

struct Local;

impl Trait for Local { /* … */ }

impl<T: Trait> Decay<T> for Local { /* … */ }

Otherwise, the instantiation T = U would collide with the reflexive impl.

Design

We consider re-rebalanced coherence rules (RFC2451) in this design especially to define the receiver type and the type parameter. Note that adding a blanket impl is a breaking change except under a special rule allowed in that RFC. To quote it here:

RFC #1023 is amended to state that adding a new impl to an existing trait is considered a breaking change unless, given impl<P1..=Pn> Trait<T1..=Tn> for T0:

At least one of the types T0..=Tn must be a local type, added in this revision. Let Ti be the first such type.

No uncovered type parameters P1..=Pn appear in T0..Ti (excluding Ti)

[…]

However, the following impls would not be considered a breaking change: […]

impl<T> OldTrait<T> for NewType

Let’s say we want to introduce a new desciptor trait for matrix-like layouts. Then we can ship a new type representing the canonical form of this matrix trait and in the same revision define a blanket impl that allows other layouts to decay to it. This wouldn’t be possible if the parameters were swapped. We can then let this specific type (it may contain covered type parameters) decay to any other previously defined layout to provide interoperability with older code.