Data API proposed in SE-0485 (OutputSpan) (swiftlang#1758)

glessard · jmschonfeld · web-flow · commit 27a37d666a33 · 2026-02-24T17:50:03.000-08:00
* Add the OutputSpan-taking initializers

* improve the output-span taking initializer for inline

* append-with-outputrawspan, for InlineData

* append with typed OutputSpan

* complete the OutputRawSpan-based initializer

Co-authored-by: Jeremy Schonfeld &lt;jschonfeld@apple.com&gt;

* the OutputRawSpan-based appender

* remove stray availability annotations

* Apply suggestions from code review

* fix some indentation

* Apply suggestions from code review

* implement initializer in `_Representation` instead

* add inout param to `withUninitializedBytes`

(and simplify internal names)

* slightly refactor `InlineData.append(_:_:)`

* add doc-comments

* update copyright headers

* tests for `Data(rawCapacity:initializingWith:)`

* tests for `Data(addingRawCapacity:initializingWith:)`

* remove redundant uniqueness checks

`reserveCapacity()` happens to do the uniqueness check.

* fix a mistake

* use a less confusing variable name

* Apply suggestions from code review

Co-authored-by: Jeremy Schonfeld &lt;jeremyschonfeld@gmail.com&gt;

* fix large slice capacity reservation

* make a design decision clearer.

* tweak test to avoid appending 0

* improve new tests

* fix appending to sliced data instances

* add availability annotations

* add one more availability annotation

* remove a stray print statement

---------

Co-authored-by: Jeremy Schonfeld &lt;jschonfeld@apple.com&gt;
Co-authored-by: Jeremy Schonfeld &lt;jeremyschonfeld@gmail.com&gt;
diff --git a/Sources/FoundationEssentials/Data/Data.swift b/Sources/FoundationEssentials/Data/Data.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Copyright (c) 2014 - 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
@@ -239,6 +239,68 @@ public struct Data : RandomAccessCollection, MutableCollection, RangeReplaceable
         _representation = .empty
     }
 
+    /// Creates a data instance with the specified capacity, and then calls the given
+    /// closure with an output span covering the instance's uninitialized memory.
+    ///
+    /// Inside the closure, initialize elements by appending to the `OutputRawSpan`.
+    /// The `OutputRawSpan` keeps track of the initialized memory, ensuring
+    /// safety. Its `count` at the end of the closure will become the `count` of
+    /// the newly-initialized instance of `Data`.
+    ///
+    /// - Note: While the resulting `Data` may have a capacity larger than the
+    ///   requested amount, the `OutputRawSpan` passed to the closure will cover
+    ///   exactly the number of bytes requested.
+    ///
+    /// - Parameters:
+    ///   - capacity: The number of bytes to allocate space for in the new `Data`.
+    ///   - initializer: A closure to initialize the allocated memory.
+    ///     - Parameters:
+    ///       - span: An `OutputRawSpan` covering uninitialized memory with
+    ///         space for the specified number of bytes.
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+    @_alwaysEmitIntoClient
+    public init<E: Error>(
+        rawCapacity capacity: Int,
+        initializingWith initializer: (_ span: inout OutputRawSpan) throws(E) -> Void
+    ) throws(E) {
+        precondition(capacity >= 0, "capacity must not be negative")
+        _representation = try _Representation(capacity: capacity, initializer)
+    }
+
+    /// Creates a data instance with the specified capacity, and then calls the given
+    /// closure with an output span covering the instance's uninitialized memory.
+    ///
+    /// Inside the closure, initialize elements by appending to the `OutputSpan`.
+    /// The `OutputSpan` keeps track of the initialized memory, ensuring
+    /// safety. Its `count` at the end of the closure will become the `count` of
+    /// the newly-initialized instance of `Data`.
+    ///
+    /// - Note: While the resulting `Data` may have a capacity larger than the
+    ///   requested amount, the `OutputSpan` passed to the closure will cover
+    ///   exactly the number of bytes requested.
+    ///
+    /// - Parameters:
+    ///   - capacity: The number of bytes to allocate space for in the new `Data`.
+    ///   - initializer: A closure to initialize the allocated memory.
+    ///     - Parameters:
+    ///       - span: An `OutputSpan` covering uninitialized memory with
+    ///         space for the specified number of elements.
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+    @_alwaysEmitIntoClient
+    public init<E: Error>(
+        capacity: Int,
+        initializingWith initializer: (_ span: inout OutputSpan<UInt8>) throws(E) -> Void
+    ) throws(E) {
+        self = try Data(rawCapacity: capacity) { output throws(E) in
+            try output.withUnsafeMutableBytes { (bytes, count) throws(E) in
+                try bytes.withMemoryRebound(to: UInt8.self) { buffer throws(E) in
+                    var span = OutputSpan<UInt8>(buffer: buffer, initializedCount: 0)
+                    try initializer(&span)
+                    count = span.finalize(for: buffer)
+                }
+            }
+        }
+    }
 
     /// Initialize a `Data` without copying the bytes.
     ///
