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 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 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.

Required. Default implementations provided.

Instance Methods

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.

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

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

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.

func removeLast() -> Self.Element

Removes and returns the last element of the collection.

func removeLast(Int)

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

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.

Relationships

Inherits From

Conforming Types

See Also

Collection Traversal

protocol RandomAccessCollection

A collection that supports efficient random-access index traversal.