<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.10.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Swift",
  "identifier" : "/documentation/Swift/BidirectionalCollection",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Swift"
    ],
    "preciseIdentifier" : "s:SK"
  },
  "title" : "BidirectionalCollection"
}
-->

# BidirectionalCollection

A collection that supports backward as well as forward traversal.

```
protocol BidirectionalCollection<Element> : Collection where Self.Indices : BidirectionalCollection, Self.SubSequence : BidirectionalCollection
```

## Overview

Bidirectional collections offer traversal backward from any valid index,
not including a collection’s `startIndex`. Bidirectional collections can
therefore offer additional operations, such as a `last` property that
provides efficient access to the last element and a `reversed()` method
that presents the elements in reverse order. In addition, bidirectional
collections have more efficient implementations of some sequence and
collection methods, such as `suffix(_:)`.

# Conforming to the BidirectionalCollection Protocol

To add `BidirectionalProtocol` conformance to your custom types, implement
the `index(before:)` method in addition to the requirements of the
`Collection` protocol.

Indices that are moved forward and backward in a bidirectional collection
move by the same amount in each direction. That is, for any valid index `i`
into a bidirectional collection `c`:

- If `i >= c.startIndex && i < c.endIndex`, then
  `c.index(before: c.index(after: i)) == i`.
- If `i > c.startIndex && i <= c.endIndex`, then
  `c.index(after: c.index(before: i)) == i`.

Valid indices are exactly those indices that are reachable from the
collection’s `startIndex` by repeated applications of `index(after:)`, up
to, and including, the `endIndex`.

## Topics

### Associated Types

[`associatedtype Element`](/documentation/Swift/BidirectionalCollection/Element)

A type representing the sequence’s elements.

[`associatedtype Index`](/documentation/Swift/BidirectionalCollection/Index)

A type that represents a position in the collection.

[`associatedtype Indices`](/documentation/Swift/BidirectionalCollection/Indices-swift.associatedtype)

A type that represents the indices that are valid for subscripting the
collection, in ascending order.

[`associatedtype SubSequence`](/documentation/Swift/BidirectionalCollection/SubSequence)

A collection representing a contiguous subrange of this collection’s
elements. The subsequence shares indices with the original collection.

### Instance Properties

[`var endIndex: Self.Index`](/documentation/Swift/BidirectionalCollection/endIndex)

The collection’s “past the end” position—that is, the position one
greater than the last valid subscript argument.

[`var indices: Self.Indices`](/documentation/Swift/BidirectionalCollection/indices-4qv42)

The indices that are valid for subscripting the collection, in ascending
order.

[`var last: Self.Element?`](/documentation/Swift/BidirectionalCollection/last)

The last element of the collection.

[`var startIndex: Self.Index`](/documentation/Swift/BidirectionalCollection/startIndex)

The position of the first element in a nonempty collection.

### Instance Methods

[`func contains(some RegexComponent) -> Bool`](/documentation/Swift/BidirectionalCollection/contains(_:)-1l08t)

Returns a Boolean value indicating whether the collection contains the
given regex.

[`func contains(() -> some RegexComponent) -> Bool`](/documentation/Swift/BidirectionalCollection/contains(_:)-60wyq)

Returns a Boolean value indicating whether this collection contains a
match for the regex, where the regex is created by the given closure.

[`func difference<C>(from: C) -> CollectionDifference<Self.Element>`](/documentation/Swift/BidirectionalCollection/difference(from:))

Returns the difference needed to produce this collection’s ordered
elements from the given collection.

[`func difference<C>(from: C, by: (C.Element, Self.Element) -> Bool) -> CollectionDifference<Self.Element>`](/documentation/Swift/BidirectionalCollection/difference(from:by:))

Returns the difference needed to produce this collection’s ordered
elements from the given collection, using the given predicate as an
equivalence test.

[`func distance(from: Self.Index, to: Self.Index) -> Int`](/documentation/Swift/BidirectionalCollection/distance(from:to:))

Returns the distance between two indices.

[`func dropLast(Int) -> Self.SubSequence`](/documentation/Swift/BidirectionalCollection/dropLast(_:))