@@ -536,6 +598,74 @@ public struct Data : RandomAccessCollection, MutableCollection, RangeReplaceable
         }
     }
 
+    /// Grows this data to have enough capacity for the specified number of
+    /// bytes, then calls the closure with an output span covering the requested
+    /// amount of uninitialized memory.
+    ///
+    /// Inside the closure, initialize elements by appending to `span`. It
+    /// ensures safety by keeping track of the initialized memory.
+    /// At the end of the closure, `span`'s `count` elements will have
+    /// been appended to this `Data` instance.
+    ///
+    /// If the closure throws an error, the items appended until that point
+    /// will remain in the `Data` instance.
+    ///
+    /// - Parameters:
+    ///   - uninitializedCount: The number of new elements the `Data` should have
+    ///     space for.
+    ///   - initializer: A closure to initialize memory.
+    ///     - Parameters:
+    ///       - span: An `OutputRawSpan` covering uninitialized memory with
+    ///         space for the specified number of additional bytes.
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+    @_alwaysEmitIntoClient
+    public mutating func append<E: Error>(
+        addingRawCapacity uninitializedCount: Int,
+        initializingWith initializer: (_ span: inout OutputRawSpan) throws(E) -> Void
+    ) throws(E) {
+        precondition(uninitializedCount >= 0, "uninitializedCount must not be negative")
+        try _representation.append(addingCapacity: uninitializedCount, initializer)
+    }
+
+    /// Grows this data to have enough capacity for the specified number of
+    /// bytes, then calls the closure with an output span covering the requested
+    /// amount of uninitialized memory.
+    ///
+    /// Inside the closure, initialize elements by appending to `span`. It
+    /// ensures safety by keeping track of the initialized memory.
+    /// At the end of the closure, `span`'s `count` elements will have
+    /// been appended to this `Data` instance.
+    ///
+    /// If the closure throws an error, the items appended until that point
+    /// will remain in the `Data` instance.
+    ///
+    /// - Parameters:
+    ///   - uninitializedCount: The number of new elements the array should have
+    ///     space for.
+    ///   - initializer: A closure to initialize memory.
+    ///     - Parameters:
+    ///       - span: An `OutputSpan` covering uninitialized memory with
+    ///         space for the specified number of additional elements.
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+    @_alwaysEmitIntoClient
+    public mutating func append<E: Error>(
+        addingCapacity uninitializedCount: Int,
+        initializingWith initializer: (_ span: inout OutputSpan<UInt8>) throws(E) -> Void
+    ) throws(E) {
+        try self.append(addingRawCapacity: uninitializedCount) { output throws(E) in
+            try output.withUnsafeMutableBytes { (bytes, count) throws(E) in
+                try bytes.withMemoryRebound(to: UInt8.self) { buffer throws(E) in
+                    var span = OutputSpan<UInt8>(buffer: buffer, initializedCount: 0)
+                    defer {
+                        count = span.finalize(for: buffer)
+                        span = OutputSpan()
+                    }
+                    try initializer(&span)
+                }
+            }
+        }
+    }
+
     /// Append a buffer of bytes to the data.
     ///
     /// - parameter buffer: The buffer of bytes to append. The size is calculated from `SourceType` and `buffer.count`.
