maps: new package to provide generic map functions

[rsc]

Discussed in #47330

// Package maps defines various functions useful with maps of any type.
package maps

// Keys returns the keys of the map m.
// The keys will be an indeterminate order.
func Keys[M constraints.Map[K, V], K comparable, V any](m M) []K

// Values returns the values of the map m.
// The values will be in an indeterminate order.
func Values[M constraints.Map[K, V], K comparable, V any](m M) []V

// Equal reports whether two maps contain the same key/value pairs.
// Values are compared using ==.
func Equal[M1, M2 constraints.Map[K, V], K, V comparable](m1 M1, m2 M2) bool

// EqualFunc is like Equal, but compares values using cmp.
// Keys are still compared with ==.
func EqualFunc[M1 constraints.Map[K, V1], M2 constraints.Map[K, V2], K comparable, V1, V2 any](m1 m1, m2 M2, cmp func(V1, V2) bool) bool

// Clear removes all entries from m, leaving it empty.
func Clear[M constraints.Map[K, V], K comparable, V any](m M)

// Clone returns a copy of m.  This is a shallow clone:
// the new keys and values are set using ordinary assignment.
func Clone[M constraints.Map[K, V], K comparable, V any](m M) M

// Copy copies all key/value pairs in src adding them to dst.
// When a key in src is already present in dst,
// the value in dst will be overwritten by the value associated
// with the key in src.
func Copy[M constraints.Map[K, V], K comparable, V any](dst, src M)

// DeleteFunc deletes any key/value pairs from m for which del returns true.
func DeleteFunc[M constraints.Map[K, V], K comparable, V any](m M, del func(K, V) bool)

[hherman1]

These look pretty good to me, I only really paused over the Keys and Values functions: how often are these used where you wouldn’t be better served by a for range loop?

[ianlancetaylor]

I think that Keys and Values would be used quite a lot. For example, Keys is naturally used when removing duplicate elements from a slice.

func RemoveDuplicates(s []someType) []someType {
    m := make(map[someType]bool)
    for _, v := range s {
        m[v] = true
    }
    return maps.Keys(m)

[tusharsingh]

Instead of Add have you considered that Copy may be clearer? Copy implies copying from a src to dst and overwriting values.

[pcman312]

Add is a bit unclear in my opinion because it makes it sound like you're adding an individual entry (or entries). What about Merge instead?

[ianlancetaylor]

It would be best if discussion about this proposal continues on the existing discussion at #47330. Decisions made there will be reflected here. I'm going to lock this issue temporarily. Thanks.

[rsc]

Discussion on #47330 seems to have converged. I've copied the latest API into the top comment on this issue. Any comments should still be made on #47330, not here.

[rsc]

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group