Data.Map.mapKeysMonotonic is a misleading name

[Elliot Cameron]

Hello!

In some recent analysis I ran into a subtlety that caught me by surprise:
Data.Map.mapKeysMonotonic has a misleading name.

A monotonic function is not a strictly *increasing* function, but merely
non-decreasing. However, mapKeysMonotonic requires that it's mapping
function be injective, which means it really only supports *increasing*
 functions.

valid (mapKeysMonotonic (\x -> if x `elem` [1,2] then 2 else x)
(fromList [(1, "a"), (2, "b"), (3, "c")])) == False

The docs hint at this with "This means that @f <https://github.com/f>@ maps
distinct original keys to distinct resulting keys."

However, I'd propose that we deprecate this name and rename to something
like mapKeysIncreasingor mapKeysAsc (to follow the pattern of other *Asc
functions). We should also clarify the docs.

>From https://github.com/haskell/containers/issues/617
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/libraries/attachments/20190403/8382fab9/attachment.html>