[many more edits]

glessard · glessard · commit 41fcd63d67de · 2025-02-08T10:20:23.000-08:00
diff --git a/proposals/nnnn-MutableSpan.md b/proposals/nnnn-MutableSpan.md
@@ -12,6 +12,7 @@
 [SE-0447]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0447-span-access-shared-contiguous-storage.md
 [SE-0456]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0456-stdlib-span-properties.md
 [PR-2305]: https://github.com/swiftlang/swift-evolution/pull/2305
+[SE-0437]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0437-noncopyable-stdlib-primitives.md
 [SE-0453]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0453-vector.md
 [SE-0223]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0223-array-uninitialized-initializer.md
 [SE-0176]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0176-enforce-exclusive-access-to-memory.md
@@ -29,7 +30,7 @@ These functions have a few different drawbacks, most prominently their reliance
 In addition to the new types, we will propose adding new API some standard library types to take advantage of `MutableSpan` and `MutableRawSpan`.
 
 ## Proposed solution
-We previously introduced `Span` to provide shared read-only access to containers. We cannot use `Span` to also model container mutations, due to the [law of exclusivity][SE-0176]. `Span` is copyable, and must be copyable in order to properly model read access under the law of exclusivity: a value can be simultaneously accessed through multiple read-only accesses. Mutations, on the other hand, require _exclusive access_. Exclusive access cannot be modeled through a copyable type, since a copy of the value representing the access would by definition violate exclusivity. We therefore need a non-copyable type separate from `Span` in order to model mutations.
+We introduced `Span` to provide shared read-only access to containers. We cannot use `Span` to also model container mutations, due to the [law of exclusivity][SE-0176]. `Span` is copyable, and must be copyable in order to properly model read access under the law of exclusivity: a value can be simultaneously accessed through multiple read-only accesses. Mutations, on the other hand, require _exclusive access_. Exclusive access cannot be modeled with a copyable type, since a copy of the value representing the access would violate exclusivity by adding a second access. We therefore need a non-copyable type separate from `Span` in order to model mutations.
 
 #### MutableSpan
 
