ClosedRange

struct ClosedRange

An interval from a lower bound up to, and including, an upper bound.

Inheritance CustomDebugStringConvertible, CustomReflectable, CustomStringConvertible, Equatable, RangeExpression

You create a ClosedRange instance by using the closed range operator (...).

let throughFive = 0...5

A ClosedRange instance contains both its lower bound and its upper bound.

throughFive.contains(3)
// true
throughFive.contains(10)
// false
throughFive.contains(5)
// true

Because a closed range includes its upper bound, a closed range whose lower bound is equal to the upper bound contains that value. Therefore, a ClosedRange instance cannot represent an empty range.

let zeroInclusive = 0...0
zeroInclusive.contains(0)
// true
zeroInclusive.isEmpty
// false

Using a Closed Range as a Collection of Consecutive Values

When a closed range uses integers as its lower and upper bounds, or any other type that conforms to the Strideable protocol with an integer stride, you can use that range in a for-in loop or with any sequence or collection method. The elements of the range are the consecutive values from its lower bound up to, and including, its upper bound.

for n in 3...5 {
    print(n)
}
// Prints "3"
// Prints "4"
// Prints "5"

Because floating-point types such as Float and Double are their own Stride types, they cannot be used as the bounds of a countable range. If you need to iterate over consecutive floating-point values, see the stride(from:through:by:) function.

Initializers

init init(uncheckedBounds:) Required

Creates an instance with the given bounds.

Because this initializer does not perform any checks, it should be used as an optimization only when you are absolutely certain that lower is less than or equal to upper. Using the closed range operator (...) to form ClosedRange instances is preferred.

  • Parameter bounds: A tuple of the lower and upper bounds of the range.

Declaration

@inlinable public init(uncheckedBounds bounds: (lower: Bound, upper: Bound))

Instance Variables

var customMirror Required

The custom mirror for this instance.

If this type has value semantics, the mirror should be unaffected by subsequent mutations of the instance.

Declaration

var customMirror: Mirror
var debugDescription Required

A textual representation of the range, suitable for debugging.

Declaration

var debugDescription: String
var description Required

A textual representation of the range.

Declaration

var description: String
var isEmpty Required

A Boolean value indicating whether the range contains no elements.

Because a closed range cannot represent an empty range, this property is always false.

Declaration

var isEmpty: Bool
let lowerBound Required

The range's lower bound.

Declaration

let lowerBound: Bound
let upperBound Required

The range's upper bound.

Declaration

let upperBound: Bound

Instance Methods

func clamped(to limits: ClosedRange<Bound>) -> ClosedRange<Bound> Required

Returns a copy of this range clamped to the given limiting range.

The bounds of the result are always limited to the bounds of limits. For example:

let x: ClosedRange = 0...20
print(x.clamped(to: 10...1000))
// Prints "10...20"

If the two ranges do not overlap, the result is a single-element range at the upper or lower bound of limits.

let y: ClosedRange = 0...5
print(y.clamped(to: 10...1000))
// Prints "10...10"
  • Parameter limits: The range to clamp the bounds of this range.

Declaration

@inlinable public func clamped(to limits: ClosedRange<Bound>) -> ClosedRange<Bound>
func contains(_ element: Bound) -> Bool Required

Returns a Boolean value indicating whether the given element is contained within the range.

A ClosedRange instance contains both its lower and upper bound. element is contained in the range if it is between the two bounds or equal to either bound.

  • Parameter element: The element to check for containment.

Declaration

@inlinable public func contains(_ element: Bound) -> Bool
func overlaps(_ other: ClosedRange<Bound>) -> Bool Required

Declaration

@inlinable public func overlaps(_ other: ClosedRange<Bound>) -> Bool
func overlaps(_ other: Range<Bound>) -> Bool Required

Declaration

@inlinable public func overlaps(_ other: Range<Bound>) -> Bool
func relative(to collection: C) -> Range<Bound> Required

Returns the range of indices described by this range expression within the given collection.

You can use the relative(to:) method to convert a range expression, which could be missing one or both of its endpoints, into a concrete range that is bounded on both sides. The following example uses this method to convert a partial range up to 4 into a half-open range, using an array instance to add the range's lower bound.

let numbers = [10, 20, 30, 40, 50, 60, 70]
let upToFour = ..<4

let r1 = upToFour.relative(to: numbers)
// r1 == 0..<4

The r1 range is bounded on the lower end by 0 because that is the starting index of the numbers array. When the collection passed to relative(to:) starts with a different index, that index is used as the lower bound instead. The next example creates a slice of numbers starting at index 2, and then uses the slice with relative(to:) to convert upToFour to a concrete range.

let numbersSuffix = numbers[2...]
// numbersSuffix == [30, 40, 50, 60, 70]

let r2 = upToFour.relative(to: numbersSuffix)
// r2 == 2..<4

Use this method only if you need the concrete range it produces. To access a slice of a collection using a range expression, use the collection's generic subscript that uses a range expression as its parameter.

let numbersPrefix = numbers[upToFour]
// numbersPrefix == [10, 20, 30, 40]
  • Parameter collection: The collection to evaluate this range expression in relation to.

Declaration

@inlinable public func relative<C>(to collection: C) -> Range<Bound> where Bound == C.Index, C: Collection

Type Methods

func !=(lhs: Self, rhs: Self) -> Bool Required

Declaration

public static func !=(lhs: Self, rhs: Self) -> Bool
func ==(lhs: ClosedRange<Bound>, rhs: ClosedRange<Bound>) -> Bool Required

Returns a Boolean value indicating whether two ranges are equal.

Two ranges are equal when they have the same lower and upper bounds.

let x = 5...15
print(x == 5...15)
// Prints "true"
print(x == 10...20)
// Prints "false"

Declaration

@inlinable public static func ==(lhs: ClosedRange<Bound>, rhs: ClosedRange<Bound>) -> Bool
func ~=(pattern: Self, value: Self.Bound) -> Bool Required

Declaration

@inlinable public static func ~=(pattern: Self, value: Self.Bound) -> Bool