After thinking about this some more, I agree there are important use cases for API like this:
orderedSet.insert(3, at: 0)
But I think this is the wrong name. This should be an ordering API, not an insertion API.
I think there's value in roughly dividing OrderedSet
APIs into two subgroups: one for insertions and deletions, and one for orderings. I'd expect there might be cross-over cases, but establishing subgroups helps for semantic consistency.
So, for insertions and deletions, OrderedSet
would use the words insert
and remove
, just like Set
, along with update
and the various operations from SetAlgebra
like union
and subtract
. The semantic rule would be something like: unless otherwise specified, elements Equatable
-equal to existing elements are silently ignored, and elements actually inserted go to the end of the current ordering. You would not normally have an index parameter with this kind of API.
For orderings, there would be API to rearrange objects by index, and the above example would be an ordering API, something like:
orderedSet.order(3, at: 0)
which would mean "find the element in the set that is Equatable
-equal to 3, and move it to index position 0; if no such element exists, insert the first parameter value, and move it to index position 0". Other ordering APIs would generally have an index or a range of indexes as a method parameter.
I think that makes the semantics comprehensible. If you're doing an ordering operation, any insertions implied by the operation are handled in a standardized default way. If you're doing an insertion or deletion operation, any reorderings implied by the operation are handled in a standard default way.