Design Principles

[philipa]

Please document the design principles behind this API.

• Can common implementation operations (such as rebalancing) be implemented efficiently using the API, or is that some other interface?
• Attitude to garbage
• Internal vs external iteration. Proxing all access through INode (no API to walk just over E's). Why not Visitor?
• Relationship to other collection libraries
• Unordered children. What if I know I have a binary tree - its inconvenient to work through a Collection to get to Left and Right.
• Prior art

[mattunderscorechampion]

Common operations like rebalancing may need support from implementation specific SPI components.
I've added support for both external and internal iteration of both nodes and elements.
Binary and structured trees allow direct access to specific nodes and the collection of children has been replaced with an iterator.
Added documentation about prior art.
Garbage is going to depend on the implementation. I've separated out the different implementations as much as possible.