Returns a subsequence containing all but the specified number of final
elements.

[`func firstMatch<Output>(of: () -> some RegexComponent) -> Regex<Output>.Match?`](/documentation/Swift/BidirectionalCollection/firstMatch(of:)-6v8ci)

Returns the first match for the regex within this collection, where
the regex is created by the given closure.

[`func firstMatch<Output>(of: some RegexComponent) -> Regex<Output>.Match?`](/documentation/Swift/BidirectionalCollection/firstMatch(of:)-7m8f4)

Returns the first match of the specified regex within the collection.

[`func firstRange(of: some RegexComponent) -> Range<Self.Index>?`](/documentation/Swift/BidirectionalCollection/firstRange(of:)-1di7b)

Finds and returns the range of the first occurrence of a given regex
within the collection.

[`func firstRange(of: () -> some RegexComponent) -> Range<Self.Index>?`](/documentation/Swift/BidirectionalCollection/firstRange(of:)-3jqrg)

Returns the range of the first match for the regex within this collection,
where the regex is created by the given closure.

[`func firstRange<C>(of: C) -> Range<Self.Index>?`](/documentation/Swift/BidirectionalCollection/firstRange(of:)-5sum7)

Finds and returns the range of the first occurrence of a given collection
within this collection.

[`func formIndex(after: inout Self.Index)`](/documentation/Swift/BidirectionalCollection/formIndex(after:))

Replaces the given index with its successor.

[`func formIndex(before: inout Self.Index)`](/documentation/Swift/BidirectionalCollection/formIndex(before:))

Replaces the given index with its predecessor.

[`func index(Self.Index, offsetBy: Int) -> Self.Index`](/documentation/Swift/BidirectionalCollection/index(_:offsetBy:))

Returns an index that is the specified distance from the given index.

[`func index(Self.Index, offsetBy: Int, limitedBy: Self.Index) -> Self.Index?`](/documentation/Swift/BidirectionalCollection/index(_:offsetBy:limitedBy:))

Returns an index that is the specified distance from the given index,
unless that distance is beyond a given limiting index.

[`func index(after: Self.Index) -> Self.Index`](/documentation/Swift/BidirectionalCollection/index(after:))

Returns the position immediately after the given index.

[`func index(before: Self.Index) -> Self.Index`](/documentation/Swift/BidirectionalCollection/index(before:))

Returns the position immediately before the given index.

[`func joined(separator: String) -> String`](/documentation/Swift/BidirectionalCollection/joined(separator:))

Returns a new string by concatenating the elements of the sequence,
adding the given separator between each element.

[`func last(where: (Self.Element) throws -> Bool) rethrows -> Self.Element?`](/documentation/Swift/BidirectionalCollection/last(where:))

Returns the last element of the sequence that satisfies the given
predicate.

[`func lastIndex(of: Self.Element) -> Self.Index?`](/documentation/Swift/BidirectionalCollection/lastIndex(of:))

Returns the last index where the specified value appears in the
collection.

[`func lastIndex(where: (Self.Element) throws -> Bool) rethrows -> Self.Index?`](/documentation/Swift/BidirectionalCollection/lastIndex(where:))

Returns the index of the last element in the collection that matches the
given predicate.

[`func matches<Output>(of: () -> some RegexComponent) -> [Regex<Output>.Match]`](/documentation/Swift/BidirectionalCollection/matches(of:)-5eey9)

Returns a collection containing all non-overlapping matches of
the regex, created by the given closure.

[`func matches<Output>(of: some RegexComponent) -> [Regex<Output>.Match]`](/documentation/Swift/BidirectionalCollection/matches(of:)-5hhx)

Returns a collection containing all matches of the specified regex.

[`func popLast() -> Self.Element?`](/documentation/Swift/BidirectionalCollection/popLast())

Removes and returns the last element of the collection.

[`func prefixMatch<Output>(of: () -> some RegexComponent) -> Regex<Output>.Match?`](/documentation/Swift/BidirectionalCollection/prefixMatch(of:)-2fwv6)

Matches part of the regex, starting at the beginning, where the regex
is created by the given closure.

