[vector] reshape, resize, rebracket, cast

[Vladimir Ivanov]

On 03/12/2018 06:44, Brian Goetz wrote:
> I think the operations `reshape`, `resize`, `rebracket`, and `cast` 
> could use some renaming, reshuffling, and rebracketing :)
> 
> Given the parameterization of vectors by (type, shape), a user might 
> thin that "reshape" means "take a vector of E of shape S, and convert it 
> to a vector of E of shape S'".  In other words, give it a new shape. 
> But, that's not what it means -- it is a bit-level reinterpret, with 
> truncation and fill.  The operation for "give a vector a new 
> Vector.Shape" is actually called "resize".  This is not obvious, because 
> of the multiple uses of "shape" in this API.
> 
> I'd recommend the following refactorings:
> 
>   - Rename current reshape to "reinterpret", since that is really what's 
> going on -- the bits are being reinterpreted.
>   - Rename current rebracket to "reinterpret" also, since it's the same 
> operation -- just holding shape constant.
>   - Rename "resize" to "reshape" (optional, resize is also OK)
>   - Move all these operations from Species to Vector / XxxVector:
> 
>      class Vector<E> {
>          Vector<E> reshape(Shape sh);               // or resize
>          <F> Vector<F> reinterpret(Species<F> sp);  // was reshape
>          <F> Vector<F> reinterpret(Class<F> cl);    // was rebracket
>          <F> Vector<F> cast(Class<F> cl);           // was cast
>      }

I assume you meant `cast(Species<F> sp)` here. Otherwise, looks good.

As you pointed out, `resize`->`reshape` may be questionable, but I'm in 
favor of `reshape`. Though Shape is all about vector bit-width now, it 
may change in the future (S_Max_BIT is a good example where it may go).

I especially like `reinterpretet(Class<F>)`, but I'm curious whether 
there's a better name to communicate there are *both* bit-level 
reinterpretation and reshape/resizing happening in case of 
`reinterpret(Species<F>)`?

It looks attractive to completely separate element & shape 
transformations (reinterpret(Class)/cast(Class) + reshape(Shape)), but 
there are some drawbacks.

The nice thing about operations on Species is their totality: once you 
have an instance of Species in your hands, it's possible to convert 
(either reinterpret or cast) any Vector instance to it. You lose that 
when switching to `cast(Class)`: widening per-element casts can easily 
exceed maximum vector size supported (both in hardware & 
implementation): e.g, Vector<Byte,S512Bit>.cast(Integer.class) => 
Vector<Integer,S2048Bit>.

> (I may have gotten the semantics of these wrong, but if so -- that only 
> strengthens my point -- that its hard to keep them straight in the 
> current stacking.)
> 
> Similar move for `cast(Mask)` and `cast(Shuffle)` -- move them to Mask 
> and Shuffle.
> 
> Making them instance methods on Vector seems more natural -- it's an 
> operation on the vector, and the species is just providing data to 
> parameterize the operation.  (It also lays the groundwork for further 
> refactoring Species.)

Agree.

Best regards,
Vladimir Ivanov