Protocol

BidirectionalCollection

A collection that supports backward as well as forward traversal.

Declaration

protocol BidirectionalCollection 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 index i into a bidirectional collection c:

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

  • If i > c.startIndex && i <= c.endIndex c.index(after: c.index(before: i)) == i.

Topics

Associated Types

associatedtype Element

Required.

associatedtype Index

Required.

associatedtype Indices

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

Required.

associatedtype SubSequence

A sequence that can represent a contiguous subrange of the collection’s elements.

Required.

Instance Properties

var endIndex: Self.Index

Required.

var indices: Self.Indices

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

Required.

var last: Self.Element?

The last element of the collection.

var startIndex: Self.Index

Required.

Instance Methods

func difference<C>(from: C) -> CollectionDifference<Self.Element>

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

Available when Element conforms to Equatable.
func difference<C>(from: C, by: (C.Element, Self.Element) -> Bool) -> CollectionDifference<Self.Element>

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

Returns the distance between two indices.

Required. Default implementation provided.

func dropLast(Int) -> Self.SubSequence

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

func formIndex(after: inout Self.Index)

Replaces the given index with its successor.

Required.

func formIndex(before: inout Self.Index)

Replaces the given index with its predecessor.

Required. Default implementation provided.

func index(Self.Index, offsetBy: Int) -> Self.Index

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

Required. Default implementation provided.

func index(Self.Index, offsetBy: Int, limitedBy: Self.Index) -> Self.Index?

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

Required. Default implementation provided.

func index(after: Self.Index) -> Self.Index

Returns the position immediately after the given index.

Required.

func index(before: Self.Index) -> Self.Index

Returns the position immediately before the given index.

Required.

func joined(separator: String) -> String

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

Available when Element is String.
func last(where: (Self.Element) -> Bool) -> Self.Element?

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

func lastIndex(of: Self.Element) -> Self.Index?

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

Available when Element conforms to Equatable.
func lastIndex(where: (Self.Element) -> Bool) -> Self.Index?

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

func popLast() -> Self.Element?

Removes and returns the last element of the collection.

Available when Self is SubSequence.
func removeLast() -> Self.Element

Removes and returns the last element of the collection.

Available when Self is SubSequence.
func removeLast(Int)

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

Available when Self is SubSequence.
func reversed() -> ReversedCollection<Self>

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

func suffix(Int) -> Self.SubSequence

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

Subscripts

subscript(Range<Self.Index>) -> Self.SubSequence

Accesses a contiguous subrange of the collection’s elements.

Required.

subscript(Self.Index) -> Self.Element

Required.

Relationships

Inherits From

Inherited By

Conforming Types

See Also

Collection Traversal

protocol RandomAccessCollection

A collection that supports efficient random-access index traversal.