✨ [collection] Add matching helpers for collection lookups that can be used in switch statements. (#840)

Adding some matching helpers over collection so they can be used in
`switch` statements and therefore, avoid a lot of `||` statements

Author: acabarbaye

changes/20260401153128.feature

@@ -0,0 +1 @@
+:sparkles: [`collection`] Add matching helpers for collection lookups that can be used in `switch` statements.

utils/collection/filter.go

@@ -2,7 +2,9 @@ package collection
 
 import (
 	"iter"
+	"regexp"
 	"slices"
+	"strings"
 
 	"github.com/ARM-software/golang-utils/utils/field"
 )
@@ -34,6 +36,53 @@ func toPredicateFunc[E any](f PredicateRef[E]) Predicate[E] {
 	}
 }
 
+// MatchFunc compares two values of type E and reports whether they match.
+// It may return an error if the comparison requires additional processing,
+// such as compiling or evaluating a regular expression.
+type MatchFunc[E any] func(E, E) (bool, error)
+
+// MatchRefFunc compares two references to values of type E and reports whether
+// they match. It may return an error if the comparison requires additional
+// processing before the match can be determined.
+type MatchRefFunc[E any] func(*E, *E) (bool, error)
+
+func matchToPredicateFunc[E any](v E, matchFunc MatchFunc[E]) Predicate[E] {
+	return func(e E) bool {
+		matched, err := matchFunc(v, e)
+		return matched && err == nil
+	}
+}
+
+func matchToPredicateRefFunc[E any](v *E, matchFunc MatchRefFunc[E]) PredicateRef[E] {
+	return func(e *E) bool {
+		matched, err := matchFunc(v, e)
+		return matched && err == nil
+	}
+}
+
+// StringMatch reports whether two strings are exactly equal.
+var StringMatch MatchFunc[string] = func(a, b string) (bool, error) { return a == b, nil }
+
+// StringCaseInsensitiveMatch reports whether two strings are equal but ignoring their case.
+var StringCaseInsensitiveMatch MatchFunc[string] = func(a, b string) (bool, error) { return strings.EqualFold(a, b), nil }
+
+// StringCleanCaseInsensitiveMatch reports whether two strings are equal after
+// trimming surrounding whitespace and ignoring their case.
+var StringCleanCaseInsensitiveMatch MatchFunc[string] = func(a, b string) (bool, error) {
+	return StringCaseInsensitiveMatch(strings.TrimSpace(a), strings.TrimSpace(b))
+}
+
+// StringCleanMatch reports whether two strings are exactly equal after trimming
+// surrounding whitespace.
+var StringCleanMatch MatchFunc[string] = func(a, b string) (bool, error) { return StringMatch(strings.TrimSpace(a), strings.TrimSpace(b)) }
+
+// StringRegexMatch reports whether a string matches the provided regular expression pattern.
+// the pattern being the first argument.
+var StringRegexMatch MatchFunc[string] = regexp.MatchString
+
+// StrictRefMatch reports whether two references are equal using field.Equal.
+func StrictRefMatch[E comparable](a, b *E) (bool, error) { return field.Equal(a, b), nil }
+
 //
 // Rejection / Filtering
 //

utils/collection/find.go

@@ -25,7 +25,7 @@ func Find(slice *[]string, val string) (int, bool) {
 }
 
 // FindInSequence searches elements (a sequence) for the first item that
