Minor containers API changes

[wren ng thornton]

On 11/28/11 3:54 PM, Evan Laforge wrote:
> You know, something else I've noticed is that Data.Map is by far my
> most common haddock destination.  So I think there's something to the
> idea that there are too many functions to memorize, even for frequent
> users, and we should emphasize combining forms over specific
> functions.

Agreed.

I think the factorization used in the bytestring-trie library gives a 
nice balance of (a) simplicity for the basic functions you really need, 
and (b) the whole kitchen sink if you really want it. In particular, the 
breakdown is to have two or three modules:

     Data.Foo:
         - Just the basics and the super-general combinators
     Data.Foo.Internal:
         - The real guts, if you feel like exposing them
     Data.Foo.Convenience:
         - Everything else that has crept into the API over the years
         - Not deprecated, but perhaps... lightly discouraged

The "basics" in the Data.Foo module include both the primitives (like 
`empty`) and also extremely specialized versions of the super-general 
combinators (like `insert`, `lookup`, or `delete`). This is the place 
for beginners to look.

The Convenience module is just giving common names for various 
specializations of the super-general combinators. While there are no 
optimization benefits or anything, it can be helpful to have this shared 
vocabulary for the various intermediate points between the super-general 
combinators and the basic operations. It also serves as a backward 
compatibility layer for people who don't want to have to change all 
their code to just using the basics.

However, this sort of refactoring should be considered in a separate 
proposal.

-- 
Live well,
~wren