<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Swift",
  "identifier" : "/documentation/Swift/UniqueArray",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Swift"
    ],
    "preciseIdentifier" : "s:s11UniqueArrayV"
  },
  "title" : "UniqueArray"
}
-->

# UniqueArray

A dynamically self-resizing, heap allocated, noncopyable array of
potentially noncopyable elements.

```
@frozen struct UniqueArray<Element> where Element : ~Copyable
```

## Overview

`UniqueArray` instances automatically resize their underlying storage as
needed to accommodate newly inserted items, using a geometric growth curve.
This lets code using `UniqueArray` avoid having to allocate enough
capacity in advance; on the other hand, it makes it difficult to tell
when and where such reallocations may happen.

For example, appending an element to a `UniqueArray` has highly variable
complexity; often, it runs at a constant cost, but if the operation has to
resize storage, then the cost of an individual append suddenly becomes
proportional to the size of the whole array.

The geometric growth curve allows the cost of such latency spikes to
get amortized across repeated invocations, bringing the average cost back
to O(1); but the spikes make this construct less suitable for use cases that
expect predictable, consistent performance on every operation.

Implicit growth also makes it more difficult to predict/analyze the amount
of memory an algorithm would need. Developers targeting environments with
stringent limits on heap allocations may prefer to avoid using dynamically
resizing container types as a matter of policy. The type `RigidArray` provides
a fixed-capacity array variant that caters specifically for these use cases,
trading ease-of-use for more consistent/predictable execution.
For copyable elements, the copy-on-write `Array` type is an
even more convenient and expressive choice.

## Topics

### Initializers

[`init()`](/documentation/Swift/UniqueArray/init())

Initializes a new unique array with no elements.

[`init(capacity: Int)`](/documentation/Swift/UniqueArray/init(capacity:))

Initializes a new unique array with the specified capacity and no elements.

[`init(capacity: Int?, copying: some Sequence<Element>)`](/documentation/Swift/UniqueArray/init(capacity:copying:)-5tkhn)

Creates a new array with the specified initial capacity, holding a copy
of the contents of a given sequence.

[`init(capacity: Int?, copying: Span<Element>)`](/documentation/Swift/UniqueArray/init(capacity:copying:)-991h4)

Creates a new array with the specified capacity, holding a copy
of the contents of the given span.

[`init<E>(capacity: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)`](/documentation/Swift/UniqueArray/init(capacity:initializingWith:))

Creates a new array with the specified capacity, directly initializing
its storage using an output span.

[`init(minimumCapacity: Int)`](/documentation/Swift/UniqueArray/init(minimumCapacity:))

Initializes a new unique array with the specified capacity and no elements.

[`init(repeating: Element, count: Int)`](/documentation/Swift/UniqueArray/init(repeating:count:))

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

### Instance Properties

[`var capacity: Int`](/documentation/Swift/UniqueArray/capacity)

The maximum number of elements this array can hold without having to
reallocate its storage.

[`var count: Int`](/documentation/Swift/UniqueArray/count)

The number of elements in this array.

[`var debugDescription: String`](/documentation/Swift/UniqueArray/debugDescription)

[`var description: String`](/documentation/Swift/UniqueArray/description)

[`var endIndex: Int`](/documentation/Swift/UniqueArray/endIndex)

The array’s “past the end” position—that is, the position one greater than
the last valid subscript argument. This is always equal to array’s count.

[`var freeCapacity: Int`](/documentation/Swift/UniqueArray/freeCapacity)

The number of additional elements that can be added to this array without
reallocating its storage.

[`var indices: Range<Int>`](/documentation/Swift/UniqueArray/indices)

The range of indices that are valid for subscripting the array.

[`var isEmpty: Bool`](/documentation/Swift/UniqueArray/isEmpty)

A Boolean value indicating whether this array contains no elements.

[`var mutableSpan: MutableSpan<Element>`](/documentation/Swift/UniqueArray/mutableSpan)

A mutable span over the elements of this array, providing direct
mutating access.

[`var span: Span<Element>`](/documentation/Swift/UniqueArray/span)

A span over the elements of this array, providing direct read-only access.

[`var startIndex: Int`](/documentation/Swift/UniqueArray/startIndex)

The position of the first element in a nonempty array. This is always zero.

### Instance Methods

[`func append(consuming Element)`](/documentation/Swift/UniqueArray/append(_:))