@@ -141,9 +142,9 @@ extension MutableSpan where Element: ~Copyable {
 ```
 ##### Bulk updating of a `MutableSpan`'s elements:
 
-We include functions to perform bulk copies into the memory represented by a `MutableSpan`. Updating a `MutableSpan` from known-sized sources (such as `Collection` or `Span`) copies every element of a source. It is an error to do so when there is the span is too short to contain every element from the source. Updating a `MutableSpan` from `Sequence` or `IteratorProtocol` instances will copy as many items as possible, either until the input is empty or until the operation has updated the item at the last index.
+We include functions to perform bulk copies of elements into the memory represented by a `MutableSpan`. Updating a `MutableSpan` from known-sized sources (such as `Collection` or `Span`) copies every element of a source. It is an error to do so when there is the span is too short to contain every element from the source. Updating a `MutableSpan` from `Sequence` or `IteratorProtocol` instances will copy as many items as possible, either until the input is empty or until the operation has updated the item at the last index.
 
-**Note:** This set of functions is sufficiently complete in functionality, but this minimal approach to slicing is only one of many possible approaches. We could revive the option of using a `some RangeExpression` parameter, or we could use the return value of a `func extracting(_: some RangeExpression)` such as was recently added to `UnsafeBufferPointer` in support of non-copyable elements. The latter option in combination with `mutating` functions requires the use of intermediate bindings.
+**Note:** This set of functions is sufficiently complete in functionality, but uses a minimal approach to slicing. This is only one of many possible approaches to slicing `MutableSpan`. We could revive the option of using a `some RangeExpression` parameter, or we could use the return value of a `func extracting(_: some RangeExpression)` such as was [recently added][SE-0437] to `UnsafeBufferPointer`. The latter option in combination with `mutating` functions requires the use of intermediate bindings. This section may change in response to feedback and our investigations.
 
 ```swift
 extension MutableSpan {
@@ -251,7 +252,22 @@ extension MutableRawSpan {
 
 ##### Accessing and modifying  the memory of a `MutableRawSpan`:
 
-The basic operations available on `RawSpan` are available for `MutableRawSpan`. These operations are not type-safe, in that the loaded value returned by the operation can be invalid, and violate type invariants. Some types have a property that makes the `unsafeLoad(as:)` function safe, but we don't have a way to [formally identify](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0447-span-access-shared-contiguous-storage.md#SurjectiveBitPattern) such types at this time.
+`MutableRawSpan` supports storing the bytes of a `BitwiseCopyable` value to its underlying memory:
+
+```swift
+extension MutableRawSpan {
+  mutating func storeBytes<T: BitwiseCopyable>(
+    of value: T, toByteOffset offset: Int = 0, as type: T.Type
+  )
+
+  @unsafe
+  mutating func storeBytes<T: BitwiseCopyable>(
+    of value: T, toUncheckedByteOffset offset: Int, as type: T.Type
+  )
+}
+```
+
+Additionally, the basic loading operations available on `RawSpan` are available for `MutableRawSpan`. These operations are not type-safe, in that the loaded value returned by the operation can be invalid, and violate type invariants. Some types have a property that makes the `unsafeLoad(as:)` function safe, but we don't have a way to [formally identify](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0447-span-access-shared-contiguous-storage.md#SurjectiveBitPattern) such types at this time.
 
 ```swift
 extension MutableRawSpan {
@@ -277,22 +293,10 @@ extension MutableRawSpan {
 }
 ```
 
-To these, `MutableRawSpan` adds functions to store the bytes of a `BitwiseCopyable` value:
-
-```swift
-extension MutableRawSpan {
-  mutating func storeBytes<T: BitwiseCopyable>(
-    of value: T, toByteOffset offset: Int = 0, as type: T.Type
-  )
+We include functions to perform bulk copies into the memory represented by a `MutableRawSpan`. Updating a `MutableRawSpan` from a `Collection` or a `Span` copies every element of a source. It is an error to do so when there is are not enough bytes in the span to contain every element from the source. Updating `MutableRawSpan` from `Sequence` or `IteratorProtocol` instance copies as many items as possible, either until the input is empty or until there are not enough bytes in the span to store another element.
 
-  @unsafe
-  mutating func storeBytes<T: BitwiseCopyable>(
-    of value: T, toUncheckedByteOffset offset: Int, as type: T.Type
-  )
-}
-```
+**Note:** This set of functions is sufficiently complete in functionality, but uses a minimal approach to slicing. This is only one of many possible approaches to slicing `MutableRawSpan`. (See the note above on )
 
-We include functions to perform bulk copies into the memory represented by a `MutableRawSpan`. Updating a `MutableRawSpan` from a `Collection` or a `Span` copies every element of a source. It is an error to do so when there is are not enough bytes in the span to contain every element from the source. Updating `MutableRawSpan` from `Sequence` or `IteratorProtocol` instance copies as many items as possible, either until the input is empty or until there are not enough bytes in the span to store another element.
 ```swift
 extension MutableRawSpan {
   mutating func update<S: Sequence>(
@@ -440,7 +444,7 @@ This proposal is additive and ABI-compatible with existing code.
 
 ## Implications on adoption
 
-The additions described in this proposal require a new version of the Swift standard library and runtime.
+The additions described in this proposal require a new version of the Swift standard library.
 
 ## Alternatives considered
 
@@ -504,7 +508,7 @@ extension MutableSpan where Element: ~Copyable {
 }
 ```
 
-Unfortunately, tuples do not support non-copyable values yet. We may be able to use `InlineArray` ([SE-0453][SE-0453]), or a bespoke type, but destructuring the non-copyable constituent part remains a challenge. Solving this issue for `Span` as well as `MutableSpan` is a top priority.
+Unfortunately, tuples do not support non-copyable values yet. We may be able to use `InlineArray` ([SE-0453][SE-0453]), or a bespoke type, but destructuring the non-copyable constituent part remains a challenge. Solving this issue for `Span` and `MutableSpan` is a top priority.
 
 #### Mutating algorithms
 
@@ -514,5 +518,5 @@ Algorithms defined on `MutableCollection` such as `sort(by:)` and `partition(b
 
 Some data structures can delegate initialization of parts of their owned memory. The standard library added the `Array` initializer `init(unsafeUninitializedCapacity:initializingWith:)` in [SE-0223][SE-0223]. This initializer relies on `UnsafeMutableBufferPointer` and correct usage of initialization primitives. We should present a simpler and safer model of initialization by leveraging non-copyability and non-escapability.
 
-## Acknowledgements
+We expect to propose an `OutputSpan<T>` type to represent partially-initialized memory, and to support to the initialization of memory by appending to the initialized portion of the underlying storage.
 
