StructureSwift5.9.0

    Array

    An ordered, random-access collection.

    @frozen struct Array<Element>

    Arrays are one of the most commonly used data types in an app. You use arrays to organize your app’s data. Specifically, you use the Array type to hold elements of a single type, the array’s Element type. An array can store any kind of elements—from integers to strings to classes.

    Swift makes it easy to create arrays in your code using an array literal: simply surround a comma-separated list of values with square brackets. Without any other information, Swift creates an array that includes the specified values, automatically inferring the array’s Element type. For example:

    // An array of 'Int' elements
let oddNumbers = [1, 3, 5, 7, 9, 11, 13, 15]

// An array of 'String' elements
let streets = ["Albemarle", "Brandywine", "Chesapeake"]

    You can create an empty array by specifying the Element type of your array in the declaration. For example:

    // Shortened forms are preferred
var emptyDoubles: [Double] = []

// The full type name is also allowed
var emptyFloats: Array<Float> = Array()

    If you need an array that is preinitialized with a fixed number of default values, use the Array(repeating:count:) initializer.

    var digitCounts = Array(repeating: 0, count: 10)
print(digitCounts)
// Prints "[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]"

    Accessing Array Values

    When you need to perform an operation on all of an array’s elements, use a for-in loop to iterate through the array’s contents.

    for street in streets {
    print("I don't live on \(street).")
}
// Prints "I don't live on Albemarle."
// Prints "I don't live on Brandywine."
// Prints "I don't live on Chesapeake."

    Use the isEmpty property to check quickly whether an array has any elements, or use the count property to find the number of elements in the array.

    if oddNumbers.isEmpty {
    print("I don't know any odd numbers.")
} else {
    print("I know \(oddNumbers.count) odd numbers.")
}
// Prints "I know 8 odd numbers."

    Use the first and last properties for safe access to the value of the array’s first and last elements. If the array is empty, these properties are nil.

    if let firstElement = oddNumbers.first, let lastElement = oddNumbers.last {
    print(firstElement, lastElement, separator: ", ")
}
// Prints "1, 15"

print(emptyDoubles.first, emptyDoubles.last, separator: ", ")
// Prints "nil, nil"

    You can access individual array elements through a subscript. The first element of a nonempty array is always at index zero. You can subscript an array with any integer from zero up to, but not including, the count of the array. Using a negative number or an index equal to or greater than count triggers a runtime error. For example:

    print(oddNumbers[0], oddNumbers[3], separator: ", ")
// Prints "1, 7"

print(emptyDoubles[0])
// Triggers runtime error: Index out of range

    Adding and Removing Elements

    Suppose you need to store a list of the names of students that are signed up for a class you’re teaching. During the registration period, you need to add and remove names as students add and drop the class.

    var students = ["Ben", "Ivy", "Jordell"]

    To add single elements to the end of an array, use the append(_:) method. Add multiple elements at the same time by passing another array or a sequence of any kind to the append(contentsOf:) method.

    students.append("Maxime")
students.append(contentsOf: ["Shakia", "William"])
// ["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]

    You can add new elements in the middle of an array by using the insert(_:at:) method for single elements and by using insert(contentsOf:at:) to insert multiple elements from another collection or array literal. The elements at that index and later indices are shifted back to make room.

    students.insert("Liam", at: 3)
// ["Ben", "Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]

    To remove elements from an array, use the remove(at:), removeSubrange(_:), and removeLast() methods.

    // Ben's family is moving to another state
students.remove(at: 0)
// ["Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]

// William is signing up for a different class
students.removeLast()
// ["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]

    You can replace an existing element with a new value by assigning the new value to the subscript.

    if let i = students.firstIndex(of: "Maxime") {
    students[i] = "Max"
}
// ["Ivy", "Jordell", "Liam", "Max", "Shakia"]

    Growing the Size of an Array

    Every array reserves a specific amount of memory to hold its contents. When you add elements to an array and that array begins to exceed its reserved capacity, the array allocates a larger region of memory and copies its elements into the new storage. The new storage is a multiple of the old storage’s size. This exponential growth strategy means that appending an element happens in constant time, averaging the performance of many append operations. Append operations that trigger reallocation have a performance cost, but they occur less and less often as the array grows larger.

    If you know approximately how many elements you will need to store, use the reserveCapacity(_:) method before appending to the array to avoid intermediate reallocations. Use the capacity and count properties to determine how many more elements the array can store without allocating larger storage.

    For arrays of most Element types, this storage is a contiguous block of memory. For arrays with an Element type that is a class or @objc protocol type, this storage can be a contiguous block of memory or an instance of NSArray. Because any arbitrary subclass of NSArray can become an Array, there are no guarantees about representation or efficiency in this case.

    Modifying Copies of Arrays

    Each array has an independent value that includes the values of all of its elements. For simple types such as integers and other structures, this means that when you change a value in one array, the value of that element does not change in any copies of the array. For example:

    var numbers = [1, 2, 3, 4, 5]
