Add contains(_:) methods to (Closed)Range

benchmark/CMakeLists.txt

@@ -159,6 +159,7 @@ set(SWIFT_BENCH_MODULES
     single-source/RandomTree
     single-source/RandomValues
     single-source/RangeAssignment
+    single-source/RangeContains
     single-source/RangeIteration
     single-source/RangeOverlaps
     single-source/RangeReplaceableCollectionPlusDefault

benchmark/single-source/RangeContains.swift

@@ -0,0 +1,96 @@
+//===--- RangeContains.swift ----------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import TestsUtils
+
+public let benchmarks = [
+  BenchmarkInfo(
+    name: "RangeContainsRange",
+    runFunction: run_RangeContainsRange,
+    tags: [.validation, .api],
+    setUpFunction: buildRanges),
+  BenchmarkInfo(
+    name: "RangeContainsClosedRange",
+    runFunction: run_RangeContainsClosedRange,
+    tags: [.validation, .api],
+    setUpFunction: buildRanges),
+  BenchmarkInfo(
+    name: "ClosedRangeContainsRange",
+    runFunction: run_ClosedRangeContainsRange,
+    tags: [.validation, .api],
+    setUpFunction: buildRanges),
+  BenchmarkInfo(
+    name: "ClosedRangeContainsClosedRange",
+    runFunction: run_ClosedRangeContainsClosedRange,
+    tags: [.validation, .api],
+    setUpFunction: buildRanges),
+]
+
+private func buildRanges() {
+  blackHole(ranges)
+  blackHole(closedRanges)
+}
+
+private let ranges: [Range<Int>] = (-8...8).flatMap { a in (0...16).map { l in a..<(a+l) } }
+private let closedRanges: [ClosedRange<Int>] = (-8...8).flatMap { a in (0...16).map { l in a...(a+l) } }
+
+@inline(never)
+public func run_RangeContainsRange(_ n: Int) {
+  var checksum: UInt64 = 0
+  for _ in 0..<n {
+    for lhs in ranges {
+      for rhs in ranges {
+        if lhs.contains(rhs) { checksum += 1 }
+      }
+    }
+  }
+  check(checksum == 15725 * UInt64(n))
+}
+
+@inline(never)
+public func run_RangeContainsClosedRange(_ n: Int) {
+  var checksum: UInt64 = 0
+  for _ in 0..<n {
+    for lhs in ranges {
+      for rhs in closedRanges {
+        if lhs.contains(rhs) { checksum += 1 }
+      }
+    }
+  }
+  check(checksum == 10812 * UInt64(n))
+}
+
+@inline(never)
+public func run_ClosedRangeContainsRange(_ n: Int) {
+  var checksum: UInt64 = 0
+  for _ in 0..<n {
+    for lhs in closedRanges {
+      for rhs in ranges {
+        if lhs.contains(rhs) { checksum += 1 }
+      }
+    }
+  }
+  check(checksum == 17493 * UInt64(n))
+}
+
+@inline(never)
+public func run_ClosedRangeContainsClosedRange(_ n: Int) {
+  var checksum: UInt64 = 0
+  for _ in 0..<n {
+    for lhs in closedRanges {
+      for rhs in closedRanges {
+        if lhs.contains(rhs) { checksum += 1 }
+      }
+    }
+  }
+  check(checksum == 12597 * UInt64(n))
+}

benchmark/utils/main.swift

@@ -163,6 +163,7 @@ import RandomShuffle
 import RandomTree
 import RandomValues
 import RangeAssignment
+import RangeContains
 import RangeIteration
 import RangeOverlaps
 import RangeReplaceableCollectionPlusDefault
@@ -362,6 +363,7 @@ register(RandomShuffle.benchmarks)
 register(RandomTree.benchmarks)
 register(RandomValues.benchmarks)
 register(RangeAssignment.benchmarks)
+register(RangeContains.benchmarks)
 register(RangeIteration.benchmarks)
 register(RangeOverlaps.benchmarks)
 register(RangeReplaceableCollectionPlusDefault.benchmarks)

stdlib/public/core/ClosedRange.swift

@@ -325,6 +325,64 @@ where Bound: Strideable, Bound.Stride: SignedInteger
     // The first and last elements are the same because each element is unique.
     return _customIndexOfEquatableElement(element)
   }