[`func prefixMatch<R>(of: R) -> Regex<R.RegexOutput>.Match?`](/documentation/Swift/BidirectionalCollection/prefixMatch(of:)-7dq6v)

Returns a match if this string is matched by the given regex at its start.

[`func ranges(of: some RegexComponent) -> [Range<Self.Index>]`](/documentation/Swift/BidirectionalCollection/ranges(of:)-40wx3)

Finds and returns the ranges of the all occurrences of a given sequence
within the collection.

[`func ranges(of: () -> some RegexComponent) -> [Range<Self.Index>]`](/documentation/Swift/BidirectionalCollection/ranges(of:)-9qfdo)

Returns the ranges of the all non-overlapping matches for the regex
within this collection, where the regex is created by the given closure.

[`func removeLast() -> Self.Element`](/documentation/Swift/BidirectionalCollection/removeLast())

Removes and returns the last element of the collection.

[`func removeLast(Int)`](/documentation/Swift/BidirectionalCollection/removeLast(_:))

Removes the given number of elements from the end of the collection.

[`func reversed() -> ReversedCollection<Self>`](/documentation/Swift/BidirectionalCollection/reversed())

Returns a view presenting the elements of the collection in reverse
order.

[`func split(maxSplits: Int, omittingEmptySubsequences: Bool, separator: () -> some RegexComponent) -> [Self.SubSequence]`](/documentation/Swift/BidirectionalCollection/split(maxSplits:omittingEmptySubsequences:separator:))

Returns the longest possible subsequences of the collection, in order,
around subsequence that match the regex created by the given closure.

[`func split(separator: some RegexComponent, maxSplits: Int, omittingEmptySubsequences: Bool) -> [Self.SubSequence]`](/documentation/Swift/BidirectionalCollection/split(separator:maxSplits:omittingEmptySubsequences:))

Returns the longest possible subsequences of the collection, in order,
around elements equal to the given separator.

[`func starts(with: some RegexComponent) -> Bool`](/documentation/Swift/BidirectionalCollection/starts(with:)-4972u)

Returns a Boolean value indicating whether the initial elements of the
sequence are the same as the elements in the specified regex.

[`func starts(with: () -> some RegexComponent) -> Bool`](/documentation/Swift/BidirectionalCollection/starts(with:)-97xlm)

Returns a Boolean value indicating whether the initial elements of this
collection are a match for the regex created by the given closure.

[`func suffix(Int) -> Self.SubSequence`](/documentation/Swift/BidirectionalCollection/suffix(_:))

Returns a subsequence, up to the given maximum length, containing the
final elements of the collection.

[`func trimmingPrefix(some RegexComponent) -> Self.SubSequence`](/documentation/Swift/BidirectionalCollection/trimmingPrefix(_:)-1luge)

Returns a new collection of the same type by removing the initial elements
that matches the given regex.

[`func trimmingPrefix(() -> some RegexComponent) -> Self.SubSequence`](/documentation/Swift/BidirectionalCollection/trimmingPrefix(_:)-781ik)

Returns a subsequence of this collection by removing the elements
matching the regex from the start, where the regex is created by
the given closure.

[`func wholeMatch<Output>(of: () -> some RegexComponent) -> Regex<Output>.Match?`](/documentation/Swift/BidirectionalCollection/wholeMatch(of:)-1wbp6)

Matches a regex in its entirety, where the regex is created by
the given closure.

[`func wholeMatch<R>(of: R) -> Regex<R.RegexOutput>.Match?`](/documentation/Swift/BidirectionalCollection/wholeMatch(of:)-7741n)

Returns a match if this string is matched by the given regex in its entirety.

### Subscripts

[`subscript(Self.Index) -> Self.Element`](/documentation/Swift/BidirectionalCollection/subscript(_:)-5tj5)

Accesses the element at the specified position.

[`subscript(Range<Self.Index>) -> Self.SubSequence`](/documentation/Swift/BidirectionalCollection/subscript(_:)-7tzd8)

Accesses a contiguous subrange of the collection’s elements.

## Relationships

### Conforming Types

[`UnicodeScalarView`](/documentation/Swift/String/UnicodeScalarView)

[`FlattenSequence`](/documentation/Swift/FlattenSequence)

