consistent design of collections and their interfaces

[StefanKarpinski]

The current interface to things like hashes and sets is pretty thrown together and dodgy. For example, you can't put a set into a set at the moment because add(s::Set, s2::Set) adds the contents of the second set to the first, rather than adding the second set to the first as an item.

[JeffBezanson]

This is the only example of this "dodginess" that I'm aware of. Set union is a different operation than adding an element to the set. add(s, e) should always add e as an element. union(a,b) makes a new set that is the union, and union!(a, b) could add the elements of b to a. Actually we don't allow identifiers with ! but I could change that.

At least, we should write down what the collections interface is, I believe it consists of methods

start, done, next, ref, assign, add, get, has, del, isempty, length

[StefanKarpinski]

Awesome — writing down the interface is an excellent start. If that's the only dodgy API issue, then that's really good and this issue will be much easier to close than I anticipated.

[JeffBezanson]

Here's a question: should we use has(a,i) to test whether an array element has been assigned? I suppose has for arrays would work on any integer, and if the index is out of bounds it just returns false. isassigned might require an in-bounds index. Is that useful or should we just use has?

[StefanKarpinski]

That's a tough question. I guess the difference between an unassigned index and an out of bounds index is that you couldn't assign something to an out-of-bounds index even if you tried. What would the corresponding distinction for hashes be? Does using a key of the wrong type cause an "out-of-type" exception? Is that analogous to an out-of-bounds exception?

[JeffBezanson]

Possible additions to this interface:

adjoin, find

There are some other questions about how arrays fit the collections interface. I'm using del(a, i) to remove an element from an array, but it's not really the same as deleting from a hash table since the elements get shifted down so there might still be something at that index. Maybe it should be remove(a,i)?

We should take a vote or something on whether to use "x!" identifiers for mutating.

Also note contains in tensor.j and in and index_of in graph.j. These functions are ripe for standardization.

[JeffBezanson]

Another one: I'm not sure the method has(String,Char) is right. In all other cases has checks for the presence of a key, not a value.

[StefanKarpinski]

Yeah, I was considering making a spreadsheet of what various languages use for different operators and use that to try to pick the 1) best, 2) least surprising to the largest number of people.