sets and maps: ensure all funcs are sorted

Author: orsinium

maps/maps.go

@@ -56,6 +56,18 @@ func HasValue[M ~map[K]V, K, V comparable](items M, val V) bool {
 	return false
 }
 
+// Keys returns the keys of the given map.
+//
+// The resulting keys order is unknown. You cannot rely on it in any way,
+// even on it being random.
+func Keys[M ~map[K]V, K comparable, V any](items M) []K {
+	result := make([]K, 0, len(items))
+	for key := range items {
+		result = append(result, key)
+	}
+	return result
+}
+
 // Map calls the given function `f` with each key and value and makes a new map
 // out of key-value pairs returned by the function.
 func Map[M ~map[K]V, K, RK comparable, V, RV any](items M, f func(K, V) (RK, RV)) map[RK]RV {
@@ -119,18 +131,6 @@ func MergeBy[M1, M2 ~map[K]V, K, V comparable](items1 M1, items2 M2, f func(K, V
 	return result
 }
 
-// Keys returns the keys of the given map.
-//
-// The resulting keys order is unknown. You cannot rely on it in any way,
-// even on it being random.
-func Keys[M ~map[K]V, K comparable, V any](items M) []K {
-	result := make([]K, 0, len(items))
-	for key := range items {
-		result = append(result, key)
-	}
-	return result
-}
-
 // Take returns a copy of the given map containing only the given keys.
 //
 // Keys that aren't in the map are simply ignored.

maps/maps_inplace.go

@@ -21,6 +21,38 @@ func Drop[M ~map[K]V, K comparable, V any](items M, keys ...K) {
 	}
 }
 
+// IMapValues applies the function to the map values.
+//
+// This is an in-place operation. It modifies `items` map in-place.
+// If you want to create a new map, use [MapValues] instead.
+func IMapValues[M ~map[K]V, K comparable, V any](items M, f func(V) V) {
+	for key, value := range items {
+		items[key] = f(value)
+	}
+}
+
+// IMerge adds items from the second map to the first one.
+//
+// This is an in-place operation. It modifies `target` map in-place.
+func IMerge[M1, M2 ~map[K]V, K, V comparable](target M1, items M2) {
+	for key, value := range items {
+		target[key] = value
+	}
+}
+
+// IMergeBy is like [IMerge] but conflicts are resolved by the function `f`.
+//
+// This is an in-place operation. It modifies `target` map in-place.
+func IMergeBy[M1, M2 ~map[K]V, K, V comparable](target M1, items M2, f func(K, V, V) V) {
+	for key, value2 := range items {
+		value1, contains := target[key]
+		if contains {
+			value2 = f(key, value1, value2)
+		}
+		target[key] = value2
+	}
+}
+
 // LeaveOnly leaves in the given map only the given keys.
 //
 // It is in-place operation, it modifies the original map.
@@ -70,35 +102,3 @@ func Update[M1, M2 ~map[K]V, K, V comparable](items M1, with M2) {
 		items[key] = value
 	}
 }
-
-// IMerge adds items from the second map to the first one.
-//
-// This is an in-place operation. It modifies `target` map in-place.
-func IMerge[M1, M2 ~map[K]V, K, V comparable](target M1, items M2) {
-	for key, value := range items {
-		target[key] = value
-	}
-}
-
-// IMergeBy is like [IMerge] but conflicts are resolved by the function `f`.
-//
-// This is an in-place operation. It modifies `target` map in-place.
-func IMergeBy[M1, M2 ~map[K]V, K, V comparable](target M1, items M2, f func(K, V, V) V) {
-	for key, value2 := range items {
-		value1, contains := target[key]
-		if contains {
-			value2 = f(key, value1, value2)
-		}
-		target[key] = value2
-	}
-}
-
-// IMapValues applies the function to the map values.
-//
-// This is an in-place operation. It modifies `items` map in-place.
-// If you want to create a new map, use [MapValues] instead.
-func IMapValues[M ~map[K]V, K comparable, V any](items M, f func(V) V) {
-	for key, value := range items {
-		items[key] = f(value)
-	}
-}

maps/maps_inplace_test.go

@@ -26,6 +26,38 @@ func TestDrop(t *testing.T) {
 	is.Equal(m, map[int]int{3: 4})
 }
 
