NdArray Initializer API

[karllessard]

This draft shows how we could hydrate a just-allocated array using a new API that focuses on a stateful builder approach rather than the positional endpoints setXXX(value, coords) exposed by the NdArray itself.

Not only it simplifies the task of initializing an array with explicit values but also it allows us to allocate an empty sparse array and then let the user initialize its data (right now, the user have to allocate and initialize the data of the indices and values subarrays first before being able to allocate a sparse array).

Example of usage:

NdArray<String> array = NdArrays.ofObjects(String.class, Shape.of(3, 2), initializer -> {
     initializer.byVectors()
         .put("Cat", "Dog")
         .put("House") // partial initialization
         .to(2)
         .put("Orange", "Apple");
});
// -> [["Cat", "Dog"], ["House", null], ["Orange", "Apple"]]

[Craigacp]

Needs a bunch more documentation, I'm a bit confused by the type hierarchy, and it probably needs building out for the rest of the types before we make a release with it in.

[Craigacp]

So maybe this should be "next elements" rather than "next element", but also it's not entirely clear to me what happens if I pass in a rectangular ndarray into a larger ndarray where the values are set. Are they read off in row-major order and placed into the next elements in row-major order of the target array? Or is it doing broadcasting/shape matching of some kind?

[karllessard]

I made the contract more strict when it comes to per-element initialization: an initialization pass must always be done with elements of the same rank. So basically you target a dimension and then provide the elements for it.

[Craigacp]

Can these be final?

[karllessard]

The lifecycle of these coordinates have changed in the last version

[karllessard]

Closing this draft, please take a look at #13 @Craigacp