Adds an element to the end of the array.

[`func append<E>(addingCount: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)`](/documentation/Swift/UniqueArray/append(addingCount:initializingWith:))

Append a given number of items to the end of this array by populating
an output span.

[`func append(copying: UnsafeBufferPointer<Element>)`](/documentation/Swift/UniqueArray/append(copying:)-1qhpn)

Copies the elements of a buffer to the end of this array.

[`func append(copying: Span<Element>)`](/documentation/Swift/UniqueArray/append(copying:)-3aouw)

Copies the elements of a span to the end of this array.

[`func append(copying: some Sequence<Element>)`](/documentation/Swift/UniqueArray/append(copying:)-7ntgb)

Copies the elements of a sequence to the end of this array.

[`func append(copying: UnsafeMutableBufferPointer<Element>)`](/documentation/Swift/UniqueArray/append(copying:)-90c4t)

Copies the elements of a buffer to the end of this array.

[`func append(moving: UnsafeMutableBufferPointer<Element>)`](/documentation/Swift/UniqueArray/append(moving:)-71oaj)

Moves the elements of a buffer to the end of this array, leaving the
buffer uninitialized.

[`func append(moving: inout OutputSpan<Element>)`](/documentation/Swift/UniqueArray/append(moving:)-9p4vs)

Moves the elements of a output span to the end of this array, leaving the
span empty.

[`func clone() -> UniqueArray<Element>`](/documentation/Swift/UniqueArray/clone())

Copy the contents of this array into a newly allocated unique array
instance with just enough capacity to hold all its elements.

[`func clone(capacity: Int) -> UniqueArray<Element>`](/documentation/Swift/UniqueArray/clone(capacity:))

Copy the contents of this array into a newly allocated unique array
instance with the specified capacity.

[`func distance(from: UniqueArray<Element>.Index, to: UniqueArray<Element>.Index) -> Int`](/documentation/Swift/UniqueArray/distance(from:to:))

Returns the distance between two indices.

[`func edit<E, R>((inout OutputSpan<Element>) throws(E) -> R) throws(E) -> R`](/documentation/Swift/UniqueArray/edit(_:))

Arbitrarily edit the storage underlying this array by invoking a
user-supplied closure with a mutable `OutputSpan` view over it.
This method calls its function argument at most once, allowing it to
arbitrarily modify the contents of the output span it is given.
The argument is free to add, remove or reorder any items; however,
it is not allowed to replace the span or change its capacity.

[`func formIndex(inout UniqueArray<Element>.Index, offsetBy: inout Int, limitedBy: UniqueArray<Element>.Index)`](/documentation/Swift/UniqueArray/formIndex(_:offsetBy:limitedBy:))

Offsets the given index by the specified distance, but no further than
the given limiting index.

[`func formIndex(after: inout Int)`](/documentation/Swift/UniqueArray/formIndex(after:))

Replaces the given index with its successor.

[`func formIndex(before: inout Int)`](/documentation/Swift/UniqueArray/formIndex(before:))

Replaces the given index with its predecessor.

[`func index(Int, offsetBy: Int) -> Int`](/documentation/Swift/UniqueArray/index(_:offsetBy:))

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

[`func index(after: Int) -> Int`](/documentation/Swift/UniqueArray/index(after:))

Returns the position immediately after the given index.

[`func index(before: Int) -> Int`](/documentation/Swift/UniqueArray/index(before:))

Returns the position immediately before the given index.

[`func insert(consuming Element, at: Int)`](/documentation/Swift/UniqueArray/insert(_:at:))

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

[`func insert<E>(addingCount: Int, at: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)`](/documentation/Swift/UniqueArray/insert(addingCount:at:initializingWith:))

Inserts a given number of new items into this array at the specified
position, using a callback to directly initialize array storage by
populating an output span.

