struct ClosedRange<Bound>
Inheritance 
BidirectionalCollection, Collection, CustomDebugStringConvertible, CustomReflectable, CustomStringConvertible, Equatable, Hashable, RandomAccessCollection, RangeExpression, Sequence
View Protocol Hierarchy →


Associated Types 
Element = Bound
A type representing the sequence's elements. Iterator = IndexingIterator<ClosedRange<Bound>>
A type that provides the sequence's iteration interface and encapsulates its iteration state. SubSequence = Slice<ClosedRange<Bound>>
A type that represents a subsequence of some of the sequence's elements. 
Nested Types  ClosedRange.Index 
Import  import Swift 
Initializers
Now that Range is conditionally a collection when Bound: Strideable, CountableRange is no longer needed. This is a deprecated initializer for any remaining uses of Range(countableRange).
Declaration
init(_ other: ClosedRange<ClosedRange<Bound>.Bound>)
Creates an instance equivalent to the given Range
.
other
: A Range
to convert to a ClosedRange
instance.
An equivalent range must be representable as a closed range.
For example, passing an empty range as other
triggers a runtime error,
because an empty range cannot be represented by a closed range instance.
Declaration
init(_ other: Range<ClosedRange<Bound>.Bound>)
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.
bounds
: A tuple of the lower and upper bounds of the range.
Declaration
init(uncheckedBounds bounds: (lower: ClosedRange<Bound>.Bound, upper: ClosedRange<Bound>.Bound))
Instance Variables
The number of elements in the collection.
To check whether a collection is empty, use its isEmpty
property
instead of comparing count
to zero. Unless the collection guarantees
randomaccess performance, calculating count
can be an O(n)
operation.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the length
of the collection.
Declaration
var count: Int { get }
Declared In
BidirectionalCollection
, Collection
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 { get }
A textual representation of the range, suitable for debugging.
Declaration
var debugDescription: String { get }
A textual representation of the range.
Declaration
var description: String { get }
The range's "past the end" positionthat is, the position one greater than the last valid subscript argument.
Declaration
var endIndex: ClosedRange<Bound>.Index { get }
The first element of the collection.
If the collection is empty, the value of this property is nil
.
let numbers = [10, 20, 30, 40, 50]
if let firstNumber = numbers.first {
print(firstNumber)
}
// Prints "10"
Declaration
var first: ClosedRange<Bound>.Element? { get }
Declared In
BidirectionalCollection
, Collection
The hash value.
Hash values are not guaranteed to be equal across different executions of your program. Do not save hash values to use during a future execution.
Declaration
var hashValue: Int { get }
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 { get }
Declared In
ClosedRange
, BidirectionalCollection
, Collection
The last element of the collection.
If the collection is empty, the value of this property is nil
.
let numbers = [10, 20, 30, 40, 50]
if let lastNumber = numbers.last {
print(lastNumber)
}
// Prints "50"
Declaration
var last: ClosedRange<Bound>.Element? { get }
Declared In
BidirectionalCollection
A view onto this collection that provides lazy implementations of
normally eager operations, such as map
and filter
.
Use the lazy
property when chaining operations to prevent
intermediate operations from allocating storage, or when you only
need a part of the final collection to avoid unnecessary computation.
Declaration
var lazy: LazyCollection<ClosedRange<Bound>> { get }
Declared In
BidirectionalCollection
, Collection
The range's lower bound.
Declaration
var lowerBound: Bound { get }
The position of the first element in the range.
Declaration
var startIndex: ClosedRange<Bound>.Index { get }
A value less than or equal to the number of elements in the collection.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the length
of the collection.
Declaration
var underestimatedCount: Int { get }
Declared In
BidirectionalCollection
, Collection
, Sequence
The range's upper bound.
Declaration
var upperBound: Bound { get }
Subscripts
Declaration
subscript(x: (UnboundedRange_) > ()) > ClosedRange<Bound>.SubSequence { get }
Declared In
BidirectionalCollection
, Collection
Accesses the element at specified position.
You can subscript a collection with any valid index other than the collection's end index. The end index refers to the position one past the last element of a collection, so it doesn't correspond with an element.
position
: The position of the element to access. position
must be a valid index of the range, and must not equal the range's end
index.
Declaration
subscript(position: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Bound { get }
Accesses a contiguous subrange of the collection's elements.
For example, using a PartialRangeFrom
range expression with an array
accesses the subrange from the start of the range expression until the
end of the array.
let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2..<5]
print(streetsSlice)
// ["Channing", "Douglas", "Evarts"]
The accessed slice uses the same indices for the same elements as the
original collection. This example searches streetsSlice
for one of the
strings in the slice, and then uses that index in the original array.
let index = streetsSlice.firstIndex(of: "Evarts")! // 4
print(streets[index])
// "Evarts"
Always use the slice's startIndex
property instead of assuming that its
indices start at a particular value. Attempting to access an element by
using an index outside the bounds of the slice may result in a runtime
error, even if that index is valid for the original collection.
print(streetsSlice.startIndex)
// 2
print(streetsSlice[2])
// "Channing"
print(streetsSlice[0])
// error: Index out of bounds
bounds
: A range of the collection's indices. The bounds of
the range must be valid indices of the collection.
Complexity: O(1)
Declaration
subscript(bounds: Range<ClosedRange<Bound>.Index>) > Slice<ClosedRange<ClosedRange<Bound>.Bound>> { get }
Accesses the contiguous subrange of the collection's elements specified by a range expression.
The range expression is converted to a concrete subrange relative to this
collection. For example, using a PartialRangeFrom
range expression
with an array accesses the subrange from the start of the range
expression until the end of the array.
let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2...]
print(streetsSlice)
// ["Channing", "Douglas", "Evarts"]
The accessed slice uses the same indices for the same elements as the
original collection uses. This example searches streetsSlice
for one
of the strings in the slice, and then uses that index in the original
array.
let index = streetsSlice.firstIndex(of: "Evarts") // 4
print(streets[index!])
// "Evarts"
Always use the slice's startIndex
property instead of assuming that its
indices start at a particular value. Attempting to access an element by
using an index outside the bounds of the slice's indices may result in a
runtime error, even if that index is valid for the original collection.
print(streetsSlice.startIndex)
// 2
print(streetsSlice[2])
// "Channing"
print(streetsSlice[0])
// error: Index out of bounds
bounds
: A range of the collection's indices. The bounds of
the range must be valid indices of the collection.
Complexity: O(1)
Declaration
subscript<R>(r: R) > ClosedRange<Bound>.SubSequence where R : RangeExpression, ClosedRange<Bound>.Index == R.Bound { get }
Declared In
BidirectionalCollection
, Collection
Instance Methods
Returns a Boolean value indicating whether every element of a sequence satisfies a given predicate.
predicate
: A closure that takes an element of the sequence
as its argument and returns a Boolean value that indicates whether
the passed element satisfies a condition.
Returns: true
if the sequence contains only elements that satisfy
predicate
; otherwise, false
.
Declaration
func allSatisfy(_ predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > Bool
Declared In
BidirectionalCollection
, Sequence
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 singleelement range at
the upper or lower bound of limits
.
let y: ClosedRange = 0...5
print(y.clamped(to: 10...1000))
// Prints "10...10"
limits
: The range to clamp the bounds of this range.
Returns: A new range clamped to the bounds of limits
.
Declaration
func clamped(to limits: ClosedRange<Bound>) > ClosedRange<Bound>
Returns an array containing the nonnil
results of calling the given
transformation with each element of this sequence.
Use this method to receive an array of nonoptional values when your transformation produces an optional value.
In this example, note the difference in the result of using map
and
compactMap
with a transformation that returns an optional Int
value.
let possibleNumbers = ["1", "2", "three", "///4///", "5"]
let mapped: [Int?] = possibleNumbers.map { str in Int(str) }
// [1, 2, nil, nil, 5]
let compactMapped: [Int] = possibleNumbers.compactMap { str in Int(str) }
// [1, 2, 5]
transform
: A closure that accepts an element of this
sequence as its argument and returns an optional value.
Returns: An array of the nonnil
results of calling transform
with each element of the sequence.
Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.
Declaration
func compactMap<ElementOfResult>(_ transform: (ClosedRange<Bound>.Element) throws > ElementOfResult?) rethrows > [ElementOfResult]
Declared In
BidirectionalCollection
, Sequence
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.
element
: The element to check for containment.
Returns: true
if element
is contained in the range; otherwise,
false
.
Declaration
func contains(_ element: Bound) > Bool
Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.
You can use the predicate to check for an element of a type that
doesn't conform to the Equatable
protocol, such as the
HTTPResponse
enumeration in this example.
enum HTTPResponse {
case ok
case error(Int)
}
let lastThreeResponses: [HTTPResponse] = [.ok, .ok, .error(404)]
let hadError = lastThreeResponses.contains { element in
if case .error = element {
return true
} else {
return false
}
}
// 'hadError' == true
Alternatively, a predicate can be satisfied by a range of Equatable
elements or a general condition. This example shows how you can check an
array for an expense greater than $100.
let expenses = [21.37, 55.21, 9.32, 10.18, 388.77, 11.41]
let hasBigPurchase = expenses.contains { $0 > 100 }
// 'hasBigPurchase' == true
predicate
: A closure that takes an element of the sequence
as its argument and returns a Boolean value that indicates whether
the passed element represents a match.
Returns: true
if the sequence contains an element that satisfies
predicate
; otherwise, false
.
Declaration
func contains(where predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > Bool
Declared In
BidirectionalCollection
, Sequence
Returns the distance between two indices.
Unless the collection conforms to the BidirectionalCollection
protocol,
start
must be less than or equal to end
.
Parameters:
start: A valid index of the collection.
end: Another valid index of the collection. If end
is equal to
start
, the result is zero.
Returns: The distance between start
and end
. The result can be
negative only if the collection conforms to the
BidirectionalCollection
protocol.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the
resulting distance.
Declaration
func distance(from start: ClosedRange<Bound>.Index, to end: ClosedRange<Bound>.Index) > Int
Declared In
BidirectionalCollection
, Collection
Returns the distance between two indices.
Unless the collection conforms to the BidirectionalCollection
protocol,
start
must be less than or equal to end
.
Parameters:
start: A valid index of the collection.
end: Another valid index of the collection. If end
is equal to
start
, the result is zero.
Returns: The distance between start
and end
. The result can be
negative only if the collection conforms to the
BidirectionalCollection
protocol.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the
resulting distance.
Declaration
func distance(from start: ClosedRange<Bound>.Index, to end: ClosedRange<Bound>.Index) > Int
Declared In
ClosedRange
, BidirectionalCollection
Deprecated: all index distances are now of type Int.
Declaration
func distance<T>(from start: ClosedRange<Bound>.Index, to end: ClosedRange<Bound>.Index) > T where T : BinaryInteger
Declared In
BidirectionalCollection
, Collection
Returns a subsequence by skipping elements while predicate
returns
true
and returning the remaining elements.
predicate
: A closure that takes an element of the
sequence as its argument and returns true
if the element should
be skipped or false
if it should be included. Once the predicate
returns false
it will not be called again.
Complexity: O(n), where n is the length of the collection.
Declaration
func drop(while predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence containing all but the first element of the sequence.
The following example drops the first element from an array of integers.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst())
// Prints "[2, 3, 4, 5]"
If the sequence has no elements, the result is an empty subsequence.
let empty: [Int] = []
print(empty.dropFirst())
// Prints "[]"
Returns: A subsequence starting after the first element of the sequence.
Complexity: O(1)
Declaration
func dropFirst() > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence containing all but the given number of initial elements.
If the number of elements to drop exceeds the number of elements in the collection, the result is an empty subsequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst(2))
// Prints "[3, 4, 5]"
print(numbers.dropFirst(10))
// Prints "[]"
n
: The number of elements to drop from the beginning of
the collection. n
must be greater than or equal to zero.
Returns: A subsequence starting after the specified number of
elements.
Complexity: O(n), where n is the number of elements to drop from the beginning of the collection.
Declaration
func dropFirst(_ n: Int) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence containing all but the last element of the sequence.
The sequence must be finite.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast())
// Prints "[1, 2, 3, 4]"
If the sequence has no elements, the result is an empty subsequence.
let empty: [Int] = []
print(empty.dropLast())
// Prints "[]"
Returns: A subsequence leaving off the last element of the sequence.
Complexity: O(n), where n is the length of the sequence.
Declaration
func dropLast() > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence containing all but the specified number of final elements.
If the number of elements to drop exceeds the number of elements in the collection, the result is an empty subsequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast(2))
// Prints "[1, 2, 3]"
print(numbers.dropLast(10))
// Prints "[]"
n
: The number of elements to drop off the end of the
collection. n
must be greater than or equal to zero.
Returns: A subsequence that leaves off n
elements from the end.
Complexity: O(n), where n is the number of elements to drop.
Declaration
func dropLast(_ n: Int) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements in the same order, using the given predicate as the equivalence test.
At least one of the sequences must be finite.
The predicate must be a equivalence relation over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areEquivalent(a, a)
is alwaystrue
. (Reflexivity)areEquivalent(a, b)
impliesareEquivalent(b, a)
. (Symmetry) If
areEquivalent(a, b)
andareEquivalent(b, c)
are bothtrue
, thenareEquivalent(a, c)
is alsotrue
. (Transitivity)
Parameters:
other: A sequence to compare to this sequence.
areEquivalent: A predicate that returns true
if its two arguments
are equivalent; otherwise, false
.
Returns: true
if this sequence and other
contain equivalent items,
using areEquivalent
as the equivalence test; otherwise, false.
Declaration
func elementsEqual<OtherSequence>(_ other: OtherSequence, by areEquivalent: (ClosedRange<Bound>.Element, OtherSequence.Element) throws > Bool) rethrows > Bool where OtherSequence : Sequence
Declared In
BidirectionalCollection
, Sequence
Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero and x represents an element of the sequence.
This example enumerates the characters of the string "Swift" and prints each character along with its place in the string.
for (n, c) in "Swift".enumerated() {
print("\(n): '\(c)'")
}
// Prints "0: 'S'"
// Prints "1: 'w'"
// Prints "2: 'i'"
// Prints "3: 'f'"
// Prints "4: 't'"
When you enumerate a collection, the integer part of each pair is a counter
for the enumeration, but is not necessarily the index of the paired value.
These counters can be used as indices only in instances of zerobased,
integerindexed collections, such as Array
and ContiguousArray
. For
other collections the counters may be out of range or of the wrong type
to use as an index. To iterate over the elements of a collection with its
indices, use the zip(_:_:)
function.
This example iterates over the indices and elements of a set, building a list consisting of indices of names with five or fewer letters.
let names: Set = ["Sofia", "Camilla", "Martina", "Mateo", "Nicolás"]
var shorterIndices: [SetIndex<String>] = []
for (i, name) in zip(names.indices, names) {
if name.count <= 5 {
shorterIndices.append(i)
}
}
Now that the shorterIndices
array holds the indices of the shorter
names in the names
set, you can use those indices to access elements in
the set.
for i in shorterIndices {
print(names[i])
}
// Prints "Sofia"
// Prints "Mateo"
Returns: A sequence of pairs enumerating the sequence.
Declaration
func enumerated() > EnumeratedSequence<ClosedRange<Bound>>
Declared In
BidirectionalCollection
, Sequence
Returns an array containing, in order, the elements of the sequence that satisfy the given predicate.
In this example, filter(_:)
is used to include only names shorter than
five characters.
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let shortNames = cast.filter { $0.count < 5 }
print(shortNames)
// Prints "["Kim", "Karl"]"
isIncluded
: A closure that takes an element of the
sequence as its argument and returns a Boolean value indicating
whether the element should be included in the returned array.
Returns: An array of the elements that isIncluded
allowed.
Declaration
func filter(_ isIncluded: (ClosedRange<Bound>.Element) throws > Bool) rethrows > [ClosedRange<Bound>.Element]
Declared In
BidirectionalCollection
, Sequence
Returns the first element of the sequence that satisfies the given predicate.
The following example uses the first(where:)
method to find the first
negative number in an array of integers:
let numbers = [3, 7, 4, 2, 9, 6, 10, 1]
if let firstNegative = numbers.first(where: { $0 < 0 }) {
print("The first negative number is \(firstNegative).")
}
// Prints "The first negative number is 2."
predicate
: A closure that takes an element of the sequence as
its argument and returns a Boolean value indicating whether the
element is a match.
Returns: The first element of the sequence that satisfies predicate
,
or nil
if there is no element that satisfies predicate
.
Declaration
func first(where predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
, Sequence
Returns the first index in which an element of the collection satisfies the given predicate.
You can use the predicate to find an element of a type that doesn't
conform to the Equatable
protocol or to find an element that matches
particular criteria. Here's an example that finds a student name that
begins with the letter "A":
let students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
if let i = students.firstIndex(where: { $0.hasPrefix("A") }) {
print("\(students[i]) starts with 'A'!")
}
// Prints "Abena starts with 'A'!"
predicate
: A closure that takes an element as its argument
and returns a Boolean value that indicates whether the passed element
represents a match.
Returns: The index of the first element for which predicate
returns
true
. If no elements in the collection satisfy the given predicate,
returns nil
.
Declaration
func firstIndex(where predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Index?
Declared In
BidirectionalCollection
, Collection
Declaration
func flatMap(_ transform: (ClosedRange<Bound>.Element) throws > String?) rethrows > [String]
Declared In
BidirectionalCollection
, Collection
Returns an array containing the nonnil
results of calling the given
transformation with each element of this sequence.
Use this method to receive an array of nonoptional values when your transformation produces an optional value.
In this example, note the difference in the result of using map
and
flatMap
with a transformation that returns an optional Int
value.
let possibleNumbers = ["1", "2", "three", "///4///", "5"]
let mapped: [Int?] = possibleNumbers.map { str in Int(str) }
// [1, 2, nil, nil, 5]
let flatMapped: [Int] = possibleNumbers.flatMap { str in Int(str) }
// [1, 2, 5]
transform
: A closure that accepts an element of this
sequence as its argument and returns an optional value.
Returns: An array of the nonnil
results of calling transform
with each element of the sequence.
Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.
Declaration
func flatMap<ElementOfResult>(_ transform: (ClosedRange<Bound>.Element) throws > ElementOfResult?) rethrows > [ElementOfResult]
Declared In
BidirectionalCollection
, Sequence
Returns an array containing the concatenated results of calling the given transformation with each element of this sequence.
Use this method to receive a singlelevel collection when your transformation produces a sequence or collection for each element.
In this example, note the difference in the result of using map
and
flatMap
with a transformation that returns an array.
let numbers = [1, 2, 3, 4]
let mapped = numbers.map { Array(repeating: $0, count: $0) }
// [[1], [2, 2], [3, 3, 3], [4, 4, 4, 4]]
let flatMapped = numbers.flatMap { Array(repeating: $0, count: $0) }
// [1, 2, 2, 3, 3, 3, 4, 4, 4, 4]
In fact, s.flatMap(transform)
is equivalent to
Array(s.map(transform).joined())
.
transform
: A closure that accepts an element of this
sequence as its argument and returns a sequence or collection.
Returns: The resulting flattened array.
Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.
Declaration
func flatMap<SegmentOfResult>(_ transform: (ClosedRange<Bound>.Element) throws > SegmentOfResult) rethrows > [SegmentOfResult.Element] where SegmentOfResult : Sequence
Declared In
BidirectionalCollection
, Sequence
Calls the given closure on each element in the sequence in the same order
as a for
in
loop.
The two loops in the following example produce the same output:
let numberWords = ["one", "two", "three"]
for word in numberWords {
print(word)
}
// Prints "one"
// Prints "two"
// Prints "three"
numberWords.forEach { word in
print(word)
}
// Same as above
Using the forEach
method is distinct from a for
in
loop in two
important ways:
 You cannot use a
break
orcontinue
statement to exit the current call of thebody
closure or skip subsequent calls.  Using the
return
statement in thebody
closure will exit only from the current call tobody
, not from any outer scope, and won't skip subsequent calls.
body
: A closure that takes an element of the sequence as a
parameter.
Declaration
func forEach(_ body: (ClosedRange<Bound>.Element) throws > Void) rethrows
Declared In
BidirectionalCollection
, Sequence
Offsets the given index by the specified distance.
The value passed as n
must not offset i
beyond the bounds of the
collection.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
. n
must not be negative unless the
collection conforms to the BidirectionalCollection
protocol.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the absolute
value of n
.
Declaration
func formIndex(_ i: inout ClosedRange<Bound>.Index, offsetBy n: Int)
Declared In
BidirectionalCollection
, Collection
Deprecated: all index distances are now of type Int.
Declaration
func formIndex<T>(_ i: inout ClosedRange<Bound>.Index, offsetBy n: T)
Declared In
BidirectionalCollection
, Collection
Offsets the given index by the specified distance, or so that it equals the given limiting index.
The value passed as n
must not offset i
beyond the bounds of the
collection, unless the index passed as limit
prevents offsetting
beyond those bounds.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
. n
must not be negative unless the
collection conforms to the BidirectionalCollection
protocol.
limit: A valid index of the collection to use as a limit. If n > 0
,
a limit that is less than i
has no effect. Likewise, if n < 0
, a
limit that is greater than i
has no effect.
Returns: true
if i
has been offset by exactly n
steps without
going beyond limit
; otherwise, false
. When the return value is
false
, the value of i
is equal to limit
.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the absolute
value of n
.
Declaration
func formIndex(_ i: inout ClosedRange<Bound>.Index, offsetBy n: Int, limitedBy limit: ClosedRange<Bound>.Index) > Bool
Declared In
BidirectionalCollection
, Collection
Deprecated: all index distances are now of type Int.
Declaration
func formIndex<T>(_ i: inout ClosedRange<Bound>.Index, offsetBy n: T, limitedBy limit: ClosedRange<Bound>.Index) > Bool where T : BinaryInteger
Declared In
BidirectionalCollection
, Collection
Replaces the given index with its successor.
i
: A valid index of the collection. i
must be less than
endIndex
.
Declaration
func formIndex(after i: inout ClosedRange<Bound>.Index)
Declared In
BidirectionalCollection
, Collection
Replaces the given index with its predecessor.
i
: A valid index of the collection. i
must be greater than
startIndex
.
Declaration
func formIndex(before i: inout ClosedRange<Bound>.Index)
Declared In
BidirectionalCollection
Hashes the essential components of this value by feeding them into the given hasher.
Implement this method to conform to the Hashable
protocol. The
components used for hashing must be the same as the components compared
in your type's ==
operator implementation. Call hasher.combine(_:)
with each of these components.
Important: Never call finalize()
on hasher
. Doing so may become a
compiletime error in the future.
hasher
: The hasher to use when combining the components
of this instance.
Declaration
func hash(into hasher: inout Hasher)
Returns an index that is the specified distance from the given index.
The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.
let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"
The value passed as n
must not offset i
beyond the bounds of the
collection.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
. n
must not be negative unless the
collection conforms to the BidirectionalCollection
protocol.
Returns: An index offset by n
from the index i
. If n
is positive,
this is the same value as the result of n
calls to index(after:)
.
If n
is negative, this is the same value as the result of n
calls
to index(before:)
.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the absolute
value of n
.
Declaration
func index(_ i: ClosedRange<Bound>.Index, offsetBy n: Int) > ClosedRange<Bound>.Index
Declared In
BidirectionalCollection
, Collection
Returns an index that is the specified distance from the given index.
The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.
let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"
The value passed as n
must not offset i
beyond the bounds of the
collection.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
. n
must not be negative unless the
collection conforms to the BidirectionalCollection
protocol.
Returns: An index offset by n
from the index i
. If n
is positive,
this is the same value as the result of n
calls to index(after:)
.
If n
is negative, this is the same value as the result of n
calls
to index(before:)
.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the absolute
value of n
.
Declaration
func index(_ i: ClosedRange<Bound>.Index, offsetBy n: Int) > ClosedRange<Bound>.Index
Declared In
ClosedRange
, BidirectionalCollection
Deprecated: all index distances are now of type Int.
Declaration
func index<T>(_ i: ClosedRange<Bound>.Index, offsetBy n: T) > ClosedRange<Bound>.Index where T : BinaryInteger
Declared In
BidirectionalCollection
, Collection
Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
The following example obtains an index advanced four positions from a
string's starting index and then prints the character at that position.
The operation doesn't require going beyond the limiting s.endIndex
value, so it succeeds.
let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
print(s[i])
}
// Prints "t"
The next example attempts to retrieve an index six positions from
s.startIndex
but fails, because that distance is beyond the index
passed as limit
.
let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
print(j)
// Prints "nil"
The value passed as n
must not offset i
beyond the bounds of the
collection, unless the index passed as limit
prevents offsetting
beyond those bounds.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
. n
must not be negative unless the
collection conforms to the BidirectionalCollection
protocol.
limit: A valid index of the collection to use as a limit. If n > 0
,
a limit that is less than i
has no effect. Likewise, if n < 0
, a
limit that is greater than i
has no effect.
Returns: An index offset by n
from the index i
, unless that index
would be beyond limit
in the direction of movement. In that case,
the method returns nil
.
Complexity: O(1) if the collection conforms to
RandomAccessCollection
; otherwise, O(n), where n is the absolute
value of n
.
Declaration
func index(_ i: ClosedRange<Bound>.Index, offsetBy n: Int, limitedBy limit: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index?
Declared In
BidirectionalCollection
, Collection
Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
The following example obtains an index advanced four positions from an
array's starting index and then prints the element at that position. The
operation doesn't require going beyond the limiting numbers.endIndex
value, so it succeeds.
let numbers = [10, 20, 30, 40, 50]
let i = numbers.index(numbers.startIndex, offsetBy: 4)
print(numbers[i])
// Prints "50"
The next example attempts to retrieve an index ten positions from
numbers.startIndex
, but fails, because that distance is beyond the
index passed as limit
.
let j = numbers.index(numbers.startIndex,
offsetBy: 10,
limitedBy: numbers.endIndex)
print(j)
// Prints "nil"
The value passed as n
must not offset i
beyond the bounds of the
collection, unless the index passed as limit
prevents offsetting
beyond those bounds.
Parameters:
i: A valid index of the array.
n: The distance to offset i
.
limit: A valid index of the collection to use as a limit. If n > 0
,
limit
should be greater than i
to have any effect. Likewise, if
n < 0
, limit
should be less than i
to have any effect.
Returns: An index offset by n
from the index i
, unless that index
would be beyond limit
in the direction of movement. In that case,
the method returns nil
.
Complexity: O(1)
Declaration
func index(_ i: ClosedRange<Bound>.Index, offsetBy n: Int, limitedBy limit: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index?
Declared In
RandomAccessCollection
, BidirectionalCollection
Deprecated: all index distances are now of type Int.
Declaration
func index<T>(_ i: ClosedRange<Bound>.Index, offsetBy n: T, limitedBy limit: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index? where T : BinaryInteger
Declared In
BidirectionalCollection
, Collection
Returns the position immediately after the given index.
The successor of an index must be well defined. For an index i
into a
collection c
, calling c.index(after: i)
returns the same index every
time.
i
: A valid index of the collection. i
must be less than
endIndex
.
Returns: The index value immediately after i
.
Declaration
func index(after i: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index
Returns the position immediately before the given index.
i
: A valid index of the collection. i
must be greater than
startIndex
.
Returns: The index value immediately before i
.
Declaration
func index(before i: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index
Returns the last element of the sequence that satisfies the given predicate.
This example uses the last(where:)
method to find the last
negative number in an array of integers:
let numbers = [3, 7, 4, 2, 9, 6, 10, 1]
if let lastNegative = numbers.last(where: { $0 < 0 }) {
print("The last negative number is \(firstNegative).")
}
// Prints "The last negative number is 6."
predicate
: A closure that takes an element of the sequence as
its argument and returns a Boolean value indicating whether the
element is a match.
Returns: The last element of the sequence that satisfies predicate
,
or nil
if there is no element that satisfies predicate
.
Declaration
func last(where predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
Returns the index of the last element in the collection that matches the given predicate.
You can use the predicate to find an element of a type that doesn't
conform to the Equatable
protocol or to find an element that matches
particular criteria. This example finds the index of the last name that
begins with the letter "A":
let students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
if let i = students.lastIndex(where: { $0.hasPrefix("A") }) {
print("\(students[i]) starts with 'A'!")
}
// Prints "Akosua starts with 'A'!"
predicate
: A closure that takes an element as its argument
and returns a Boolean value that indicates whether the passed element
represents a match.
Returns: The index of the last element in the collection that matches
predicate
, or nil
if no elements match.
Declaration
func lastIndex(where predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Index?
Declared In
BidirectionalCollection
Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.
The predicate must be a strict weak ordering over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areInIncreasingOrder(a, a)
is alwaysfalse
. (Irreflexivity) If
areInIncreasingOrder(a, b)
andareInIncreasingOrder(b, c)
are bothtrue
, thenareInIncreasingOrder(a, c)
is alsotrue
. (Transitive comparability)  Two elements are incomparable if neither is ordered before the other
according to the predicate. If
a
andb
are incomparable, andb
andc
are incomparable, thena
andc
are also incomparable. (Transitive incomparability)
Parameters:
other: A sequence to compare to this sequence.
areInIncreasingOrder: A predicate that returns true
if its first
argument should be ordered before its second argument; otherwise,
false
.
Returns: true
if this sequence precedes other
in a dictionary
ordering as ordered by areInIncreasingOrder
; otherwise, false
.
Note: This method implements the mathematical notion of lexicographical
ordering, which has no connection to Unicode. If you are sorting
strings to present to the end user, use String
APIs that perform
localized comparison instead.
Declaration
func lexicographicallyPrecedes<OtherSequence>(_ other: OtherSequence, by areInIncreasingOrder: (ClosedRange<Bound>.Element, ClosedRange<Bound>.Element) throws > Bool) rethrows > Bool where OtherSequence : Sequence, ClosedRange<Bound>.Element == OtherSequence.Element
Declared In
BidirectionalCollection
, Sequence
Returns an array containing the results of mapping the given closure over the sequence's elements.
In this example, map
is used first to convert the names in the array
to lowercase strings and then to count their characters.
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let lowercaseNames = cast.map { $0.lowercased() }
// 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"]
let letterCounts = cast.map { $0.count }
// 'letterCounts' == [6, 6, 3, 4]
transform
: A mapping closure. transform
accepts an
element of this sequence as its parameter and returns a transformed
value of the same or of a different type.
Returns: An array containing the transformed elements of this
sequence.
Declaration
func map<T>(_ transform: (ClosedRange<Bound>.Element) throws > T) rethrows > [T]
Declared In
BidirectionalCollection
, Collection
, Sequence
Returns the maximum element in the sequence, using the given predicate as the comparison between elements.
The predicate must be a strict weak ordering over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areInIncreasingOrder(a, a)
is alwaysfalse
. (Irreflexivity) If
areInIncreasingOrder(a, b)
andareInIncreasingOrder(b, c)
are bothtrue
, thenareInIncreasingOrder(a, c)
is alsotrue
. (Transitive comparability)  Two elements are incomparable if neither is ordered before the other
according to the predicate. If
a
andb
are incomparable, andb
andc
are incomparable, thena
andc
are also incomparable. (Transitive incomparability)
This example shows how to use the max(by:)
method on a
dictionary to find the keyvalue pair with the highest value.
let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
let greatestHue = hues.max { a, b in a.value < b.value }
print(greatestHue)
// Prints "Optional(("Heliotrope", 296))"
areInIncreasingOrder
: A predicate that returns true
if its
first argument should be ordered before its second argument;
otherwise, false
.
Returns: The sequence's maximum element if the sequence is not empty;
otherwise, nil
.
Declaration
@warn_unqualified_access
func max(by areInIncreasingOrder: (ClosedRange<Bound>.Element, ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
, Sequence
Returns the minimum element in the sequence, using the given predicate as the comparison between elements.
The predicate must be a strict weak ordering over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areInIncreasingOrder(a, a)
is alwaysfalse
. (Irreflexivity) If
areInIncreasingOrder(a, b)
andareInIncreasingOrder(b, c)
are bothtrue
, thenareInIncreasingOrder(a, c)
is alsotrue
. (Transitive comparability)  Two elements are incomparable if neither is ordered before the other
according to the predicate. If
a
andb
are incomparable, andb
andc
are incomparable, thena
andc
are also incomparable. (Transitive incomparability)
This example shows how to use the min(by:)
method on a
dictionary to find the keyvalue pair with the lowest value.
let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
let leastHue = hues.min { a, b in a.value < b.value }
print(leastHue)
// Prints "Optional(("Coral", 16))"
areInIncreasingOrder
: A predicate that returns true
if its first argument should be ordered before its second
argument; otherwise, false
.
Returns: The sequence's minimum element, according to
areInIncreasingOrder
. If the sequence has no elements, returns
nil
.
Declaration
func min(by areInIncreasingOrder: (ClosedRange<Bound>.Element, ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
, Sequence
Declaration
func overlaps(_ other: ClosedRange<ClosedRange<Bound>.Bound>) > Bool
Declaration
func overlaps(_ other: Range<ClosedRange<Bound>.Bound>) > Bool
Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.
If the maximum length exceeds the number of elements in the collection, the result contains all the elements in the collection.
let numbers = [1, 2, 3, 4, 5]
print(numbers.prefix(2))
// Prints "[1, 2]"
print(numbers.prefix(10))
// Prints "[1, 2, 3, 4, 5]"
maxLength
: The maximum number of elements to return.
maxLength
must be greater than or equal to zero.
Returns: A subsequence starting at the beginning of this collection
with at most maxLength
elements.
Declaration
func prefix(_ maxLength: Int) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence from the start of the collection through the specified position.
The resulting subsequence includes the element at the position end
.
The following example searches for the index of the number 40
in an
array of integers, and then prints the prefix of the array up to, and
including, that index:
let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
print(numbers.prefix(through: i))
}
// Prints "[10, 20, 30, 40]"
Using the prefix(through:)
method is equivalent to using a partial
closed range as the collection's subscript. The subscript notation is
preferred over prefix(through:)
.
if let i = numbers.firstIndex(of: 40) {
print(numbers[...i])
}
// Prints "[10, 20, 30, 40]"
end
: The index of the last element to include in the
resulting subsequence. end
must be a valid index of the collection
that is not equal to the endIndex
property.
Returns: A subsequence up to, and including, the end
position.
Complexity: O(1)
Declaration
func prefix(through position: ClosedRange<Bound>.Index) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence from the start of the collection up to, but not including, the specified position.
The resulting subsequence does not include the element at the position
end
. The following example searches for the index of the number 40
in an array of integers, and then prints the prefix of the array up to,
but not including, that index:
let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
print(numbers.prefix(upTo: i))
}
// Prints "[10, 20, 30]"
Passing the collection's starting index as the end
parameter results in
an empty subsequence.
print(numbers.prefix(upTo: numbers.startIndex))
// Prints "[]"
Using the prefix(upTo:)
method is equivalent to using a partial
halfopen range as the collection's subscript. The subscript notation is
preferred over prefix(upTo:)
.
if let i = numbers.firstIndex(of: 40) {
print(numbers[..<i])
}
// Prints "[10, 20, 30]"
end
: The "past the end" index of the resulting subsequence.
end
must be a valid index of the collection.
Returns: A subsequence up to, but not including, the end
position.
Complexity: O(1)
Declaration
func prefix(upTo end: ClosedRange<Bound>.Index) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence containing the initial elements until predicate
returns false
and skipping the remaining elements.
predicate
: A closure that takes an element of the
sequence as its argument and returns true
if the element should
be included or false
if it should be excluded. Once the predicate
returns false
it will not be called again.
Complexity: O(n), where n is the length of the collection.
Declaration
func prefix(while predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a random element of the range, using the given generator as a source for randomness.
You can use this method to select a random element of a range when you
are using a custom random number generator. If you're generating a random
number, in most cases, you should prefer using the random(in:)
static method of the desired numeric type. That static method is available
for both integer and floating point types, and returns a nonoptional
value.
This method uses the default random generator, Random.default
. Calling
(1...100).randomElement()
is equivalent to calling
(1...100).randomElement(using: &Random.default)
.
Returns: A random element of the range.
This method never returns nil
.
Declaration
func randomElement() > ClosedRange<Bound>.Element?
Declared In
ClosedRange
, BidirectionalCollection
, Collection
Returns a random element of the range, using the given generator as a source for randomness.
You can use this method to select a random element of a range when you
are using a custom random number generator. If you're generating a random
number, in most cases, you should prefer using the random(in:using:)
static method of the desired numeric type. That static method is available
for both integer and floating point types, and returns a nonoptional
value.
generator
: The random number generator to use when choosing
a random element.
Returns: A random element of the range.
This method never returns nil
.
Declaration
func randomElement<T>(using generator: inout T) > ClosedRange<Bound>.Element? where T : RandomNumberGenerator
Declared In
ClosedRange
, BidirectionalCollection
, Collection
Returns the result of combining the elements of the sequence using the given closure.
Use the reduce(_:_:)
method to produce a single value from the elements
of an entire sequence. For example, you can use this method on an array
of numbers to find their sum or product.
The nextPartialResult
closure is called sequentially with an
accumulating value initialized to initialResult
and each element of
the sequence. This example shows how to find the sum of an array of
numbers.
let numbers = [1, 2, 3, 4]
let numberSum = numbers.reduce(0, { x, y in
x + y
})
// numberSum == 10
When numbers.reduce(_:_:)
is called, the following steps occur:
 The
nextPartialResult
closure is called withinitialResult
0
in this caseand the first element ofnumbers
, returning the sum:1
.  The closure is called again repeatedly with the previous call's return value and each element of the sequence.
 When the sequence is exhausted, the last value returned from the closure is returned to the caller.
If the sequence has no elements, nextPartialResult
is never executed
and initialResult
is the result of the call to reduce(_:_:)
.
Parameters:
initialResult: The value to use as the initial accumulating value.
initialResult
is passed to nextPartialResult
the first time the
closure is executed.
nextPartialResult: A closure that combines an accumulating value and
an element of the sequence into a new accumulating value, to be used
in the next call of the nextPartialResult
closure or returned to
the caller.
Returns: The final accumulated value. If the sequence has no elements,
the result is initialResult
.
Declaration
func reduce<Result>(_ initialResult: Result, _ nextPartialResult: (Result, ClosedRange<Bound>.Element) throws > Result) rethrows > Result
Declared In
BidirectionalCollection
, Sequence
Returns the result of combining the elements of the sequence using the given closure.
Use the reduce(into:_:)
method to produce a single value from the
elements of an entire sequence. For example, you can use this method on an
array of integers to filter adjacent equal entries or count frequencies.
This method is preferred over reduce(_:_:)
for efficiency when the
result is a copyonwrite type, for example an Array or a Dictionary.
The updateAccumulatingResult
closure is called sequentially with a
mutable accumulating value initialized to initialResult
and each element
of the sequence. This example shows how to build a dictionary of letter
frequencies of a string.
let letters = "abracadabra"
let letterCount = letters.reduce(into: [:]) { counts, letter in
counts[letter, default: 0] += 1
}
// letterCount == ["a": 5, "b": 2, "r": 2, "c": 1, "d": 1]
When letters.reduce(into:_:)
is called, the following steps occur:
 The
updateAccumulatingResult
closure is called with the initial accumulating value[:]
in this caseand the first character ofletters
, modifying the accumulating value by setting1
for the key"a"
.  The closure is called again repeatedly with the updated accumulating value and each element of the sequence.
 When the sequence is exhausted, the accumulating value is returned to the caller.
If the sequence has no elements, updateAccumulatingResult
is never
executed and initialResult
is the result of the call to
reduce(into:_:)
.
Parameters:
initialResult: The value to use as the initial accumulating value.
updateAccumulatingResult: A closure that updates the accumulating
value with an element of the sequence.
Returns: The final accumulated value. If the sequence has no elements,
the result is initialResult
.
Declaration
func reduce<Result>(into initialResult: Result, _ updateAccumulatingResult: (inout Result, ClosedRange<Bound>.Element) throws > ()) rethrows > Result
Declared In
BidirectionalCollection
, Sequence
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 halfopen 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]
collection
: The collection to evaluate this range expression
in relation to.
Returns: A range suitable for slicing collection
. The returned range
is not guaranteed to be inside the bounds of collection
. Callers
should apply the same preconditions to the return value as they would
to a range provided directly by the user.
Declaration
func relative<C>(to collection: C) > Range<Bound> where Bound == C.Index, C : Collection
Returns a view presenting the elements of the collection in reverse order.
You can reverse a collection without allocating new space for its
elements by calling this reversed()
method. A ReversedCollection
instance wraps an underlying collection and provides access to its
elements in reverse order. This example prints the characters of a
string in reverse order:
let word = "Backwards"
for char in word.reversed() {
print(char, terminator: "")
}
// Prints "sdrawkcaB"
If you need a reversed collection of the same type, you may be able to
use the collection's sequencebased or collectionbased initializer. For
example, to get the reversed version of a string, reverse its
characters and initialize a new String
instance from the result.
let reversedWord = String(word.reversed())
print(reversedWord)
// Prints "sdrawkcaB"
Complexity: O(1)
Declaration
func reversed() > ReversedCollection<ClosedRange<Bound>>
Declared In
BidirectionalCollection
, Sequence
Returns the elements of the sequence, shuffled.
For example, you can shuffle the numbers between 0
and 9
by calling
the shuffled()
method on that range:
let numbers = 0...9
let shuffledNumbers = numbers.shuffled()
// shuffledNumbers == [1, 7, 6, 2, 8, 9, 4, 3, 5, 0]
This method uses the default random generator, Random.default
. The call
to numbers.shuffled()
above is equivalent to calling
numbers.shuffled(using: &Random.default)
.
Returns: A shuffled array of this sequence's elements.
Complexity: O(n)
Declaration
func shuffled() > [ClosedRange<Bound>.Element]
Declared In
BidirectionalCollection
, Sequence
Returns the elements of the sequence, shuffled using the given generator as a source for randomness.
You use this method to randomize the elements of a sequence when you
are using a custom random number generator. For example, you can shuffle
the numbers between 0
and 9
by calling the shuffled(using:)
method
on that range:
let numbers = 0...9
let shuffledNumbers = numbers.shuffled(using: &myGenerator)
// shuffledNumbers == [8, 9, 4, 3, 2, 6, 7, 0, 5, 1]
generator
: The random number generator to use when shuffling
the sequence.
Returns: An array of this sequence's elements in a shuffled order.
Complexity: O(n)
Declaration
func shuffled<T>(using generator: inout T) > [ClosedRange<Bound>.Element] where T : RandomNumberGenerator
Declared In
BidirectionalCollection
, Sequence
Returns the elements of the sequence, sorted using the given predicate as the comparison between elements.
When you want to sort a sequence of elements that don't conform to the
Comparable
protocol, pass a predicate to this method that returns
true
when the first element passed should be ordered before the
second. The elements of the resulting array are ordered according to the
given predicate.
The predicate must be a strict weak ordering over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areInIncreasingOrder(a, a)
is alwaysfalse
. (Irreflexivity) If
areInIncreasingOrder(a, b)
andareInIncreasingOrder(b, c)
are bothtrue
, thenareInIncreasingOrder(a, c)
is alsotrue
. (Transitive comparability)  Two elements are incomparable if neither is ordered before the other
according to the predicate. If
a
andb
are incomparable, andb
andc
are incomparable, thena
andc
are also incomparable. (Transitive incomparability)
The sorting algorithm is not stable. A nonstable sort may change the
relative order of elements for which areInIncreasingOrder
does not
establish an order.
In the following example, the predicate provides an ordering for an array
of a custom HTTPResponse
type. The predicate orders errors before
successes and sorts the error responses by their error code.
enum HTTPResponse {
case ok
case error(Int)
}
let responses: [HTTPResponse] = [.error(500), .ok, .ok, .error(404), .error(403)]
let sortedResponses = responses.sorted {
switch ($0, $1) {
// Order errors by code
case let (.error(aCode), .error(bCode)):
return aCode < bCode
// All successes are equivalent, so none is before any other
case (.ok, .ok): return false
// Order errors before successes
case (.error, .ok): return true
case (.ok, .error): return false
}
}
print(sortedResponses)
// Prints "[.error(403), .error(404), .error(500), .ok, .ok]"
You also use this method to sort elements that conform to the
Comparable
protocol in descending order. To sort your sequence in
descending order, pass the greaterthan operator (>
) as the
areInIncreasingOrder
parameter.
let students: Set = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
let descendingStudents = students.sorted(by: >)
print(descendingStudents)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"
Calling the related sorted()
method is equivalent to calling this
method and passing the lessthan operator (<
) as the predicate.
print(students.sorted())
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"
print(students.sorted(by: <))
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"
areInIncreasingOrder
: A predicate that returns true
if its
first argument should be ordered before its second argument;
otherwise, false
.
Returns: A sorted array of the sequence's elements.
Declaration
func sorted(by areInIncreasingOrder: (ClosedRange<Bound>.Element, ClosedRange<Bound>.Element) throws > Bool) rethrows > [ClosedRange<Bound>.Element]
Declared In
BidirectionalCollection
, Sequence
Returns the longest possible subsequences of the collection, in order, that don't contain elements satisfying the given predicate.
The resulting array consists of at most maxSplits + 1
subsequences.
Elements that are used to split the sequence are not returned as part of
any subsequence.
The following examples show the effects of the maxSplits
and
omittingEmptySubsequences
parameters when splitting a string using a
closure that matches spaces. The first use of split
returns each word
that was originally separated by one or more spaces.
let line = "BLANCHE: I don't want realism. I want magic!"
print(line.split(whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
The second example passes 1
for the maxSplits
parameter, so the
original string is split just once, into two new strings.
print(line.split(maxSplits: 1, whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", " I don\'t want realism. I want magic!"]"
The final example passes false
for the omittingEmptySubsequences
parameter, so the returned array contains empty strings where spaces
were repeated.
print(line.split(omittingEmptySubsequences: false, whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
Parameters:
maxSplits: The maximum number of times to split the collection, or
one less than the number of subsequences to return. If
maxSplits + 1
subsequences are returned, the last one is a suffix
of the original collection containing the remaining elements.
maxSplits
must be greater than or equal to zero. The default value
is Int.max
.
omittingEmptySubsequences: If false
, an empty subsequence is
returned in the result for each pair of consecutive elements
satisfying the isSeparator
predicate and for each element at the
start or end of the collection satisfying the isSeparator
predicate. The default value is true
.
isSeparator: A closure that takes an element as an argument and
returns a Boolean value indicating whether the collection should be
split at that element.
Returns: An array of subsequences, split from this collection's
elements.
Declaration
func split(maxSplits: Int = default, omittingEmptySubsequences: Bool = default, whereSeparator isSeparator: (ClosedRange<Bound>.Element) throws > Bool) rethrows > [ClosedRange<Bound>.SubSequence]
Declared In
BidirectionalCollection
, Collection
Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.
The predicate must be a equivalence relation over the elements. That
is, for any elements a
, b
, and c
, the following conditions must
hold:
areEquivalent(a, a)
is alwaystrue
. (Reflexivity)areEquivalent(a, b)
impliesareEquivalent(b, a)
. (Symmetry) If
areEquivalent(a, b)
andareEquivalent(b, c)
are bothtrue
, thenareEquivalent(a, c)
is alsotrue
. (Transitivity)
Parameters:
possiblePrefix: A sequence to compare to this sequence.
areEquivalent: A predicate that returns true
if its two arguments
are equivalent; otherwise, false
.
Returns: true
if the initial elements of the sequence are equivalent
to the elements of possiblePrefix
; otherwise, false
. If
possiblePrefix
has no elements, the return value is true
.
Declaration
func starts<PossiblePrefix>(with possiblePrefix: PossiblePrefix, by areEquivalent: (ClosedRange<Bound>.Element, PossiblePrefix.Element) throws > Bool) rethrows > Bool where PossiblePrefix : Sequence
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence, up to the given maximum length, containing the final elements of the collection.
If the maximum length exceeds the number of elements in the collection, the result contains the entire collection.
let numbers = [1, 2, 3, 4, 5]
print(numbers.suffix(2))
// Prints "[4, 5]"
print(numbers.suffix(10))
// Prints "[1, 2, 3, 4, 5]"
maxLength
: The maximum number of elements to return.
maxLength
must be greater than or equal to zero.
Returns: A subsequence terminating at the end of the collection with at
most maxLength
elements.
Complexity: O(n), where n is equal to maxLength
.
Declaration
func suffix(_ maxLength: Int) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Returns a subsequence from the specified position to the end of the collection.
The following example searches for the index of the number 40
in an
array of integers, and then prints the suffix of the array starting at
that index:
let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
print(numbers.suffix(from: i))
}
// Prints "[40, 50, 60]"
Passing the collection's endIndex
as the start
parameter results in
an empty subsequence.
print(numbers.suffix(from: numbers.endIndex))
// Prints "[]"
Using the suffix(from:)
method is equivalent to using a partial range
from the index as the collection's subscript. The subscript notation is
preferred over suffix(from:)
.
if let i = numbers.firstIndex(of: 40) {
print(numbers[i...])
}
// Prints "[40, 50, 60]"
start
: The index at which to start the resulting subsequence.
start
must be a valid index of the collection.
Returns: A subsequence starting at the start
position.
Complexity: O(1)
Declaration
func suffix(from start: ClosedRange<Bound>.Index) > ClosedRange<Bound>.SubSequence
Declared In
BidirectionalCollection
, Collection
Conditionally Inherited Items
The initializers, methods, and properties listed below may be available on this type under certain conditions (such as methods that are available on Array
when its elements are Equatable
) or may not ever be available if that determination is beyond SwiftDoc.org's capabilities. Please open an issue on GitHub if you see something out of place!
Where Element : Collection
Returns the elements of this collection of collections, concatenated.
In this example, an array of three ranges is flattened so that the elements of each range can be iterated in turn.
let ranges = [0..<3, 8..<10, 15..<17]
// A forin loop over 'ranges' accesses each range:
for range in ranges {
print(range)
}
// Prints "0..<3"
// Prints "8..<10"
// Prints "15..<17"
// Use 'joined()' to access each element of each range:
for index in ranges.joined() {
print(index, terminator: " ")
}
// Prints: "0 1 2 8 9 15 16"
Returns: A flattened view of the elements of this collection of collections.
Declaration
func joined() > FlattenCollection<ClosedRange<Bound>>
Declared In
BidirectionalCollection
, Collection
Where Element : Comparable
Returns a Boolean value indicating whether the sequence precedes another
sequence in a lexicographical (dictionary) ordering, using the
lessthan operator (<
) to compare elements.
This example uses the lexicographicallyPrecedes
method to test which
array of integers comes first in a lexicographical ordering.
let a = [1, 2, 2, 2]
let b = [1, 2, 3, 4]
print(a.lexicographicallyPrecedes(b))
// Prints "true"
print(b.lexicographicallyPrecedes(b))
// Prints "false"
other
: A sequence to compare to this sequence.
Returns: true
if this sequence precedes other
in a dictionary
ordering; otherwise, false
.
Note: This method implements the mathematical notion of lexicographical
ordering, which has no connection to Unicode. If you are sorting
strings to present to the end user, use String
APIs that
perform localized comparison.
Declaration
func lexicographicallyPrecedes<OtherSequence>(_ other: OtherSequence) > Bool where OtherSequence : Sequence, ClosedRange<Bound>.Element == OtherSequence.Element
Declared In
BidirectionalCollection
, Sequence
Returns the maximum element in the sequence.
This example finds the largest value in an array of height measurements.
let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
let greatestHeight = heights.max()
print(greatestHeight)
// Prints "Optional(67.5)"
Returns: The sequence's maximum element. If the sequence has no
elements, returns nil
.
Declaration
@warn_unqualified_access
func max() > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
, Sequence
Returns the minimum element in the sequence.
This example finds the smallest value in an array of height measurements.
let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
let lowestHeight = heights.min()
print(lowestHeight)
// Prints "Optional(58.5)"
Returns: The sequence's minimum element. If the sequence has no
elements, returns nil
.
Declaration
@warn_unqualified_access
func min() > ClosedRange<Bound>.Element?
Declared In
BidirectionalCollection
, Sequence
Returns the elements of the sequence, sorted.
You can sort any sequence of elements that conform to the Comparable
protocol by calling this method. Elements are sorted in ascending order.
The sorting algorithm is not stable. A nonstable sort may change the relative order of elements that compare equal.
Here's an example of sorting a list of students' names. Strings in Swift
conform to the Comparable
protocol, so the names are sorted in
ascending order according to the lessthan operator (<
).
let students: Set = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
let sortedStudents = students.sorted()
print(sortedStudents)
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"
To sort the elements of your sequence in descending order, pass the
greaterthan operator (>
) to the sorted(by:)
method.
let descendingStudents = students.sorted(by: >)
print(descendingStudents)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"
Returns: A sorted array of the sequence's elements.
Declaration
func sorted() > [ClosedRange<Bound>.Element]
Declared In
BidirectionalCollection
, Sequence
Where Element : Equatable
Returns a Boolean value indicating whether the sequence contains the given element.
This example checks to see whether a favorite actor is in an array storing a movie's cast.
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
print(cast.contains("Marlon"))
// Prints "true"
print(cast.contains("James"))
// Prints "false"
element
: The element to find in the sequence.
Returns: true
if the element was found in the sequence; otherwise,
false
.
Declaration
func contains(_ element: ClosedRange<Bound>.Element) > Bool
Declared In
BidirectionalCollection
, Sequence
Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.
At least one of the sequences must be finite.
This example tests whether one countable range shares the same elements as another countable range and an array.
let a = 1...3
let b = 1...10
print(a.elementsEqual(b))
// Prints "false"
print(a.elementsEqual([1, 2, 3]))
// Prints "true"
other
: A sequence to compare to this sequence.
Returns: true
if this sequence and other
contain the same elements
in the same order.
Declaration
func elementsEqual<OtherSequence>(_ other: OtherSequence) > Bool where OtherSequence : Sequence, ClosedRange<Bound>.Element == OtherSequence.Element
Declared In
BidirectionalCollection
, Sequence
Returns the first index where the specified value appears in the collection.
After using firstIndex(of:)
to find the position of a particular element
in a collection, you can use it to access the element by subscripting.
This example shows how you can modify one of the names in an array of
students.
var students = ["Ben", "Ivy", "Jordell", "Maxime"]
if let i = students.firstIndex(of: "Maxime") {
students[i] = "Max"
}
print(students)
// Prints "["Ben", "Ivy", "Jordell", "Max"]"
element
: An element to search for in the collection.
Returns: The first index where element
is found. If element
is not
found in the collection, returns nil
.
Declaration
func firstIndex(of element: ClosedRange<Bound>.Element) > ClosedRange<Bound>.Index?
Declared In
BidirectionalCollection
, Collection
Returns the last index where the specified value appears in the collection.
After using lastIndex(of:)
to find the position of the last instance of
a particular element in a collection, you can use it to access the
element by subscripting. This example shows how you can modify one of
the names in an array of students.
var students = ["Ben", "Ivy", "Jordell", "Ben", "Maxime"]
if let i = students.lastIndex(of: "Ben") {
students[i] = "Benjamin"
}
print(students)
// Prints "["Ben", "Ivy", "Jordell", "Benjamin", "Max"]"
element
: An element to search for in the collection.
Returns: The last index where element
is found. If element
is not
found in the collection, returns nil
.
Declaration
func lastIndex(of element: ClosedRange<Bound>.Element) > ClosedRange<Bound>.Index?
Declared In
BidirectionalCollection
Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.
The resulting array consists of at most maxSplits + 1
subsequences.
Elements that are used to split the collection are not returned as part
of any subsequence.
The following examples show the effects of the maxSplits
and
omittingEmptySubsequences
parameters when splitting a string at each
space character (" "). The first use of split
returns each word that
was originally separated by one or more spaces.
let line = "BLANCHE: I don't want realism. I want magic!"
print(line.split(separator: " "))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
The second example passes 1
for the maxSplits
parameter, so the
original string is split just once, into two new strings.
print(line.split(separator: " ", maxSplits: 1))
// Prints "["BLANCHE:", " I don\'t want realism. I want magic!"]"
The final example passes false
for the omittingEmptySubsequences
parameter, so the returned array contains empty strings where spaces
were repeated.
print(line.split(separator: " ", omittingEmptySubsequences: false))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
Parameters:
separator: The element that should be split upon.
maxSplits: The maximum number of times to split the collection, or
one less than the number of subsequences to return. If
maxSplits + 1
subsequences are returned, the last one is a suffix
of the original collection containing the remaining elements.
maxSplits
must be greater than or equal to zero. The default value
is Int.max
.
omittingEmptySubsequences: If false
, an empty subsequence is
returned in the result for each consecutive pair of separator
elements in the collection and for each instance of separator
at
the start or end of the collection. If true
, only nonempty
subsequences are returned. The default value is true
.
Returns: An array of subsequences, split from this collection's
elements.
Declaration
func split(separator: ClosedRange<Bound>.Element, maxSplits: Int = default, omittingEmptySubsequences: Bool = default) > [ClosedRange<Bound>.SubSequence]
Declared In
BidirectionalCollection
, Collection
, Sequence
Returns a Boolean value indicating whether the initial elements of the sequence are the same as the elements in another sequence.
This example tests whether one countable range begins with the elements of another countable range.
let a = 1...3
let b = 1...10
print(b.starts(with: a))
// Prints "true"
Passing a sequence with no elements or an empty collection as
possiblePrefix
always results in true
.
print(b.starts(with: []))
// Prints "true"
possiblePrefix
: A sequence to compare to this sequence.
Returns: true
if the initial elements of the sequence are the same as
the elements of possiblePrefix
; otherwise, false
. If
possiblePrefix
has no elements, the return value is true
.
Declaration
func starts<PossiblePrefix>(with possiblePrefix: PossiblePrefix) > Bool where PossiblePrefix : Sequence, ClosedRange<Bound>.Element == PossiblePrefix.Element
Declared In
BidirectionalCollection
, Sequence
Where Element : Sequence
Returns the elements of this sequence of sequences, concatenated.
In this example, an array of three ranges is flattened so that the elements of each range can be iterated in turn.
let ranges = [0..<3, 8..<10, 15..<17]
// A forin loop over 'ranges' accesses each range:
for range in ranges {
print(range)
}
// Prints "0..<3"
// Prints "8..<10"
// Prints "15..<17"
// Use 'joined()' to access each element of each range:
for index in ranges.joined() {
print(index, terminator: " ")
}
// Prints: "0 1 2 8 9 15 16"
Returns: A flattened view of the elements of this sequence of sequences.
Declaration
func joined() > FlattenSequence<ClosedRange<Bound>>
Declared In
BidirectionalCollection
, Sequence
Returns the concatenated elements of this sequence of sequences, inserting the given separator between each element.
This example shows how an array of [Int]
instances can be joined, using
another [Int]
instance as the separator:
let nestedNumbers = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
let joined = nestedNumbers.joined(separator: [1, 2])
print(Array(joined))
// Prints "[1, 2, 3, 1, 2, 4, 5, 6, 1, 2, 7, 8, 9]"
separator
: A sequence to insert between each of this
sequence's elements.
Returns: The joined sequence of elements.
Declaration
func joined<Separator>(separator: Separator) > JoinedSequence<ClosedRange<Bound>> where Separator : Sequence, Separator.Element == ClosedRange<Bound>.Element.Element
Declared In
BidirectionalCollection
, Sequence
Where Element : StringProtocol
Returns a new string by concatenating the elements of the sequence, adding the given separator between each element.
The following example shows how an array of strings can be joined to a single, commaseparated string:
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let list = cast.joined(separator: ", ")
print(list)
// Prints "Vivien, Marlon, Kim, Karl"
separator
: A string to insert between each of the elements
in this sequence. The default separator is an empty string.
Returns: A single, concatenated string.
Declaration
func joined(separator: String = default) > String
Declared In
BidirectionalCollection
, Sequence
Where Index : Strideable, Indices == Range, Index.Stride == Int
The indices that are valid for subscripting the collection, in ascending order.
Declaration
var indices: Range<ClosedRange<Bound>.Index> { get }
Declared In
RandomAccessCollection
Returns the distance between two indices.
Parameters:
start: A valid index of the collection.
end: Another valid index of the collection. If end
is equal to
start
, the result is zero.
Returns: The distance between start
and end
.
Complexity: O(1)
Declaration
func distance(from start: ClosedRange<Bound>.Index, to end: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index.Stride
Declared In
RandomAccessCollection
Returns an index that is the specified distance from the given index.
The following example obtains an index advanced four positions from an array's starting index and then prints the element at that position.
let numbers = [10, 20, 30, 40, 50]
let i = numbers.index(numbers.startIndex, offsetBy: 4)
print(numbers[i])
// Prints "50"
The value passed as n
must not offset i
beyond the bounds of the
collection.
Parameters:
i: A valid index of the collection.
n: The distance to offset i
.
Returns: An index offset by n
from the index i
. If n
is positive,
this is the same value as the result of n
calls to index(after:)
.
If n
is negative, this is the same value as the result of n
calls
to index(before:)
.
Complexity: O(1)
Declaration
func index(_ i: ClosedRange<Bound>.Index, offsetBy n: ClosedRange<Bound>.Index.Stride) > ClosedRange<Bound>.Index
Declared In
RandomAccessCollection
Returns the position immediately after the given index.
i
: A valid index of the collection. i
must be less than
endIndex
.
Returns: The index value immediately after i
.
Declaration
func index(after i: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index
Declared In
RandomAccessCollection
Returns the position immediately after the given index.
i
: A valid index of the collection. i
must be greater than
startIndex
.
Returns: The index value immediately before i
.
Declaration
func index(before i: ClosedRange<Bound>.Index) > ClosedRange<Bound>.Index
Declared In
RandomAccessCollection
Where Indices == DefaultIndices
The indices that are valid for subscripting the collection, in ascending order.
A collection's indices
property can hold a strong reference to the
collection itself, causing the collection to be nonuniquely referenced.
If you mutate the collection while iterating over its indices, a strong
reference can cause an unexpected copy of the collection. To avoid the
unexpected copy, use the index(after:)
method starting with
startIndex
to produce indices instead.
var c = MyFancyCollection([10, 20, 30, 40, 50])
var i = c.startIndex
while i != c.endIndex {
c[i] /= 5
i = c.index(after: i)
}
// c == MyFancyCollection([2, 4, 6, 8, 10])
Declaration
var indices: DefaultIndices<ClosedRange<Bound>> { get }
Declared In
BidirectionalCollection
, Collection
Where Iterator == IndexingIterator
Returns an iterator over the elements of the collection.
Declaration
func makeIterator() > IndexingIterator<ClosedRange<Bound>>
Declared In
BidirectionalCollection
, Collection
Where SubSequence == AnySequence
Returns a subsequence by skipping the initial, consecutive elements that satisfy the given predicate.
The following example uses the drop(while:)
method to skip over the
positive numbers at the beginning of the numbers
array. The result
begins with the first element of numbers
that does not satisfy
predicate
.
let numbers = [3, 7, 4, 2, 9, 6, 10, 1]
let startingWithNegative = numbers.drop(while: { $0 > 0 })
// startingWithNegative == [2, 9, 6, 10, 1]
If predicate
matches every element in the sequence, the result is an
empty sequence.
predicate
: A closure that takes an element of the sequence as
its argument and returns a Boolean value indicating whether the
element should be included in the result.
Returns: A subsequence starting after the initial, consecutive elements
that satisfy predicate
.
Complexity: O(n), where n is the length of the collection.
Declaration
func drop(while predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence containing all but the given number of initial elements.
If the number of elements to drop exceeds the number of elements in the sequence, the result is an empty subsequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst(2))
// Prints "[3, 4, 5]"
print(numbers.dropFirst(10))
// Prints "[]"
n
: The number of elements to drop from the beginning of
the sequence. n
must be greater than or equal to zero.
Returns: A subsequence starting after the specified number of
elements.
Complexity: O(1).
Declaration
func dropFirst(_ n: Int) > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence containing all but the given number of final elements.
The sequence must be finite. If the number of elements to drop exceeds the number of elements in the sequence, the result is an empty subsequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast(2))
// Prints "[1, 2, 3]"
print(numbers.dropLast(10))
// Prints "[]"
n
: The number of elements to drop off the end of the
sequence. n
must be greater than or equal to zero.
Returns: A subsequence leaving off the specified number of elements.
Complexity: O(n), where n is the length of the sequence.
Declaration
func dropLast(_ n: Int) > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence, up to the specified maximum length, containing the initial elements of the sequence.
If the maximum length exceeds the number of elements in the sequence, the result contains all the elements in the sequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.prefix(2))
// Prints "[1, 2]"
print(numbers.prefix(10))
// Prints "[1, 2, 3, 4, 5]"
maxLength
: The maximum number of elements to return. The
value of maxLength
must be greater than or equal to zero.
Returns: A subsequence starting at the beginning of this sequence
with at most maxLength
elements.
Complexity: O(1)
Declaration
func prefix(_ maxLength: Int) > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence containing the initial, consecutive elements that satisfy the given predicate.
The following example uses the prefix(while:)
method to find the
positive numbers at the beginning of the numbers
array. Every element
of numbers
up to, but not including, the first negative value is
included in the result.
let numbers = [3, 7, 4, 2, 9, 6, 10, 1]
let positivePrefix = numbers.prefix(while: { $0 > 0 })
// positivePrefix == [3, 7, 4]
If predicate
matches every element in the sequence, the resulting
sequence contains every element of the sequence.
predicate
: A closure that takes an element of the sequence as
its argument and returns a Boolean value indicating whether the
element should be included in the result.
Returns: A subsequence of the initial, consecutive elements that
satisfy predicate
.
Complexity: O(n), where n is the length of the collection.
Declaration
func prefix(while predicate: (ClosedRange<Bound>.Element) throws > Bool) rethrows > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Returns the longest possible subsequences of the sequence, in order, that don't contain elements satisfying the given predicate. Elements that are used to split the sequence are not returned as part of any subsequence.
The following examples show the effects of the maxSplits
and
omittingEmptySubsequences
parameters when splitting a string using a
closure that matches spaces. The first use of split
returns each word
that was originally separated by one or more spaces.
let line = "BLANCHE: I don't want realism. I want magic!"
print(line.split(whereSeparator: { $0 == " " })
.map(String.init))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
The second example passes 1
for the maxSplits
parameter, so the
original string is split just once, into two new strings.
print(
line.split(maxSplits: 1, whereSeparator: { $0 == " " })
.map(String.init))
// Prints "["BLANCHE:", " I don\'t want realism. I want magic!"]"
The final example passes true
for the allowEmptySlices
parameter, so
the returned array contains empty strings where spaces were repeated.
print(
line.split(
omittingEmptySubsequences: false,
whereSeparator: { $0 == " " }
).map(String.init))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
Parameters:
maxSplits: The maximum number of times to split the sequence, or one
less than the number of subsequences to return. If maxSplits + 1
subsequences are returned, the last one is a suffix of the original
sequence containing the remaining elements. maxSplits
must be
greater than or equal to zero. The default value is Int.max
.
omittingEmptySubsequences: If false
, an empty subsequence is
returned in the result for each pair of consecutive elements
satisfying the isSeparator
predicate and for each element at the
start or end of the sequence satisfying the isSeparator
predicate.
If true
, only nonempty subsequences are returned. The default
value is true
.
isSeparator: A closure that returns true
if its argument should be
used to split the sequence; otherwise, false
.
Returns: An array of subsequences, split from this sequence's elements.
Declaration
func split(maxSplits: Int = default, omittingEmptySubsequences: Bool = default, whereSeparator isSeparator: (ClosedRange<Bound>.Element) throws > Bool) rethrows > [AnySequence<ClosedRange<Bound>.Element>]
Declared In
BidirectionalCollection
, Sequence
Returns a subsequence, up to the given maximum length, containing the final elements of the sequence.
The sequence must be finite. If the maximum length exceeds the number of elements in the sequence, the result contains all the elements in the sequence.
let numbers = [1, 2, 3, 4, 5]
print(numbers.suffix(2))
// Prints "[4, 5]"
print(numbers.suffix(10))
// Prints "[1, 2, 3, 4, 5]"
maxLength
: The maximum number of elements to return. The
value of maxLength
must be greater than or equal to zero.
Complexity: O(n), where n is the length of the sequence.
Declaration
func suffix(_ maxLength: Int) > AnySequence<ClosedRange<Bound>.Element>
Declared In
BidirectionalCollection
, Sequence
Where SubSequence == Slice
Accesses a contiguous subrange of the collection's elements.
The accessed slice uses the same indices for the same elements as the
original collection. Always use the slice's startIndex
property
instead of assuming that its indices start at a particular value.
This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.
let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"
let index = streetsSlice.firstIndex(of: "Evarts") // 4
print(streets[index!])
// Prints "Evarts"
bounds
: A range of the collection's indices. The bounds of
the range must be valid indices of the collection.
Complexity: O(1)
Declaration
subscript(bounds: Range<ClosedRange<Bound>.Index>) > Slice<ClosedRange<Bound>> { get }
Declared In
BidirectionalCollection
, Collection
An interval from a lower bound up to, and including, an upper bound.
You create a
ClosedRange
instance by using the closed range operator (...
).A
ClosedRange
instance contains both its lower bound and its upper bound.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.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 afor
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.Because floatingpoint types such as
Float
andDouble
are their ownStride
types, they cannot be used as the bounds of a countable range. If you need to iterate over consecutive floatingpoint values, see thestride(from:through:by:)
function.