//===----------------------------------------------------------------------===// // // This source file is part of the Swift Collections open source project // // Copyright (c) 2026 Apple Inc. and the Swift project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information // // SPDX-License-Identifier: Apache-2.0 WITH Swift-exception // //===----------------------------------------------------------------------===// #if !COLLECTIONS_SINGLE_MODULE import InternalCollectionsUtilities import ContainersPreview #endif #if compiler(>=6.3) @available(SwiftStdlib 5.0, *) extension TemporaryArray where Element: ~Copyable { /// Adds an element to the end of the array, growing (and, if needed, spilling /// to the heap) to make room. /// /// - Complexity: O(1), amortized over many invocations on the same array. @_alwaysEmitIntoClient public mutating func append(_ item: consuming Element) { _ensureFreeCapacity(1) unsafe _storage.initializeElement(at: _count, to: item) _count &+= 1 } /// Appends a given number of items to the end of the array by populating an /// output span, growing (and, if needed, spilling to the heap) to make room. /// /// The closure may initialize fewer than `newItemCount` items; the array /// gains exactly as many as the closure adds before it returns or throws. /// /// - Complexity: O(`newItemCount`), amortized. @_alwaysEmitIntoClient public mutating func append( addingCount newItemCount: Int, initializingWith initializer: (inout OutputSpan) throws(E) -> Void ) throws(E) { precondition(newItemCount >= 0, "Cannot add a negative number of items") _ensureFreeCapacity(newItemCount) let buffer = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, newItemCount))) var span = unsafe OutputSpan(buffer: buffer, initializedCount: 0) defer { _count &+= span.finalize(for: buffer) span = OutputSpan() } return try initializer(&span) } } @available(SwiftStdlib 5.0, *) extension TemporaryArray where Element: ~Copyable { /// Moves the elements of a buffer to the end of this array, leaving the /// buffer uninitialized. /// /// - Complexity: O(`items.count`), amortized. @_alwaysEmitIntoClient public mutating func append( moving items: UnsafeMutableBufferPointer ) { guard items.count > 0 else { return } _ensureFreeCapacity(items.count) let target = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, items.count))) let i = unsafe target.moveInitialize(fromContentsOf: items) assert(i == items.count) _count &+= items.count } /// Moves the elements of an output span to the end of this array, leaving the /// span empty. /// /// - Complexity: O(`items.count`), amortized. @_alwaysEmitIntoClient public mutating func append( moving items: inout OutputSpan ) { items.withUnsafeMutableBufferPointer { buffer, count in let source = unsafe buffer.extracting(Range(uncheckedBounds: (0, count))) unsafe self.append(moving: source) count = 0 } } } @available(SwiftStdlib 5.0, *) extension TemporaryArray /*where Element: Copyable*/ { /// Appends `count` copies of `repeatedValue` to the end of the array, growing /// (and, if needed, spilling to the heap) to make room. /// /// This is `TemporaryArray`'s analogue of `UniqueArray`'s /// `init(repeating:count:)`: it's an append rather than an initializer, /// because a `TemporaryArray` is meant to be seeded (typically on the stack) /// via `withTemporaryArray` and then filled. /// /// - Complexity: O(`count`), amortized. @_alwaysEmitIntoClient public mutating func append(repeating repeatedValue: Element, count: Int) { precondition(count >= 0, "Cannot add a negative number of items") guard count > 0 else { return } _ensureFreeCapacity(count) let target = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, count))) unsafe target.initialize(repeating: repeatedValue) _count &+= count } /// Copies the elements of a buffer to the end of this array. /// /// - Complexity: O(`newElements.count`), amortized. @_alwaysEmitIntoClient public mutating func append( copying newElements: UnsafeBufferPointer ) { guard newElements.count > 0 else { return } _ensureFreeCapacity(newElements.count) let target = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, newElements.count))) _ = unsafe target.initialize(fromContentsOf: newElements) _count &+= newElements.count } /// Copies the elements of a buffer to the end of this array. /// /// - Complexity: O(`newElements.count`), amortized. @_alwaysEmitIntoClient public mutating func append( copying items: UnsafeMutableBufferPointer ) { unsafe self.append(copying: UnsafeBufferPointer(items)) } /// Copies the elements of a span to the end of this array. /// /// - Complexity: O(`newElements.count`), amortized. @_alwaysEmitIntoClient public mutating func append(copying newElements: Span) { guard newElements.count > 0 else { return } _ensureFreeCapacity(newElements.count) let target = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, newElements.count))) unsafe newElements.withUnsafeBufferPointer { source in _ = unsafe target.initialize(fromContentsOf: source) } _count &+= newElements.count } /// Copies the elements of a sequence to the end of this array. /// /// If the sequence provides only a loose `underestimatedCount`, the array's /// storage may need to be resized more than once (potentially spilling to the /// heap along the way). /// /// - Complexity: O(*m*), where *m* is the length of `newElements`, amortized. @_alwaysEmitIntoClient public mutating func append(copying newElements: some Sequence) { let done: Void? = newElements.withContiguousStorageIfAvailable { buffer in _ensureFreeCapacity(buffer.count) let target = unsafe _freeSpace.extracting( Range(uncheckedBounds: (0, buffer.count))) _ = unsafe target.initialize(fromContentsOf: buffer) _count &+= buffer.count return } if done != nil { return } _ensureFreeCapacity(newElements.underestimatedCount) for item in newElements { append(item) } } } #if compiler(>=6.4) && UnstableContainersPreview @available(SwiftStdlib 5.0, *) extension TemporaryArray where Element: ~Copyable { /// Appends all the items generated by a producer to the end of this array, /// growing (and, if needed, spilling to the heap) as it goes. /// /// This is the building block for collecting the result of mapping, filtering /// or otherwise transforming an arbitrary generative sequence whose final /// length isn't known in advance. The producer's `underestimatedCount` is /// used to size each bulk append. /// /// - Complexity: O(*n*) where *n* is the number of generated items, amortized. @_alwaysEmitIntoClient public mutating func append< E: Error, P: Producer & ~Copyable & ~Escapable >( from producer: inout P ) throws(E) where P.Element: ~Copyable { var done = false while !done { let c = Swift.max(producer.underestimatedCount, 1) _ensureFreeCapacity(c) try self.append(addingCount: freeCapacity) { target throws(E) in while !target.isFull, !done { done = try !producer.generate(into: &target) } } } } } #endif #endif