[swift-evolution] [late pitch] UnsafeBytes proposal

[Andrew Trick]

> On Aug 12, 2016, at 7:47 PM, Andrew Trick via swift-evolution <swift-evolution at swift.org> wrote:
> 
>> 
>> On Aug 12, 2016, at 7:32 PM, Brent Royal-Gordon <brent at architechies.com> wrote:
>> 
>>> On Aug 12, 2016, at 6:12 PM, Andrew Trick via swift-evolution <swift-evolution at swift.org> wrote:
>>> 
>>> This proposal adds basic usability for working with raw memory without breaking source. The need to provide higher level API for working with raw memory buffers has always been evident, but making improvements in this area depended on first introducing `UnsafeRawPointer`. It was not clear until the final week of source-breaking changes whether SE-0107 would make it into Swift 3. Now that it has, we should use the little remaining time to improve the migration experience and encourage correct use of the memory model by introducing a low-risk additive API.
>>> 
>>> Proposal:
>>> 
>>> https://github.com/atrick/swift-evolution/blob/unsafebytes/proposals/NNNN-UnsafeBytes.md
>>> 
>>> <NNNN-UnsafeBytes.md>
>> 
>> I've only read a little but so far, but: Is the difference between this and UnsafeBufferPointer that it's built around a raw pointer rather than a bound pointer? If so, would UnsafeRawBufferPointer be a better name?
> 
> Yes that’s exactly right. Semantically, reads or writes on `UnsafeBytes` are untyped memory accesses. So you can get bytes into or out of it without binding memory.
> 
> But as you’ll see from the interfaces and examples I’ve shown, `UnsafeMutableRawBufferPointer` would be a terrible name. There’s no reason from the user’s point of view to link this type to `UnsafeBufferPointer` and that names conveys no additionally useful information.  It’s often viewed as just a collection of Bytes and potentially an important type for a number of public interfaces.


I can give you a less dissmissive answer to this, because there is potential for confusion given that the value is actually a view over the bytes, not the bytes. I just don't think a longer name will clarify the semantics:

- `Bytes` sufficiently conveys a region of raw memory.

- The `Unsafe` already hints that this is only a "view" into memory,
  not a copy of the Bytes, and suggests that the developer needs to
  consult the doc comment if using it in a non-idiomatic way.

- In the expected idioms (see examples) this simple name will be far
  more meaningful and less distracting.

- Adding `Raw` to the name is purely redundant and adding `Buffer`,
  and `Pointer` into the name would cause confusion.

I think both your and Xiaodi's comments can be addressed by clarifying
the doc comments:

/// A non-owning view of raw memory as a collection of `UInt8` bytes.
///
/// Reads and writes on memory via `UnsafeBytes` are untyped operations that
/// do no require binding the memory to `UInt8`.
///
/// In addition to the `Collection` interface, this provides a bounds-checked
/// version of `UnsafeMutableRawPointer`'s interface to raw memory:
/// `load(fromByteOffset:as:)`, `storeBytes(of:toByteOffset:as:)`, and
/// `copyBytes(from:count:)`.
///
/// Because this is only a view into memory, and does not own the memory,
/// copying a value of type `UnsafeMutableBytes` does not copy the underlying
/// memory. However, assigning into `UnsafeMutableBytes` via a subscript copies
/// bytes into the memory, and assigning an `UnsafeMutableBytes` into a
/// value-based collection, such as `[UInt8]` copies bytes out of memory.
///
/// Example:
///
///   // View a slice of memory at someBytes.
///   var destBytes = someBytes[0..<n]
///
///   // Copy `n` bytes of data from sourceBytes into that view.
///   destBytes[0..<n] = sourceBytes
///
///   // View a different slice memory at someBytes.
///   destBytes = someBytes[n..<m]

-Andy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160812/c82320be/attachment.html>