diff --git a/Sources/FoundationEssentials/Data/Representations/Data+Inline.swift b/Sources/FoundationEssentials/Data/Representations/Data+Inline.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Copyright (c) 2025 - 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
@@ -76,6 +76,29 @@ extension Data {
             length = UInt8(count)
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient @inline(__always)
+        init<E: Error>(
+            rawCapacity: Int,
+            initializingWith initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            self.init()
+            do throws(E) {
+                let count = try Swift.withUnsafeMutableBytes(of: &bytes) {
+                    buffer throws(E) in
+                    let prefix = buffer.prefix(rawCapacity)
+                    var output = OutputRawSpan(buffer: prefix, initializedCount: 0)
+                    try initializer(&output)
+                    return output.finalize(for: prefix)
+                }
+                assert(count <= rawCapacity)
+                length = UInt8(count)
+            } catch {
+                self = .init()
+                throw error
+            }
+        }
+
         @inlinable @inline(__always) // This is @inlinable as a convenience initializer.
         init(_ slice: InlineSlice, count: Int) {
             self.init(count: count)
@@ -162,6 +185,28 @@ extension Data {
             length += UInt8(buffer.count)
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient
+        mutating func append<E: Error>(
+            _ extraCapacity: Int, _ initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            let oldCount = self.count
+            let newCapacity = oldCount + extraCapacity
+            assert(newCapacity <= capacity)
+            try Swift.withUnsafeMutableBytes(of: &bytes) {
+                buffer throws(E) in
+                let slice = buffer[oldCount..<newCapacity]
+                var span = OutputRawSpan(buffer: slice, initializedCount: 0)
+                defer {
+                    let addedCount = unsafe span.finalize(for: slice)
+                    length = UInt8(truncatingIfNeeded: oldCount + addedCount)
+                    assert(addedCount <= extraCapacity)
+                    span = OutputRawSpan()
+                }
+                try initializer(&span)
+            }
+        }
+
         @inlinable // This is @inlinable as trivially computable.
         subscript(index: Index) -> UInt8 {
             get {
diff --git a/Sources/FoundationEssentials/Data/Representations/Data+InlineSlice.swift b/Sources/FoundationEssentials/Data/Representations/Data+InlineSlice.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Copyright (c) 2025 - 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
@@ -181,6 +181,20 @@ extension Data {
             slice = slice.lowerBound..<HalfInt(Int(slice.upperBound) + buffer.count)
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient
+        mutating func append<E: Error>(
+            _ extraCapacity: Int, _ initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            assert(count + extraCapacity < HalfInt.max)
+            reserveCapacity(count + extraCapacity)
+            var appendedCount = 0
+            defer {
+                slice = slice.lowerBound..<(slice.upperBound + HalfInt(appendedCount))
+            }
+            try storage.withUninitializedBytes(extraCapacity: extraCapacity, location: endIndex, &appendedCount, initializer)
+        }
+
         @inlinable // This is @inlinable as reasonably small.
         subscript(index: Index) -> UInt8 {
             get {
diff --git a/Sources/FoundationEssentials/Data/Representations/Data+LargeSlice.swift b/Sources/FoundationEssentials/Data/Representations/Data+LargeSlice.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Copyright (c) 2025 - 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
@@ -169,6 +169,19 @@ extension Data {
             slice.range = slice.range.lowerBound..<slice.range.upperBound + buffer.count
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient
+        mutating func append<E: Error>(
+            _ extraCapacity: Int, _ initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            reserveCapacity(count + extraCapacity)
+            var appendedCount = 0
+            defer {
+                slice.range = slice.range.lowerBound..<(slice.range.upperBound + appendedCount)
+            }
+            try storage.withUninitializedBytes(extraCapacity: extraCapacity, location: endIndex, &appendedCount, initializer)
+        }
+
         @inlinable // This is @inlinable as trivially computable.
         subscript(index: Index) -> UInt8 {
             get {
diff --git a/Sources/FoundationEssentials/Data/Representations/Data+Representation.swift b/Sources/FoundationEssentials/Data/Representations/Data+Representation.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Copyright (c) 2025 - 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
@@ -93,6 +93,26 @@ extension Data {
             }
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient
+        init<E: Error>(
+            capacity: Int, _ initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            if InlineData.canStore(count: capacity) {
+                let inline = try InlineData(rawCapacity: capacity, initializingWith: initializer)
+                self = (inline.count == 0) ? .empty : .inline(inline)
+            } else {
+                let storage = __DataStorage(capacity: capacity)
+                var appendedCount = 0
+                try storage.withUninitializedBytes(extraCapacity: capacity, location: 0, &appendedCount, initializer)
+                if InlineSlice.canStore(count: appendedCount) {
+                    self = .slice(InlineSlice(storage, count: appendedCount))
+                } else {
+                    self = .large(LargeSlice(storage, count: appendedCount))
+                }
+            }
+        }
+
         @usableFromInline // This is not @inlinable as it is a non-trivial, non-generic function.
         mutating func reserveCapacity(_ minimumCapacity: Int) {
             guard minimumCapacity > 0 else { return }
@@ -302,6 +322,60 @@ extension Data {
             }
         }
         
+        @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
+        @_alwaysEmitIntoClient
+        mutating func append<E: Error>(
+            addingCapacity uninitializedCount: Int,
+            _ initializer: (inout OutputRawSpan) throws(E) -> Void
+        ) throws(E) {
+            let newCapacity = count + uninitializedCount
+
+            func appendInline(_ inline: consuming InlineData) throws(E) {
+                if InlineData.canStore(count: newCapacity) {
+                    defer {
+                        self = (inline.count == 0) ? .empty : .inline(inline)
+                    }
+                    try inline.append(uninitializedCount, initializer)
+                } else {
+                    let storage = __DataStorage(capacity: newCapacity)
+                    inline.withUnsafeBytes { storage.append($0.baseAddress!, length: $0.count) }
+                    var appendedCount = 0
+                    defer {
+                        assert(inline.count+appendedCount == storage.length)
+                        let newCount = storage.length
+                        if InlineSlice.canStore(count: newCount) {
+                            self = .slice(InlineSlice(storage, count: newCount))
+                        } else {
+                            self = .large(LargeSlice(storage, count: newCount))
+                        }
+                    }
+                    try storage.withUninitializedBytes(extraCapacity: uninitializedCount, location: inline.count, &appendedCount, initializer)
+                }
+            }
+
+            switch self {
+            case .empty:
+                try appendInline(InlineData())
+            case .inline(let inline):
+                try appendInline(inline)
+            case .slice(var slice):
+                if InlineSlice.canStore(count: newCapacity) {
+                    self = .empty
+                    defer { self = .slice(slice) }
+                    try slice.append(uninitializedCount, initializer)
+                } else {
+                    self = .empty
+                    var newSlice = LargeSlice(slice)
+                    defer { self = .large(newSlice) }
+                    try newSlice.append(uninitializedCount, initializer)
+                }
+            case .large(var slice):
+                self = .empty
+                defer { self = .large(slice) }
+                try slice.append(uninitializedCount, initializer)
+            }
+        }
+
         @inlinable // This is @inlinable as reasonably small.
         mutating func resetBytes(in range: Range<Index>) {
             switch self {
diff --git a/Sources/FoundationEssentials/Data/Representations/DataStorage.swift b/Sources/FoundationEssentials/Data/Representations/DataStorage.swift
diff --git a/Tests/FoundationEssentialsTests/DataTests.swift b/Tests/FoundationEssentialsTests/DataTests.swift
