diff --git a/Proposals/nnnn-generalize-closure-based-functions-in-Data.md b/Proposals/nnnn-generalize-closure-based-functions-in-Data.md new file mode 100644 index 000000000..eb5b89a01 --- /dev/null +++ b/Proposals/nnnn-generalize-closure-based-functions-in-Data.md @@ -0,0 +1,75 @@ +# Generalize closure-based functions of `Data` + +* Proposal: [SF-NNNN](nnnn-generalize-closure-based-functions-in-Data.md) +* Authors: [Guillaume Lessard](https://github.com/glessard) +* Review Manager: TBD +* Status: **Awaiting implementation** or **Awaiting review** +* Bug: *if applicable* [swiftlang/swift-foundation#1638](https://github.com/swiftlang/swift-foundation/issues/1638) + +* Implementation: [swiftlang/swift-foundation#1622](https://github.com/swiftlang/swift-foundation/pull/1622) + +* Review: ([pitch](https://forums.swift.org/...)) + +## Introduction + +We propose to generalize the closure-taking API of `Data` for typed throws and for noncopyable return values, making them able to accept a greater variety of closures. + +## Motivation + +Since [SE-0427](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0427-noncopyable-generics.md), noncopyable types can participate in Swift generics, but `Data` has not been adapted to allow working with noncopyable values. [SE-0437](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0437-noncopyable-stdlib-primitives.md) paved the way by generalizing low-level constructs such as `UnsafeBufferPointer`, and as a result the community of Swift systems programmers now expects that generic functions such as `withUnsafeBytes()` can return noncopyable values. + +In [SE-0413](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0413-typed-throws.md), we also added the ability for functions to throw typed errors. This ability is important in high-performance contexts such as embedded Swift, and functions such as `withUnsafeBytes()` should support closures with typed errors. + +`Data`'s current closure-based functions such as `withUnsafeBytes()` cannot take advantage of either of these newer features: + +```swift +extension Data { + public func withUnsafeBytes( + _ apply: (UnsafeRawBufferPointer) throws -> ResultType + ) rethrows -> ResultType +} +``` + + + +## Proposed solution + +We will add support for typed throws and noncopyable return values to the functions of `Data` that take closure arguments with generic types. + +## Detailed design + +The signatures of `Data`'s three closure-based functions will become: + +```swift +extension Data { + @_alwaysEmitIntoClient + public func withUnsafeBytes( + _ apply: (UnsafeRawBufferPointer) throws(E) -> ResultType + ) throws(E) -> ResultType + + @_alwaysEmitIntoClient + public func withContiguousStorageIfAvailable( + _ body: (_ buffer: UnsafeBufferPointer) throws(E) -> ResultType + ) throws(E) -> ResultType? + + @_alwaysEmitIntoClient + public mutating func withUnsafeMutableBytes( + _ body: (UnsafeMutableRawBufferPointer) throws(E) -> ResultType + ) throws(E) -> ResultType +} +``` + +These are new functions that replace existing functions in a source-compatible way. The older signature required `ResultType` type to be `Copyable`, allowing it to also satisfy the `~Copyable` constraint. The untyped errors thrown by existing closures are a special case of the typed error case, where `E == any Error`. + +## Source compatibility + +This change is source-compatible with existing call sites. + +## Implications on adoption + +On ABI-stable platforms, the existing ABI will be preserved. The new entry points will be declared `@_alwaysEmitIntoClient` in order to help the compiler specialize use sites in practice. + +## Alternatives considered + +(none) +