+func TestIMapValues(t *testing.T) {
+	is := is.New(t)
+	m := map[int]int32{1: 2, 3: 4, 5: 6}
+	f := func(v int32) int32 {
+		return v * 2
+	}
+	maps.IMapValues(m, f)
+	is.Equal(m, map[int]int32{1: 4, 3: 8, 5: 12})
+}
+
+func TestIMerge(t *testing.T) {
+	is := is.New(t)
+	m1 := map[int]string{1: "one", 2: "two"}
+	m2 := map[int]string{2: "new two", 3: "three"}
+	exp := map[int]string{1: "one", 2: "new two", 3: "three"}
+	maps.IMerge(m1, m2)
+	is.Equal(m1, exp)
+}
+
+func TestIMergeBy(t *testing.T) {
+	is := is.New(t)
+	m1 := map[int]string{1: "one", 2: "two"}
+	m2 := map[int]string{2: "new two", 3: "three"}
+	f := func(k int, a, b string) string {
+		is.Equal(k, 2)
+		return fmt.Sprintf("%s|%s", a, b)
+	}
+	exp := map[int]string{1: "one", 2: "two|new two", 3: "three"}
+	maps.IMergeBy(m1, m2, f)
+	is.Equal(m1, exp)
+}
+
 func TestLeaveOnly(t *testing.T) {
 	is := is.New(t)
 	m := map[int]int{1: 2, 3: 4, 5: 6}
@@ -61,35 +93,3 @@ func TestUpdate(t *testing.T) {
 	maps.Update(m1, m2)
 	is.Equal(m1, map[int]int{1: 2, 3: 5, 6: 7})
 }
-
-func TestIMerge(t *testing.T) {
-	is := is.New(t)
-	m1 := map[int]string{1: "one", 2: "two"}
-	m2 := map[int]string{2: "new two", 3: "three"}
-	exp := map[int]string{1: "one", 2: "new two", 3: "three"}
-	maps.IMerge(m1, m2)
-	is.Equal(m1, exp)
-}
-
-func TestIMergeBy(t *testing.T) {
-	is := is.New(t)
-	m1 := map[int]string{1: "one", 2: "two"}
-	m2 := map[int]string{2: "new two", 3: "three"}
-	f := func(k int, a, b string) string {
-		is.Equal(k, 2)
-		return fmt.Sprintf("%s|%s", a, b)
-	}
-	exp := map[int]string{1: "one", 2: "two|new two", 3: "three"}
-	maps.IMergeBy(m1, m2, f)
-	is.Equal(m1, exp)
-}
-
-func TestIMapValues(t *testing.T) {
-	is := is.New(t)
-	m := map[int]int32{1: 2, 3: 4, 5: 6}
-	f := func(v int32) int32 {
-		return v * 2
-	}
-	maps.IMapValues(m, f)
-	is.Equal(m, map[int]int32{1: 4, 3: 8, 5: 12})
-}

maps/maps_test.go

@@ -35,6 +35,13 @@ func TestEqual(t *testing.T) {
 	is.True(!maps.Equal(map[int]int{1: 2}, map[int]int{2: 1}))
 }
 
+func TestFromKeys(t *testing.T) {
+	is := is.New(t)
+	arr := []int{4, 5, 6}
+	exp := map[int]int{4: 7, 5: 7, 6: 7}
+	is.Equal(maps.FromKeys(arr, 7), exp)
+}
+
 func TestHasKey(t *testing.T) {
 	is := is.New(t)
 	m := map[int]int{1: 2, 3: 4}
@@ -59,11 +66,11 @@ func TestHasValue(t *testing.T) {
 	is.True(!maps.HasValue[map[int]int](nil, 3))
 }
 
-func TestFromKeys(t *testing.T) {
+func TestKeys(t *testing.T) {
 	is := is.New(t)
-	arr := []int{4, 5, 6}
-	exp := map[int]int{4: 7, 5: 7, 6: 7}
-	is.Equal(maps.FromKeys(arr, 7), exp)
+	m := map[int]int{1: 2, 3: 4, 5: 6}
+	act := maps.Keys(m)
+	is.Equal(maps.FromKeys(act, 0), map[int]int{1: 0, 3: 0, 5: 0})
 }
 
 func TestMap(t *testing.T) {
@@ -113,11 +120,10 @@ func TestMergeBy(t *testing.T) {
 	is.Equal(maps.MergeBy(m1, m2, f), exp)
 }
 
-func TestKeys(t *testing.T) {
+func TestTake(t *testing.T) {
 	is := is.New(t)
 	m := map[int]int{1: 2, 3: 4, 5: 6}
-	act := maps.Keys(m)
-	is.Equal(maps.FromKeys(act, 0), map[int]int{1: 0, 3: 0, 5: 0})
+	is.Equal(maps.Take(m, 1, 5), map[int]int{1: 2, 5: 6})
 }
 
 func TestValues(t *testing.T) {
@@ -127,12 +133,6 @@ func TestValues(t *testing.T) {
 	is.Equal(maps.FromKeys(act, 0), map[int]int{2: 0, 4: 0, 6: 0})
 }
 
-func TestTake(t *testing.T) {
-	is := is.New(t)
-	m := map[int]int{1: 2, 3: 4, 5: 6}
-	is.Equal(maps.Take(m, 1, 5), map[int]int{1: 2, 5: 6})
-}
-
 func TestWithout(t *testing.T) {
 	is := is.New(t)
 	m := map[int]int{1: 2, 3: 4, 5: 6}

scripts/test_docs.py

@@ -4,25 +4,29 @@
 import pytest
 
 
-def get_funcs(pkg: str) -> Iterator[str]:
+def get_funcs_for_pkg(pkg: str) -> Iterator[str]:
     for fpath in Path(pkg).iterdir():
         if fpath.suffix != '.go':
             continue
         if fpath.stem.endswith('_test'):
             continue
-        content = fpath.read_text()
-        deprecated = False
-        for line in content.splitlines():
-            if not line.startswith('func '):
-                deprecated = line.startswith('// DEPRECATED')
-                continue
-            line = line.removeprefix('func ')
-            fname = line.split('[')[0].split('(')[0]
-            if deprecated:
-                continue
-            if not fname[0].isupper():
-                continue
-            yield fname
+        yield from get_funcs_for_file(fpath)
+
+
+def get_funcs_for_file(fpath: Path) -> Iterator[str]:
+    content = fpath.read_text()
+    deprecated = False
+    for line in content.splitlines():
+        if not line.startswith('func '):
+            deprecated = line.startswith('// DEPRECATED')
+            continue
+        line = line.removeprefix('func ')
+        fname = line.split('[')[0].split('(')[0]
+        if deprecated:
+            continue
+        if not fname[0].isupper():
+            continue
+        yield fname
 
 
 def get_tests(pkg: str) -> Iterator[str]:
@@ -58,7 +62,7 @@ def get_examples(pkg: str) -> Iterator[str]:
 def test_all_have_examples(pkg: str) -> None:
     """Every function must have an example.
     """
-    funcs = set(get_funcs(pkg))
+    funcs = set(get_funcs_for_pkg(pkg))
     examples = set(get_examples(pkg))
     assert funcs == examples
 
@@ -74,22 +78,32 @@ def test_all_have_examples(pkg: str) -> None:
 def test_all_have_tests(pkg: str) -> None:
     """Every function must have unit tests.
     """
-    funcs = set(get_funcs(pkg))
+    funcs = set(get_funcs_for_pkg(pkg))
     tests = set(get_tests(pkg))
     assert funcs
     diff = funcs - tests
     assert not diff
 
 
-@pytest.mark.parametrize('func', get_funcs('slices'))
+@pytest.mark.parametrize('pkg', [
+    'maps',
+    'sets',
+])
+def test_all_funcs_sorted(pkg: str) -> None:
+    for fpath in Path(pkg).iterdir():
+        funcs = list(get_funcs_for_file(fpath))
+        assert funcs == sorted(funcs)
+
+
+@pytest.mark.parametrize('func', get_funcs_for_pkg('slices'))
 def test_slices_func_linked_in_docs(func: str) -> None:
     """Every func in the slices package must be listed in the package docs.
     """
     docs = Path('slices', 'doc.go').read_text()
     assert f'//   - [{func}](' in docs
 
 
-@pytest.mark.parametrize('func', get_funcs('channels'))
+@pytest.mark.parametrize('func', get_funcs_for_pkg('channels'))
 def test_channels_func_linked_in_docs(func: str) -> None:
     """Every func in the channels package must be listed in the package docs.
     """

sets/examples_test.go

@@ -40,14 +40,6 @@ func ExampleCopy() {
 	// map[3:{} 4:{} 6:{}]
 }
 
-func ExampleDiscard() {
-	s := sets.New(3, 4)
-	sets.Discard(s, 4)
-	sets.Discard(s, 5)
-	fmt.Println(s)
-	// Output: map[3:{}]
-}
-
 func ExampleDifference() {
 	a := sets.New(3, 4, 5)
 	b := sets.New(5, 6, 7)
@@ -56,6 +48,14 @@ func ExampleDifference() {
 	// Output: map[3:{} 4:{}]
 }
 
+func ExampleDiscard() {
+	s := sets.New(3, 4)
+	sets.Discard(s, 4)
+	sets.Discard(s, 5)
+	fmt.Println(s)
+	// Output: map[3:{}]
+}
+
 func ExampleDisjoint() {
 	a := sets.New(3, 4, 5)
 	b := sets.New(5, 6, 7)
@@ -186,6 +186,14 @@ func ExampleSum() {
 	// Output: 12
 }
 
+func ExampleSuperset() {
+	a := sets.New(3, 4, 5, 6)
+	b := sets.New(4, 5)
+	result := sets.Superset(a, b)
+	fmt.Println(result)
+	// Output: true
+}
+
 func ExampleSymmetricDifference() {
 	a := sets.New(3, 4, 5)
 	b := sets.New(5, 6, 7)
@@ -201,14 +209,6 @@ func ExampleToSlice() {
 	// Output: [3]
 }
 
-func ExampleSuperset() {
-	a := sets.New(3, 4, 5, 6)
-	b := sets.New(4, 5)
-	result := sets.Superset(a, b)
-	fmt.Println(result)
-	// Output: true
-}
-
 func ExampleUnion() {
 	a := sets.New(3, 4, 5)
 	b := sets.New(5, 6, 7)