Proposal: Rename HashMap.lookupDefault to HashMap.findWithDefault

[Ivan Lazar Miljenovic]

On 24 January 2018 at 13:14, Matt Renaud <matt at m-renaud.com> wrote:
> What
> ====
>
> Rename unordered-container's Data.HashMap.lookupDefault to findWithDefault.
>
> findWithDefault :: (Eq k, Hashable k) => v -> k -> HashMap k v -> v
>
> Note: There are no functionality changes, this is purely a rename.
>
>
> Why
> ===
>
> This aligns the Data.HashMap API with containers' Data.Map.findWithDefault.
>
> Data.Map.findWithDefault :: Ord k => a -> k -> Map k a -> a
>
> The map APIs provided by the two packages are almost drop in replacement
> compatible if you aren't using any of the implementation specific functions
> (like ordering based functions from Data.Map), this change brings us one
> step closer.
>
> API consistency reduces the cognitive overhead when learning a new package.
> Having to learn different function names for the same functionality
> depending on which "map" implementation you're using is a poor developer
> experience.
>
> We chose the containers' name findWithDefault over unordered-containers'
> lookupDefault for two reasons:
>
> Existing lookupX functions returns a Maybe value, while findX functions
> return a non-wrapped value.
> The containers package ships with GHC and is a "core" package.
>
>
> Pros:
> -----
>
> - Consistent API between different "map" implementations (Data.Map,
> Data.IntMap, Data.HashMap). This makes switching implementations an import
> change.
> - Naming matches other similar functions (lookupX return Maybe-wrapped
> values)
>
> Cons:
> -----
>
> - API change requires users to update their code
>   + unordered-containers has A LOT of users: 358815 total (13325 in the last
> 30 days)
>
>
> How
> ===
>
> https://github.com/tibbe/unordered-containers/pull/176/commits/152f8818ee13dacb370e49b904edc4c1a4c8f87b
>
> Code Changes:
> -------------
>
> - Rename the function in Data.HashMap.Base (and expose it from Strict and
> Lazy modules)
> - Make lookupDefault an INLINE alias of findWithDefault
> - Add DEPRECATION notice to lookupDefault
> - Bump unordered-containers version to 0.2.9.0
>
>
> Migration - Option 1:
> ---------------------
>
> - Announce on Haskell communication channels (haskell-cafe@,
> haskell-community@, #haskell on Twitter, Reddit thread, etc.)
> - Users of unordered-containers >= 0.2.9.0 receive warning about deprecated
> function
> - Code can be updated by find and replace: s/lookupDefault/findWithDefault/
> - lookupDefault with deprecation notice remains for 1 year (subject to
> change)
> - after 1 year the lookupDefault function is removed, unordered-containers
> version bumped to 0.3.0.0 (major version bump due to breaking change)
>
> Migration - Option 2:
> ---------------------
>
> - Announce on Haskell communication channels (haskell-cafe@,
> haskell-community@, #haskell on Twitter, Reddit thread, etc.)
> - Users of unordered-containers >= 0.2.9.0 receive warning about deprecated
> function
> - Code can be updated by find and replace: s/lookupDefault/findWithDefault/
> - lookupDefault function is never removed
>
>
> Discussion:
> ===========
>
> I would like to get some comments on this proposal. In particular:
> - Is the small API churn worth the increase in consistency?
> - Should migration option 1 (completely remove the old function) or 2 (keep
> old function indefinitely) be taken? We can punt on this and go with option
> 2 to start and revisit later if desired.
>
> I hope a decision about the proposal can be reached by 2018-02-09. Thanks!

I prefer Option 1, but I think we need a release _without_ DEPRECATION
first, and then it can be added to lookupDefault (which currently
requires a major version bump per the PVP, though this might be
changing: https://github.com/haskell/pvp/issues/12 )

Whether this is worth it though is another story; until/unless we get
Backpack support on containers and unordered-containers (which also
requires adding a lot more functionality to the latter last I checked)
I think it's OK that they use different names.

-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
http://IvanMiljenovic.wordpress.com