Dict.update is confusing

[gampleman]

Recently there was a discussion on Slack, where it turned out that even well seasoned Elm developers where confused about the semantics of Dict.update. Specifically, it is unclear what is supposed to happen when the provided function returns Nothing (i.e. should "nothing" happen - the value remains the same or does it cause the value to be removed?)

A secondary issue is that the code needed for one of the most common use cases - aggregation - is quite unwieldy:

-- for example to count by key is:
Dict.update
    key
    (Maybe.withDefault 0 >> (+) 1 >> Just)
    dict

---

I can see 2 possible solutions here:

1. Improve the docs with a) specifying what happens when b) adding some practical examples to illustrate this.
2. Change the API for a more Elixir like update : comparable -> v -> (v -> v) -> Dict comparable v -> Dict comparable v. This is less general, but arguably addresses one of the most common usecases much more explicitly:

Dict.update key 1 ((+) 1) dict

For situations where delete semantics are useful, it is not too hard to write explicit remove logic and it is probably easier to parse anyway:

toggle : comparable -> v -> Dict comparable v ->  Dict comparable v
toggle key val =
    Dict.update key (Maybe.andThen (always Nothing) >> Maybe.withDefault (Just val))

-- vs: --

toggle key val dict =
     case Dict.get key dict of
          Just v ->
                Dict.remove key dict
          Nothing ->
                Dict.insert key val

[github-actions]

Thanks for reporting this! To set expectations:

• Issues are reviewed in batches, so it can take some time to get a response.
• Ask questions a community forum. You will get an answer quicker that way!
• If you experience something similar, open a new issue. We like duplicates.

Finally, please be patient with the core team. They are trying their best with limited resources.

[cmditch]

I find the current Dict.update behavior very handy, and the signature was fairly self-explanatory for me. Though, I could definitely understand how the signature might be confusing and am all in favor of updating the docs.

update : id -> (Maybe a -> Maybe a) -> Dict id a -> Dict id a
When I first read this signature it struck me as saying: "This item might be in the dictionary. If it's not you can add an item or leave it as nothing. If it is in there, you can look at the item and decide whether you want to update it or remove it altogether. `

[dullbananas]

Change the API for a more Elixir like update : comparable -> v -> (v -> v) -> Dict comparable v -> Dict comparable v. This is less general, but arguably addresses one of the most common usecases much more explicitly:

If this is done, there should also be an updateWithDefault variant