Align Vector API with design, add some extra functions from AoC

[jdunkerley]

Pull Request Description

Vector

• Adjusted Vector.sort to be Vector.sort order on by.
  • Adjusted other sort to use order for direction argument.
• Added insert, remove, index_of and last_index_of to Vector.
• Added start and if_missing arguments to find on Vector, and adjusted default is Not_Found error.
• Added type checking to + on Vector.
• Altered first, second and last to error with Index_Out_Of_Bounds on Vector.
• Removed sum, exists, head, init, tail, rest, append, prepend from Vector.

Pair

• Added last, any, all, contains, find, index_of, last_index_of, reverse, each, fold and reduce to Pair.
• Added get to Pair.

Range

• Added first, second, index_of, last_index_of, reverse and reduce to Range.
• Added at and get to Range.
• Added start and if_missing arguments to find on Range.
• Simplified last and length of Range.
• Removed exists from Range.

List

• Added second, find, index_of, last_index_of, reverse and reduce to Range.
• Added at and get to List.
• Removed exists from List.
• Made all short-circuit if any fail on List.
• Altered is_empty to not compute the length of List.
• Altered first, tail, head, init and last to error with Index_Out_Of_Bounds on List.

Others

• Added first, second, last, get to Text.
• Added wrapper methods to the Random_Number_Generator so you can get random values more easily.
• Adjusted Aggregate_Column to operate on the first column by default.
• Added contains_key to Map.
• Added ALIAS to row_count and order_by.

Checklist

Please include the following checklist in your PR:

• The documentation has been updated if necessary.
• All code conforms to the
  Scala,
  Java,
  and
  Rust
  style guides.
• All code has been tested:
  • Unit tests have been written where possible.
  • If GUI codebase was changed: Enso GUI was tested when built using BOTH
    ./run ide build and ./run ide watch.

[JaroslavTulach]

Nice unification. Not very functional, but "if it quacks like a duck, it is a duck!" and Truffle should have no problem optimizing code even if different implementations of such vector-like objects pass thru.

I've added few suggestions about the API. They are just opinions.

I requested improvements in the test suites. Having a single test suite that is then executed with all suitable data types will ensure that expected behavior is the same for implementations. I'd like to see this done.

Remaining question is: how to prevent these vector-like types diverging in the future? I was thinking of using James tricks like:

var module = Context.getCurrent().getBindings("enso").invokeMember("get_module", moduleName);
var type = module.invokeMember("get_type", typeName);
var methods = type.getMemberKeys();

to verify there are no unexpected methods, parameters, etc. in all the vector-like types. This would prevent against future modifications that are done only in some of the vector-like types. This is just a suggestion, but it'd be nice to have such a signature testing infrastructure - it is going to be handy in the future (for example different implementations of SPI interfaces).

[JaroslavTulach]

Is each really needed? I could just use map instead (and I think I did in the past):

Pair.new 1 2 . map IO.println

works as well.

[jdunkerley]

map keeps a Vector of results for each execution, whereas each discards the result.

[JaroslavTulach]

The only difference is performance then, right?

In case of Pair using or discarding the result doesn't make a difference, I think. The compiler will see that the result isn't used and will avoid allocating the new Pair completely. Whether that is true for Vector and List as well would have to be checked. Chances are the Enso engine could provide the Graal compiler enough information to make map as effective as each.

Would then the need to have two APIs doing almost the same thing be eliminated?

[jdunkerley]

If we have a way where the compiler would know to discard the result, then yes could have a single API.

Currently, the map function will preallocate a Vector of the same size as the input for Vector.map. Likewise, for Range it does too. List and Pair have more specific implementations. We will have to tune memory allocations in various places in the coming months though.

[JaroslavTulach]

There should be a generic test suite working on Vector, List, Array (as soon as @hubertp aligns its methods) making sure the behavior is the same on all implementations of these "vector-like" objects.

[JaroslavTulach]

Here is an example where I was comparing methods on two types.

[radeusgd]

What if I do start=100? We should have a test for find that checks out of bounds offsets, much like we have for index_of.

[radeusgd]

I really like the new APIs and the direction where all of this is going, it's definitely a great step forward.

I like the changes, just in some cases I'd appreciate if we can simplify the code a bit.
Other than that - I think a few docs need some clarification (as noted) and there are a few tests that I think should be added - especially for the List methods - since the methods are not as easy to comprehend and see if there may be any bugs lurking, it's more crucial to get them very well tested.