var numbersCopy = numbers
numbers[0] = 100
print(numbers)
// Prints "[100, 2, 3, 4, 5]"
print(numbersCopy)
// Prints "[1, 2, 3, 4, 5]"

    If the elements in an array are instances of a class, the semantics are the same, though they might appear different at first. In this case, the values stored in the array are references to objects that live outside the array. If you change a reference to an object in one array, only that array has a reference to the new object. However, if two arrays contain references to the same object, you can observe changes to that object’s properties from both arrays. For example:

    // An integer type with reference semantics
class IntegerReference {
    var value = 10
}
var firstIntegers = [IntegerReference(), IntegerReference()]
var secondIntegers = firstIntegers

// Modifications to an instance are visible from either array
firstIntegers[0].value = 100
print(secondIntegers[0].value)
// Prints "100"

// Replacements, additions, and removals are still visible
// only in the modified array
firstIntegers[0] = IntegerReference()
print(firstIntegers[0].value)
// Prints "10"
print(secondIntegers[0].value)
// Prints "100"

    Arrays, like all variable-size collections in the standard library, use copy-on-write optimization. Multiple copies of an array share the same storage until you modify one of the copies. When that happens, the array being modified replaces its storage with a uniquely owned copy of itself, which is then modified in place. Optimizations are sometimes applied that can reduce the amount of copying.

    This means that if an array is sharing storage with other copies, the first mutating operation on that array incurs the cost of copying the array. An array that is the sole owner of its storage can perform mutating operations in place.

    In the example below, a numbers array is created along with two copies that share the same storage. When the original numbers array is modified, it makes a unique copy of its storage before making the modification. Further modifications to numbers are made in place, while the two copies continue to share the original storage.

    var numbers = [1, 2, 3, 4, 5]
var firstCopy = numbers
var secondCopy = numbers

// The storage for 'numbers' is copied here
numbers[0] = 100
numbers[1] = 200
numbers[2] = 300
// 'numbers' is [100, 200, 300, 4, 5]
// 'firstCopy' and 'secondCopy' are [1, 2, 3, 4, 5]

    Bridging Between Array and NSArray

    When you need to access APIs that require data in an NSArray instance instead of Array, use the type-cast operator (as) to bridge your instance. For bridging to be possible, the Element type of your array must be a class, an @objc protocol (a protocol imported from Objective-C or marked with the @objc attribute), or a type that bridges to a Foundation type.

    The following example shows how you can bridge an Array instance to NSArray to use the write(to:atomically:) method. In this example, the colors array can be bridged to NSArray because the colors array’s String elements bridge to NSString. The compiler prevents bridging the moreColors array, on the other hand, because its Element type is Optional<String>, which does not bridge to a Foundation type.

    let colors = ["periwinkle", "rose", "moss"]
let moreColors: [String?] = ["ochre", "pine"]

let url = URL(fileURLWithPath: "names.plist")
(colors as NSArray).write(to: url, atomically: true)
// true