[`func insert(copying: Span<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(copying:at:)-2g824)

Copies the elements of a span into this array at the specified position.

[`func insert(copying: some Collection<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(copying:at:)-4823q)

Copies the elements of a collection into this array at the specified
position.

[`func insert(copying: UnsafeMutableBufferPointer<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(copying:at:)-6kuy5)

Copies the elements of a fully initialized buffer pointer into this
array at the specified position.

[`func insert(copying: UnsafeBufferPointer<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(copying:at:)-9wt40)

Copies the elements of a fully initialized buffer pointer into this
array at the specified position.

[`func insert(moving: UnsafeMutableBufferPointer<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(moving:at:)-4f2qc)

Moves the elements of a fully initialized buffer into this array,
starting at the specified position, and leaving the buffer
uninitialized.

[`func insert(moving: inout OutputSpan<Element>, at: Int)`](/documentation/Swift/UniqueArray/insert(moving:at:)-6d5t1)

Moves the elements of an output span into this array,
starting at the specified position, and leaving the span empty.

[`func isTriviallyIdentical(to: borrowing UniqueArray<Element>) -> Bool`](/documentation/Swift/UniqueArray/isTriviallyIdentical(to:))

[`func popLast() -> Element?`](/documentation/Swift/UniqueArray/popLast())

Removes and returns the last element of the array, if there is one.

[`func remove(at: Int) -> Element`](/documentation/Swift/UniqueArray/remove(at:))

Removes and returns the element at the specified position.

[`func removeAll()`](/documentation/Swift/UniqueArray/removeAll())

Removes all elements from the array, preserving its allocated capacity.

[`func removeLast() -> Element`](/documentation/Swift/UniqueArray/removeLast())

Removes and returns the last element of the array.

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

Removes and discards the specified number of elements from the end of the
array.

[`func removeSubrange(some RangeExpression<Int>)`](/documentation/Swift/UniqueArray/removeSubrange(_:)-6hkdt)

Removes the specified subrange of elements from the array.

[`func removeSubrange(Range<Int>)`](/documentation/Swift/UniqueArray/removeSubrange(_:)-6t21j)

Removes the specified subrange of elements from the array.

[`func replaceSubrange<E>(Range<Int>, addingCount: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)`](/documentation/Swift/UniqueArray/replaceSubrange(_:addingCount:initializingWith:))

Replaces the specified range of elements by a given count of new items,
using a callback to directly initialize array storage by populating
an output span.

[`func replaceSubrange(Range<Int>, copying: UnsafeBufferPointer<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:copying:)-5cbxf)

Replaces the specified subrange of elements by copying the elements of
the given buffer pointer, which must be fully initialized.

[`func replaceSubrange(Range<Int>, copying: Span<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:copying:)-70i0j)

Replaces the specified subrange of elements by copying the elements of
the given span.

[`func replaceSubrange(Range<Int>, copying: consuming some Collection<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:copying:)-7599g)

Replaces the specified subrange of elements by copying the elements of
the given collection.

[`func replaceSubrange(Range<Int>, copying: UnsafeMutableBufferPointer<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:copying:)-8tpt1)

Replaces the specified subrange of elements by copying the elements of
the given buffer pointer, which must be fully initialized.

[`func replaceSubrange(Range<Int>, moving: UnsafeMutableBufferPointer<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:moving:)-4de3f)

Replaces the specified range of elements by moving the elements of a
fully initialized buffer into their place. On return, the buffer is left
in an uninitialized state.

[`func replaceSubrange(Range<Int>, moving: inout OutputSpan<Element>)`](/documentation/Swift/UniqueArray/replaceSubrange(_:moving:)-6vpdp)

Replaces the specified range of elements by moving the contents of an
output span into their place. On return, the span is left empty.

[`func reserveCapacity(Int)`](/documentation/Swift/UniqueArray/reserveCapacity(_:))

Ensure that the array has capacity to store the specified number of
elements, by growing its storage buffer if necessary.

[`func setCapacity(Int)`](/documentation/Swift/UniqueArray/setCapacity(_:))

Grow or shrink the capacity of a unique array instance without discarding
its contents.

[`func swapAt(Int, Int)`](/documentation/Swift/UniqueArray/swapAt(_:_:))

Exchanges the values at the specified indices of the array.

### Subscripts

[`subscript(Int) -> Element`](/documentation/Swift/UniqueArray/subscript(_:))

Accesses the element at the specified position.

### Type Aliases

[`typealias Index`](/documentation/Swift/UniqueArray/Index)

A type that represents a position in the array: an integer offset from the
start.

### Default Implementations

[Equatable Implementations](/documentation/Swift/UniqueArray/Equatable-Implementations)

[Hashable Implementations](/documentation/Swift/UniqueArray/Hashable-Implementations)

[Iterable Implementations](/documentation/Swift/UniqueArray/Iterable-Implementations)

## Relationships

### Conforms To

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

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

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

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

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

---

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)