[`UnsafeMutableRawBufferPointer`](/documentation/Swift/UnsafeMutableRawBufferPointer)

[`DefaultIndices`](/documentation/Swift/DefaultIndices)

[`LazyPrefixWhileSequence`](/documentation/Swift/LazyPrefixWhileSequence)

[`LazyFilterSequence`](/documentation/Swift/LazyFilterSequence)

[`DiscontiguousSlice`](/documentation/Swift/DiscontiguousSlice)

[`UnsafeBufferPointer`](/documentation/Swift/UnsafeBufferPointer)

[`Slice`](/documentation/Swift/Slice)

[`UnicodeScalarView`](/documentation/Swift/Substring/UnicodeScalarView)

[`Ranges-swift.struct`](/documentation/Swift/RangeSet/Ranges-swift.struct)

[`LazySequence`](/documentation/Swift/LazySequence)

[`ClosedRange`](/documentation/Swift/ClosedRange)

[`EnumeratedSequence`](/documentation/Swift/EnumeratedSequence)

[`ReversedCollection`](/documentation/Swift/ReversedCollection)

[`ArraySlice`](/documentation/Swift/ArraySlice)

[`UTF16View`](/documentation/Swift/String/UTF16View)

[`Words-swift.struct`](/documentation/Swift/UInt128/Words-swift.struct)

[`LazyMapSequence`](/documentation/Swift/LazyMapSequence)

[`Words-swift.struct`](/documentation/Swift/Int8/Words-swift.struct)

[`Array`](/documentation/Swift/Array)

[`Range`](/documentation/Swift/Range)

[`Words-swift.struct`](/documentation/Swift/UInt32/Words-swift.struct)

[`Substring`](/documentation/Swift/Substring)

[`UTF8View`](/documentation/Swift/String/UTF8View)

[`String`](/documentation/Swift/String)

[`UTF16View`](/documentation/Swift/Unicode/Scalar/UTF16View)

[`ContiguousArray`](/documentation/Swift/ContiguousArray)

[`Words-swift.struct`](/documentation/Swift/UInt8/Words-swift.struct)

[`AnyRandomAccessCollection`](/documentation/Swift/AnyRandomAccessCollection)

[`Repeated`](/documentation/Swift/Repeated)

[`Words-swift.struct`](/documentation/Swift/UInt64/Words-swift.struct)

[`CollectionOfOne`](/documentation/Swift/CollectionOfOne)

[`UnsafeMutableBufferPointer`](/documentation/Swift/UnsafeMutableBufferPointer)

[`Words-swift.struct`](/documentation/Swift/Int32/Words-swift.struct)

[`KeyValuePairs`](/documentation/Swift/KeyValuePairs)

[`UTF8View`](/documentation/Swift/Unicode/Scalar/UTF8View)

[`UnsafeRawBufferPointer`](/documentation/Swift/UnsafeRawBufferPointer)

[`UTF16View`](/documentation/Swift/Substring/UTF16View)

[`Words-swift.struct`](/documentation/Swift/Int16/Words-swift.struct)

[`LazyDropWhileSequence`](/documentation/Swift/LazyDropWhileSequence)

[`EmptyCollection`](/documentation/Swift/EmptyCollection)

[`AnyRegexOutput`](/documentation/Swift/AnyRegexOutput)

[`Words-swift.struct`](/documentation/Swift/UInt/Words-swift.struct)

[`UTF8View`](/documentation/Swift/Substring/UTF8View)

[`AnyBidirectionalCollection`](/documentation/Swift/AnyBidirectionalCollection)

[`Words-swift.struct`](/documentation/Swift/Int64/Words-swift.struct)

[`Words-swift.struct`](/documentation/Swift/UInt16/Words-swift.struct)

[`Words-swift.struct`](/documentation/Swift/Int/Words-swift.struct)

### Inherited By

[`StringProtocol`](/documentation/Swift/StringProtocol)

[`RandomAccessCollection`](/documentation/Swift/RandomAccessCollection)

### Inherits From

[`Collection`](/documentation/Swift/Collection)

[`Sequence`](/documentation/Swift/Sequence)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)