spanset: Add overlaps() helper function, and add tests for Contains and Overlaps

Analogous to how we have a spanset helper contains() that
understands the special span representation: [x-eps,x).
This commit adds another helper to detect overlapping spans.

Moreover, this commit adds tests to verify the behaviour of
these two helper functions.

References: #156537

Release note: None

Author: iskettaneh

pkg/kv/kvserver/spanset/spanset.go

@@ -370,7 +370,7 @@ func (s *SpanSet) checkAllowed(
 
 		for ac := access; ac < NumSpanAccess; ac++ {
 			for _, cur := range s.spans[ac][scope] {
-				if contains(cur.Span, span) && check(ac, cur) {
+				if Contains(cur.Span, span) && check(ac, cur) {
 					return nil
 				}
 			}
@@ -382,11 +382,11 @@ func (s *SpanSet) checkAllowed(
 	return nil
 }
 
-// contains returns whether s1 contains s2. Unlike Span.Contains, this function
+// Contains returns whether s1 contains s2. Unlike Span.Contains, this function
 // supports spans with a nil start key and a non-nil end key (e.g. "[nil, c)").
 // In this form, s2.Key (inclusive) is considered to be the previous key to
 // s2.EndKey (exclusive).
-func contains(s1, s2 roachpb.Span) bool {
+func Contains(s1, s2 roachpb.Span) bool {
 	if s2.Key != nil {
 		// The common case.
 		return s1.Contains(s2)
@@ -402,6 +402,26 @@ func contains(s1, s2 roachpb.Span) bool {
 	return s1.Key.Compare(s2.EndKey) < 0 && s1.EndKey.Compare(s2.EndKey) >= 0
 }
 
+// Overlaps returns whether s1 overlaps s2. Unlike Span.Overlaps, this function
+// supports spans with a nil start key and a non-nil end key (e.g. "[nil, c)").
+// In this form, s2.Key (inclusive) is considered to be the previous key to
+// s2.EndKey (exclusive).
+func Overlaps(s1, s2 roachpb.Span) bool {
+	if s2.Key != nil {
+		// The common case.
+		return s1.Overlaps(s2)
+	}
+
+	// The following is equivalent to:
+	//   s1.Overlaps(roachpb.Span{Key: s2.EndKey.Prev()})
+
+	if s1.EndKey == nil {
+		return s1.Key.IsPrev(s2.EndKey)
+	}
+
+	return s1.Key.Compare(s2.EndKey) < 0 && s1.EndKey.Compare(s2.EndKey) >= 0
+}
+
 // Validate returns an error if any spans that have been added to the set
 // are invalid.
 func (s *SpanSet) Validate() error {

pkg/kv/kvserver/spanset/spanset_test.go

@@ -394,3 +394,201 @@ func TestSpanSetWriteImpliesRead(t *testing.T) {
 		t.Errorf("expected to be allowed to read rwSpan, error: %+v", err)
 	}
 }
+
+// Test that Contains correctly determines if s1 contains s2, including
+// support for spans with nil start/end keys.
+func TestContains(t *testing.T) {
+	defer leaktest.AfterTest(t)()
+
+	testCases := []struct {
+		name     string
+		s1       roachpb.Span
+		s2       roachpb.Span
+		expected bool
+	}{
+		{
+			name:     "s1 contains s2 exactly",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			expected: true,
+		},
+		{
+			name:     "s1 contains s2",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("c")},
+			expected: true,
+		},
+		{
+			name:     "s1 contains s2 start point span",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{Key: roachpb.Key("a")},
+			expected: true,
+		},
+		{
+			name:     "s1 contains s2 end point span",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{EndKey: roachpb.Key("d")},
+			expected: true,
+		},
+		{
+			name:     "s1 point contains s2 point same key",
+			s1:       roachpb.Span{Key: roachpb.Key("a")},
+			s2:       roachpb.Span{Key: roachpb.Key("a")},
+			expected: true,
+		},
+		{
+			name:     "s1 does not contain s2 - disjoint",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("d"), EndKey: roachpb.Key("f")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not contain s2 - partial overlap",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not contain s2 - s2 larger",
+			s1:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not contain s2 point - outside range",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 with nil end does not contain disjoint span",
+			s1:       roachpb.Span{Key: roachpb.Key("a")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 with nil start does not contain disjoint span",
+			s1:       roachpb.Span{EndKey: roachpb.Key("b")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 with nil end does not contain s2 with nil start",
+			s1:       roachpb.Span{Key: roachpb.Key("a")},
+			s2:       roachpb.Span{Key: roachpb.Key("b")},
+			expected: false,
+		},
+		{
+			name:     "s1 with nil start does not contain s2 with nil end",
+			s1:       roachpb.Span{EndKey: roachpb.Key("a")},
+			s2:       roachpb.Span{EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			require.Equal(t, tc.expected, Contains(tc.s1, tc.s2))
+		})
+	}
+}
+
+// Test that Overlaps correctly determines if s1 overlaps s2, including
+// support for spans with nil start/end keys.
+func TestOverlaps(t *testing.T) {
+	defer leaktest.AfterTest(t)()
+
+	testCases := []struct {
+		name     string
+		s1       roachpb.Span
+		s2       roachpb.Span
+		expected bool
+	}{
+		{
+			name:     "s1 overlaps s2 exactly",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			expected: true,
+		},
+		{
+			name:     "s1 overlaps s2 partial",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("d")},
+			expected: true,
+		},
+		{
+			name:     "s1 contains s2",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("c")},
+			expected: true,
+		},
+		{
+			name:     "s2 contains s1",
+			s1:       roachpb.Span{Key: roachpb.Key("b"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			expected: true,
+		},
+		{
+			name:     "s1 overlaps s2 with nil end",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{Key: roachpb.Key("a")},
+			expected: true,
+		},
+		{
+			name:     "s1 overlaps s2 with nil start",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("d")},
+			s2:       roachpb.Span{EndKey: roachpb.Key("d")},
+			expected: true,
+		},
+		{
+			name:     "s1 point overlaps s2 point same key",
+			s1:       roachpb.Span{Key: roachpb.Key("a")},
+			s2:       roachpb.Span{Key: roachpb.Key("a")},
+			expected: true,
+		},
+		{
+			name:     "s1 point overlaps s2 point same end key",
+			s1:       roachpb.Span{EndKey: roachpb.Key("a")},
+			s2:       roachpb.Span{EndKey: roachpb.Key("a")},
+			expected: true,
+		},
+		{
+			name:     "s1 does not overlap s2",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("d"), EndKey: roachpb.Key("f")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not overlap s2 - adjacent",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("c"), EndKey: roachpb.Key("d")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not overlap s2 with nil end key",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{Key: roachpb.Key("c")},
+			expected: false,
+		},
+		{
+			name:     "s1 does not overlap s2 with nil start key",
+			s1:       roachpb.Span{Key: roachpb.Key("a"), EndKey: roachpb.Key("c")},
+			s2:       roachpb.Span{EndKey: roachpb.Key("a")},
+			expected: false,
+		},
+		{
+			name:     "s1 point does not overlap s2 - different keys",
+			s1:       roachpb.Span{Key: roachpb.Key("a")},
+			s2:       roachpb.Span{Key: roachpb.Key("b")},
+			expected: false,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			require.Equal(t, tc.expected, Overlaps(tc.s1, tc.s2))
+			// Overlaps should be commutative.
+			require.Equal(t, Overlaps(tc.s1, tc.s2), Overlaps(tc.s2, tc.s1))
+		})
+	}
+}