+
+  /// Returns a Boolean value indicating whether the given range is contained
+  /// within this closed range.
+  ///
+  /// The given range is contained within this closed range if the elements of
+  /// the range are all contained within this closed range.
+  ///
+  ///     let range = 0...10
+  ///     range.contains(5..<7)     // true
+  ///     range.contains(5..<10)    // true
+  ///     range.contains(5..<12)    // false
+  ///
+  ///     // Note that `5..<11` contains 5, 6, 7, 8, 9, and 10.
+  ///     range.contains(5..<11)    // true
+  ///
+  /// Additionally, passing any empty range as `other` results in the value
+  /// `true`, even if the empty range's bounds are outside the bounds of this
+  /// closed range.
+  ///
+  ///     range.contains(3..<3)     // true
+  ///     range.contains(20..<20)   // true
+  ///
+  /// - Parameter other: A range to check for containment within this closed
+  ///   range.
+  /// - Returns: `true` if `other` is empty or wholly contained within this
+  ///   closed range; otherwise, `false`.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  public func contains(_ other: Range<Bound>) -> Bool {
+    if other.isEmpty { return true }
+    let otherInclusiveUpper = other.upperBound.advanced(by: -1)
+    return lowerBound <= other.lowerBound && upperBound >= otherInclusiveUpper
+  }
+}
+
+extension ClosedRange {
+  /// Returns a Boolean value indicating whether the given closed range is
+  /// contained within this closed range.
+  ///
+  /// The given closed range is contained within this range if its bounds are
+  /// contained within this closed range.
+  ///
+  ///     let range = 0...10
+  ///     range.contains(2...5)        // true
+  ///     range.contains(2...10)       // true
+  ///     range.contains(2...12)       // false
+  ///
+  /// - Parameter other: A closed range to check for containment within this
+  ///   closed range.
+  /// - Returns: `true` if `other` is wholly contained within this closed range;
+  ///   otherwise, `false`.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  public func contains(_ other: ClosedRange<Bound>) -> Bool {
+    lowerBound <= other.lowerBound && upperBound >= other.upperBound
+  }
 }
 
 extension Comparable {  
@@ -459,6 +517,18 @@ extension ClosedRange where Bound: Strideable, Bound.Stride: SignedInteger {
 }
 
 extension ClosedRange {
+  /// Returns a Boolean value indicating whether this range and the given closed
+  /// range contain an element in common.
+  ///
+  /// This example shows two overlapping ranges:
+  ///
+  ///     let x: Range = 0...20
+  ///     print(x.overlaps(10...1000))
+  ///     // Prints "true"
+  ///
+  /// - Parameter other: A range to check for elements in common.
+  /// - Returns: `true` if this range and `other` have at least one element in
+  ///   common; otherwise, `false`.
   @inlinable
   public func overlaps(_ other: ClosedRange<Bound>) -> Bool {
     // Disjoint iff the other range is completely before or after our range.
@@ -469,6 +539,25 @@ extension ClosedRange {
     return !isDisjoint
   }
 
+  /// Returns a Boolean value indicating whether this range and the given range
+  /// contain an element in common.
+  ///
+  /// This example shows two overlapping ranges:
+  ///
+  ///     let x: Range = 0...20
+  ///     print(x.overlaps(10..<1000))
+  ///     // Prints "true"
+  ///
+  /// Because a closed range includes its upper bound, the ranges in the
+  /// following example overlap:
+  ///
+  ///     let y = 20..<30
+  ///     print(x.overlaps(y))
+  ///     // Prints "true"
+  ///
+  /// - Parameter other: A range to check for elements in common.
+  /// - Returns: `true` if this range and `other` have at least one element in
+  ///   common; otherwise, `false`.
   @inlinable
   public func overlaps(_ other: Range<Bound>) -> Bool {
     return other.overlaps(self)

stdlib/public/core/Range.swift

@@ -986,7 +986,7 @@ extension Range {
   /// This example shows two overlapping ranges:
   ///
   ///     let x: Range = 0..<20
-  ///     print(x.overlaps(10...1000))
+  ///     print(x.overlaps(10..<1000))
   ///     // Prints "true"
   ///
   /// Because a half-open range does not include its upper bound, the ranges
@@ -1011,6 +1011,25 @@ extension Range {
     return !isDisjoint
   }
 
+  /// Returns a Boolean value indicating whether this range and the given closed
+  /// range contain an element in common.
+  ///
+  /// This example shows two overlapping ranges:
+  ///
+  ///     let x: Range = 0..<20
+  ///     print(x.overlaps(10...1000))
+  ///     // Prints "true"
+  ///
+  /// Because a half-open range does not include its upper bound, the ranges
+  /// in the following example do not overlap:
+  ///
+  ///     let y = 20...30
+  ///     print(x.overlaps(y))
+  ///     // Prints "false"
+  ///
+  /// - Parameter other: A closed range to check for elements in common.
+  /// - Returns: `true` if this range and `other` have at least one element in
+  ///   common; otherwise, `false`.
   @inlinable
   public func overlaps(_ other: ClosedRange<Bound>) -> Bool {
     // Disjoint iff the other range is completely before or after our range.
@@ -1024,6 +1043,64 @@ extension Range {
   }
 }
 
+extension Range {
+  /// Returns a Boolean value indicating whether the given range is contained
+  /// within this range.
+  ///
+  /// The given range is contained within this range if its bounds are equal to
+  /// or within the bounds of this range.
+  ///
+  ///     let range = 0..<10
+  ///     range.contains(2..<5)        // true
+  ///     range.contains(2..<10)       // true
+  ///     range.contains(2..<12)       // false
+  ///
+  /// Additionally, passing any empty range as `other` results in the value
+  /// `true`, even if the empty range's bounds are outside the bounds of this
+  /// range.
+  ///
+  ///     let emptyRange = 3..<3
+  ///     emptyRange.contains(3..<3)   // true
+  ///     emptyRange.contains(5..<5)   // true
+  ///
+  /// - Parameter other: A range to check for containment within this range.
+  /// - Returns: `true` if `other` is empty or wholly contained within this
+  ///   range; otherwise, `false`.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  public func contains(_ other: Range<Bound>) -> Bool {
+    other.isEmpty ||
+      (lowerBound <= other.lowerBound && upperBound >= other.upperBound)
+  }
+
+  /// Returns a Boolean value indicating whether the given closed range is
+  /// contained within this range.
+  ///
+  /// The given closed range is contained within this range if its bounds are
+  /// contained within this range. If this range is empty, it cannot contain a
+  /// closed range, since closed ranges by definition contain their boundaries.
+  ///
+  ///     let range = 0..<10
+  ///     range.contains(2...5)        // true
+  ///     range.contains(2...10)       // false
+  ///     range.contains(2...12)       // false
+  ///
+  ///     let emptyRange = 3..<3
+  ///     emptyRange.contains(3...3)   // false
+  ///
+  /// - Parameter other: A closed range to check for containment within this
+  ///   range.
+  /// - Returns: `true` if `other` is wholly contained within this range;
+  ///   otherwise, `false`.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  public func contains(_ other: ClosedRange<Bound>) -> Bool {
+    lowerBound <= other.lowerBound && upperBound > other.upperBound
+  }
+}
+
 // Note: this is not for compatibility only, it is considered a useful
 // shorthand. TODO: Add documentation
 public typealias CountableRange<Bound: Strideable> = Range<Bound>