Add a merge API for Set

[meooow25]

For #732

[treeowl]

I don't remember who wrote the current code for alterF. It has an idea that we probably don't want here, but there should be a note about why. In particular, alterF shares the insertion and deletion structures throughout a functor that turns out to be a container. If I'm thinking about it right, we don't want anything like that here because the space leak potential is very high. There's an explosion in possible results, which all have to be kept around even if the container is consumed incrementally.

[meooow25]

I'm not sure I see how the alterF idea could be applied for filterA. alterF tries to eagerly calculate the set we would get if the function happens to change it. This is feasible because there is only one such set. For filterA, each element can be kept or dropped, which leads to $2^n-1$ other sets if we try the same thing.

Personally I don't think the alterF implementation is a good idea because it always allocates the other set, even if it turns out to be not the result. But this is a little off the current topic.

[treeowl]

Good point. We probably should discuss the alterF implementation elsewhere. It's clever in some contexts, but problematic in others.

[meooow25]

@treeowl any more comments on this?

[Vlix]

Just from a Developer Experience perspective, would the following be a good idea?

merge
  :: Ord a
  => (Set a, SimpleWhenMissing a)
     -- ^ @s1@ and what to do with elements that are not in @s2@
  -> (Set a, SimpleWhenMissing a)
     -- ^ @s2@ and what to do with elements that are not in @s1@
  -> SimpleWhenMatched a -- ^ What to do with elements in both @s1@ and @s2@
  -> Set a

[meooow25]

Worth considering, but I would say the current form is preferable.
(For the record, this interface is the same as in the existing Map.Merge.)

The idea is that this lets users define their merge function as

myMerge :: Ord a => Set a -> Set a -> Set a
myMerge = merge (... whenMissing1 ...) (... whenMissing2 ...) (... whenMatched ...)

which they can use where they need it. The doc also refers to this:

-- When 'mergeA' is given three arguments, it is inlined at the call
-- site. To prevent excessive inlining, you should generally only use
-- 'mergeA' to define custom combining functions.