Protocol

RangeReplaceableCollection

A collection that supports replacement of an arbitrary subrange of elements with the elements of another collection.

Overview

Range-replaceable collections provide operations that insert and remove elements. For example, you can add elements to an array of strings by calling any of the inserting or appending operations that the RangeReplaceableCollection protocol defines.

var bugs = ["Aphid", "Damselfly"]
bugs.append("Earwig")
bugs.insert(contentsOf: ["Bumblebee", "Cicada"], at: 1)
print(bugs)
// Prints "["Aphid", "Bumblebee", "Cicada", "Damselfly", "Earwig"]"

Likewise, RangeReplaceableCollection types can remove one or more elements using a single operation.

bugs.removeLast()
bugs.removeSubrange(1...2)
print(bugs)
// Prints "["Aphid", "Damselfly"]"

bugs.removeAll()
print(bugs)
// Prints "[]"

Lastly, use the eponymous replaceSubrange(_:with:) method to replace a subrange of elements with the contents of another collection. Here, three elements in the middle of an array of integers are replaced by the five elements of a Repeated<Int> instance.

 var nums = [10, 20, 30, 40, 50]
 nums.replaceSubrange(1...3, with: repeatElement(1, count: 5))
 print(nums)
 // Prints "[10, 1, 1, 1, 1, 1, 50]"

Conforming to the RangeReplaceableCollection Protocol

To add RangeReplaceableCollection conformance to your custom collection, add an empty initializer and the replaceSubrange(_:with:) method to your custom type. RangeReplaceableCollection provides default implementations of all its other methods using this initializer and method. For example, the removeSubrange(_:) method is implemented by calling replaceSubrange(_:with:) with an empty collection for the newElements parameter. You can override any of the protocol’s required methods to provide your own custom implementation.

Topics

Creating a New Collection

init()

Creates a new, empty collection.

Required.

Adding Elements

func insert<S>(contentsOf: S, at: Self.Index)

Inserts the elements of a sequence into the collection at the specified position.

Required. Default implementation provided.

func replaceSubrange<C>(Range<Self.Index>, with: C)

Replaces the specified subrange of elements with the given collection.

Required. Default implementation provided.

func reserveCapacity(Self.IndexDistance)

Prepares the collection to store the specified number of elements, when doing so is appropriate for the underlying type.

Required. Default implementation provided.

Beta

Removing Elements

func removeFirst(Int)

Removes the specified number of elements from the beginning of the collection.

Required. Default implementations provided.

Beta
func removeLast(Int)

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

Beta
func removeLast(Int)

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

Beta
func removeSubrange(Range<Self.Index>)

Removes the elements in the specified subrange from the collection.

func removeAll(keepingCapacity: Bool)

Removes all elements from the collection.

Required. Default implementation provided.

Beta

Concatenating Collections

func +<C, S>(C, S)

Creates a new collection by concatenating the elements of a collection and a sequence.

func +<C, S>(S, C)

Creates a new collection by concatenating the elements of a sequence and a collection.

func +<RRC1, RRC2>(RRC1, RRC2)

Creates a new collection by concatenating the elements of two collections.

func +=<R, S>(inout R, S)

Appends the elements of a sequence to a range-replaceable collection.

Associated Types

Initializers

init<S>(S)

Creates a new instance of a collection containing the elements of a sequence.

Required. Default implementation provided.

Beta
init(repeating: Self.Element, count: Int)

Creates a new collection containing the specified number of a single, repeated value.

Required. Default implementation provided.

Beta

Instance Methods

func append(Self.Element)

Adds an element to the end of the collection.

Required. Default implementation provided.

Beta
func append<S>(contentsOf: S)

Required. Default implementation provided.

Beta
func filter((Self.Element) -> Bool)

Returns a new collection of the same type containing, in order, the elements of the original collection that satisfy the given predicate.

Beta
func insert(Self.Element, at: Self.Index)

Inserts a new element into the collection at the specified position.

Required. Default implementation provided.

Beta
func remove(at: Self.Index)

Removes and returns the element at the specified position.

Required. Default implementation provided.

Beta
func removeFirst()

Removes and returns the first element of the collection.

Required. Default implementations provided.

Beta
func removeLast()

Removes and returns the last element of the collection.

Beta
func removeLast()

Removes and returns the last element of the collection.

Beta
func removeSubrange<R>(R)

Removes the elements in the specified subrange from the collection.

Beta

See Also

Collection Mutability

protocol MutableCollection

A collection that supports subscript assignment.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software