(moreColors as NSArray).write(to: url, atomically: true)
// error: cannot convert value of type '[String?]' to type 'NSArray'

    Bridging from Array to NSArray takes O(1) time and O(1) space if the array’s elements are already instances of a class or an @objc protocol; otherwise, it takes O(n) time and space.

    When the destination array’s element type is a class or an @objc protocol, bridging from NSArray to Array first calls the copy(with:) (- copyWithZone: in Objective-C) method on the array to get an immutable copy and then performs additional Swift bookkeeping work that takes O(1) time. For instances of NSArray that are already immutable, copy(with:) usually returns the same array in O(1) time; otherwise, the copying performance is unspecified. If copy(with:) returns the same array, the instances of NSArray and Array share storage using the same copy-on-write optimization that is used when two instances of Array share storage.

    When the destination array’s element type is a nonclass type that bridges to a Foundation type, bridging from NSArray to Array performs a bridging copy of the elements to contiguous storage in O(n) time. For example, bridging from NSArray to Array<Int> performs such a copy. No further bridging is required when accessing elements of the Array instance.

    Citizens in Swift

    Conformances

    Members

    Features

    Citizens in Swift

    where Element:Equatable

    Conformances

    Members

    Features

    Citizens in Swift

    where Element:Decodable

    Conformances

    Members

    Citizens in Swift

    where Element:Encodable

    Conformances

    Members

    Citizens in Swift

    where Element:Hashable

    Conformances

    • protocol Hashable

      A type that can be hashed into a Hasher to produce an integer hash value.

    Members

    Citizens in Swift

    where Element:Sendable

    Conformances

    • protocol Sendable

      A type whose values can safely be passed across concurrency domains by copying.

    Available in _Differentiation

    where Element:Differentiable

    Conformances

    • protocol Differentiable

      A type that mathematically represents a differentiable manifold whose tangent spaces are finite-dimensional.

    Members

    Available in Foundation

    where Element:EncodableWithConfiguration

    Conformances

    Members

    Available in Foundation

    where Element:DecodableWithConfiguration

    Conformances

    Members

    Available in Foundation

    where Element == UInt8

    Conformances

    Members

    Features

    Extension in BSON

    where Element:Primitive

    Conformances

    Members

    Features

    Extension in BSON

    where Element:Encodable

    Conformances

    Members

    Extension in _MongoKittenCrypto

    where Element == UInt8

    Members

    Extension in Meow

    where Element:Resolvable

    Conformances

    Extension in Grammar

    where Element:ParsingRule

    Conformances

    Members

    Features

    Extension in JSON

    where Element == JSON

    Members

    Extension in NIOCore

    where Element == UInt8

    Members

    • init(buffer: ByteBuffer)

      Creates a [UInt8] from the given buffer. The entire readable portion of the buffer will be read.

    Extension in SwiftSyntaxBuilder

    where Element:ExpressibleByLiteralSyntax

    Conformances

    Members

    AdditiveArithmeticAnyBidirectionalCollectionAnyCollectionAnyHashableAnyIndexAnyIteratorAnyKeyPathAnyRandomAccessCollectionAnySequenceArrayArraySliceBidirectionalCollectionBinaryFloatingPointBinaryIntegerBoolCVaListPointerCVarArgCaseIterableCharacterClosedRange
    Index
    CodingKeyCodingKeyRepresentableCodingUserInfoKeyCollectionCollectionDifference
    ChangeIndex
    CollectionOfOne
    Iterator
    CommandLineComparableContiguousArrayCustomDebugStringConvertibleCustomLeafReflectableCustomPlaygroundDisplayConvertibleCustomReflectableCustomStringConvertibleDecodableDecoderDecodingError
    Context
    DefaultIndicesDefaultStringInterpolationDictionary
    IndexIteratorKeys
    Iterator
    Values
    Iterator
    Double
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    DropFirstSequenceDropWhileSequence
    Iterator
    DurationDurationProtocolEmptyCollection
    Iterator
    EncodableEncoderEncodingError
    Context
    EnumeratedSequence
    Iterator
    EquatableErrorExpressibleByArrayLiteralExpressibleByBooleanLiteralExpressibleByDictionaryLiteralExpressibleByExtendedGraphemeClusterLiteralExpressibleByFloatLiteralExpressibleByIntegerLiteralExpressibleByNilLiteralExpressibleByStringInterpolationExpressibleByStringLiteralExpressibleByUnicodeScalarLiteralFixedWidthIntegerFlattenSequence
    IndexIterator
    Float
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    Float16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    Float80FloatingPointFloatingPointClassificationFloatingPointRoundingRuleFloatingPointSignHashableHasherIdentifiableIndexingIteratorInstantProtocolInt
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int32
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int64
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int8
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    IteratorProtocolIteratorSequenceJoinedSequence
    Iterator
    KeyPathKeyValuePairsKeyedDecodingContainerKeyedDecodingContainerProtocolKeyedEncodingContainerKeyedEncodingContainerProtocolLazyCollectionProtocolLazyDropWhileSequence
    Iterator
    LazyFilterSequence
    Iterator
    LazyMapSequence
    Iterator
    LazyPrefixWhileSequence
    IndexIterator
    LazySequenceLazySequenceProtocolLosslessStringConvertibleManagedBufferManagedBufferPointerMemoryLayoutMirror
    AncestorRepresentationDisplayStyle
    MirrorPathMutableCollectionNeverNumericObjectIdentifierOpaquePointerOptionSetOptionalPartialKeyPathPartialRangeFrom
    Iterator
    PartialRangeThroughPartialRangeUpToPrefixSequence
    Iterator
    RandomAccessCollectionRandomNumberGeneratorRangeRangeExpressionRangeReplaceableCollectionRawRepresentableReferenceWritableKeyPathRepeatedResultReversedCollection
    IndexIterator
    SIMDSIMD16SIMD2SIMD3SIMD32SIMD4SIMD64SIMD8SIMDMaskSIMDScalarSIMDStorageSendableSequenceSet
    IndexIterator
    SetAlgebraSignedIntegerSignedNumericSingleValueDecodingContainerSingleValueEncodingContainerSliceStaticBigIntStaticStringStrideThroughStrideThroughIteratorStrideToStrideToIteratorStrideableString
    IndexIteratorUTF16View
    Iterator
    UTF8ViewUnicodeScalarView
    Iterator
    StringInterpolationProtocolStringProtocolSubstring
    UTF16ViewUTF8ViewUnicodeScalarView
    SystemRandomNumberGeneratorTextOutputStreamTextOutputStreamableUInt
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt32
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt64
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt8
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UnboundedRange_UnfoldSequenceUnicode
    ASCII
    Parser
    CanonicalCombiningClassGeneralCategoryNumericTypeParseResultScalar
    PropertiesUTF16ViewUTF8View
    UTF16
    ForwardParserReverseParser
    UTF32
    Parser
    UTF8
    ForwardParserReverseParser
    UnicodeCodecUnicodeDecodingResultUnkeyedDecodingContainerUnkeyedEncodingContainerUnmanagedUnsafeBufferPointer
    Iterator
    UnsafeMutableBufferPointerUnsafeMutablePointerUnsafeMutableRawBufferPointerUnsafeMutableRawPointerUnsafePointerUnsafeRawBufferPointer
    Iterator
    UnsafeRawPointerUnsafeSendableUnsignedIntegerWritableKeyPathZip2Sequence
    Iterator
    _AppendKeyPath