-// satisfies predicate. It returns the zero-based index of the matching
+// satisfies the predicate. It returns the zero-based index of the matching
 // element and true when a match is found. If elements is nil or no
 // match exists, it returns -1 and false.
 func FindInSequence[E any](elements iter.Seq[E], predicate Predicate[E]) (int, bool) {

utils/collection/match.go

@@ -1,5 +1,10 @@
 package collection
 
+import (
+	"iter"
+	"slices"
+)
+
 //
 // Match utilities
 //
@@ -22,3 +27,43 @@ func Match[E any](e E, matches ...FilterFunc[E]) bool {
 func MatchAll[E any](e E, matches ...FilterFunc[E]) bool {
 	return match[E](e, matches).All()
 }
+
+// InSequence reports whether any element in s matches v using any of the
+// provided match functions. Match functions that return an error are treated
+// as non-matches.
+func InSequence[E any](s iter.Seq[E], v E, m ...MatchFunc[E]) bool {
+	matching := Map(m, func(mf MatchFunc[E]) Predicate[E] {
+		return matchToPredicateFunc(v, mf)
+	})
+	return matchInSeq(s, matching)
+}
+
+// InSequenceRef behaves like InSequence but uses reference-based match
+// functions and a reference value.
+func InSequenceRef[E any](s iter.Seq[E], v *E, m ...MatchRefFunc[E]) bool {
+	matching := Map(m, func(mf MatchRefFunc[E]) Predicate[E] {
+		return toPredicateFunc(matchToPredicateRefFunc(v, mf))
+	})
+	return matchInSeq(s, matching)
+}
+
+// In reports whether any element in s matches v using any of the provided
+// match functions. Match functions that return an error are treated as
+// non-matches.
+func In[Slice ~[]E, E any](s Slice, v E, m ...MatchFunc[E]) bool {
+	return InSequence(slices.Values(s), v, m...)
+}
+
+// InRef behaves like In but uses reference-based match functions and a
+// reference value.
+func InRef[Slice ~[]E, E any](s Slice, v *E, m ...MatchRefFunc[E]) bool {
+	return InSequenceRef(slices.Values(s), v, m...)
+}
+
+func matchInSeq[E any](s iter.Seq[E], matching []Predicate[E]) bool {
+	matchingF := func(e E) bool {
+		return Match(e, matching...)
+	}
+	_, found := FindInSequence(s, matchingF)
+	return found
+}

utils/collection/match_test.go

@@ -0,0 +1,65 @@
+package collection
+
+import (
+	"iter"
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/ARM-software/golang-utils/utils/commonerrors"
+)
+
+func TestInSequence(t *testing.T) {
+	values := []string{"alpha", "Beta", "gamma"}
+
+	assert.True(t, InSequence(slices.Values(values), " beta ", StringCleanCaseInsensitiveMatch))
+	assert.False(t, InSequence(slices.Values(values), "beta", StringCleanMatch))
+	assert.False(t, InSequence(slices.Values(values), "delta", StringCleanCaseInsensitiveMatch))
+
+	var nilSeq iter.Seq[string]
+	assert.False(t, InSequence(nilSeq, "alpha", StringMatch))
+
+	errMatch := func(pattern, value string) (bool, error) {
+		return true, commonerrors.ErrUnexpected
+	}
+	assert.False(t, InSequence(slices.Values(values), "alpha", errMatch))
+}
+
+func TestInSequenceRef(t *testing.T) {
+	values := []int{1, 2, 3}
+	target := 2
+
+	assert.True(t, InSequenceRef(slices.Values(values), &target, StrictRefMatch))
+
+	missing := 4
+	assert.False(t, InSequenceRef(slices.Values(values), &missing, StrictRefMatch))
+	assert.False(t, InSequenceRef(slices.Values(values), &target, func(a, b *int) (bool, error) {
+		return true, commonerrors.ErrUnexpected
+	}))
+
+	var nilSeq iter.Seq[int]
+	assert.False(t, InSequenceRef(nilSeq, &target, StrictRefMatch))
+}
+
+func TestIn(t *testing.T) {
+	values := []string{"alpha", "beta", "gamma"}
+
+	assert.True(t, In(values, "^be", StringRegexMatch))
+	assert.False(t, In(values, "^de", StringRegexMatch))
+	assert.True(t, In(values, "BETA", StringCaseInsensitiveMatch))
+	assert.True(t, In(values, ".+ta.*", StringRegexMatch))
+}
+
+func TestInRef(t *testing.T) {
+	values := []string{"alpha", "beta", "gamma"}
+	target := "beta"
+
+	assert.True(t, InRef(values, &target, StrictRefMatch))
+
+	missing := "delta"
+	assert.False(t, InRef(values, &missing, StrictRefMatch))
+	assert.False(t, InRef(values, &target, func(a, b *string) (bool, error) {
+		return true, commonerrors.ErrUnexpected
+	}))
+}