utils: Add IterateOrderedMap

This change was the result of investigating Go's new rangefunc
experiment[0]. The utilization of this novel language feature - which can
also be indirectly used in the absence of `GOEXPERIMENT=rangefunc` - ensures
that the map is traversed in key order.

[0]: https://go.dev/wiki/RangefuncExperiment

Imported from Icinga/icinga-notifications@e371553

Author: oxzi

utils/utils.go

@@ -1,6 +1,7 @@
 package utils
 
 import (
+	"cmp"
 	"context"
 	"crypto/sha1" // #nosec G505 -- Blocklisted import crypto/sha1
 	"fmt"
@@ -11,6 +12,7 @@ import (
 	"net"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"time"
 )
@@ -163,3 +165,27 @@ func PrintErrorThenExit(err error, exitCode int) {
 	fmt.Fprintln(os.Stderr, err)
 	os.Exit(exitCode)
 }
+
+// IterateOrderedMap implements iter.Seq2 to iterate over a map in the key's order.
+//
+// This function returns a func yielding key-value-pairs from a given map in the order of their keys, if their type
+// is cmp.Ordered.
+//
+// Please note that currently - being at Go 1.22 - rangefuncs are still an experimental feature and cannot be directly
+// used unless compiled with `GOEXPERIMENT=rangefunc`. However, they can still be invoked normally.
+// https://go.dev/wiki/RangefuncExperiment
+func IterateOrderedMap[K cmp.Ordered, V any](m map[K]V) func(func(K, V) bool) {
+	keys := make([]K, 0, len(m))
+	for key := range m {
+		keys = append(keys, key)
+	}
+	slices.Sort(keys)
+
+	return func(yield func(K, V) bool) {
+		for _, key := range keys {
+			if !yield(key, m[key]) {
+				return
+			}
+		}
+	}
+}

utils/utils_test.go

@@ -1,6 +1,7 @@
 package utils
 
 import (
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"testing"
 )
@@ -52,3 +53,52 @@ func requireClosedEmpty(t *testing.T, ch <-chan int) {
 		require.Fail(t, "receiving should not block")
 	}
 }
+
+func TestIterateOrderedMap(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      map[int]string
+		outKeys []int
+	}{
+		{"empty", map[int]string{}, nil},
+		{"single", map[int]string{1: "foo"}, []int{1}},
+		{"few-numbers", map[int]string{1: "a", 2: "b", 3: "c"}, []int{1, 2, 3}},
+		{
+			"1k-numbers",
+			func() map[int]string {
+				m := make(map[int]string)
+				for i := 0; i < 1000; i++ {
+					m[i] = "foo"
+				}
+				return m
+			}(),
+			func() []int {
+				keys := make([]int, 1000)
+				for i := 0; i < 1000; i++ {
+					keys[i] = i
+				}
+				return keys
+			}(),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var outKeys []int
+
+			// Either run with GOEXPERIMENT=rangefunc or wait for rangefuncs to land in the next Go release.
+			// for k, _ := range IterateOrderedMap(tt.in) {
+			// 	outKeys = append(outKeys, k)
+			// }
+
+			// In the meantime, it can be invoked as follows.
+			IterateOrderedMap(tt.in)(func(k int, v string) bool {
+				assert.Equal(t, tt.in[k], v)
+				outKeys = append(outKeys, k)
+				return true
+			})
+
+			assert.Equal(t, tt.outKeys, outKeys)
+		})
+	}
+}