Inconsistant naming of unsafe "conversion" functions


(Frank Swarbrick) #1

There seem to be quite a few inconsistencies with regard to the "withUnsafe" functions that invoke a closure that works with pointers and "pointer buffers".

First, a summary of the functions/methods and their names.

Free functions

func withUnsafePointer<T, Result>(to: T, (UnsafePointer<T>) -> Result) -> Result
func withUnsafePointer<T, Result>(to: inout T, (UnsafePointer<T>) -> Result) -> Result
func withUnsafeMutablePointer<T, Result>(to: inout T, (UnsafeMutablePointer<T>) -> Result) -> Result

Summary: works with typed pointer

func withUnsafeBytes<T, Result>(of: T, (UnsafeRawBufferPointer) -> Result) -> Result
func withUnsafeBytes<T, Result>(of: inout T, (UnsafeRawBufferPointer) -> Result) -> Result
func withUnsafeMutableBytes<T, Result>(of: inout T, (UnsafeMutableRawBufferPointer) -> Result) -> Result

Summary: works with raw buffer pointer

Array methods

func withUnsafeBufferPointer<R>((UnsafeBufferPointer<Array<Element>.Element>) -> R) -> R
func withUnsafeMutableBufferPointer<R>((inout UnsafeMutableBufferPointer<Array<Element>.Element>) -> R) -> R

Summary: works with typed buffer pointer

func withUnsafeBytes<R>((UnsafeRawBufferPointer) -> R) -> R
func withUnsafeMutableBytes<R>((UnsafeMutableRawBufferPointer) -> R) -> R

Summary: works with raw buffer pointer

Data methods

func withUnsafeBytes<ResultType, ContentType>((UnsafePointer<ContentType>) -> ResultType) -> ResultType
func withUnsafeMutableBytes<ResultType, ContentType>((UnsafeMutablePointer<ContentType>) -> ResultType) -> ResultType

Summary: works with typed pointer

Summary of summary:

  • withUnsafe[Mutable]Pointer

    • Free functions: Typed pointer
    • Array methods: Name not used
    • Data methods: Name not used
  • withUnsafe[Mutable]Bytes

    • Free functions: Raw buffer pointer
    • Array methods: Raw buffer pointer
    • Data methods: Typed pointer
  • withUnsafe[Mutable]BufferPointer

    • Free functions: Name not used
    • Array methods: Typed buffer pointer
    • Data methods: Name not used

Another summary of inconsistencies (in the following I refer to a "buffer pointer" as "buffer"):

  • Free functions work with typed pointers and raw buffers.
  • Array functions worth with typed and raw buffers.
  • Data functions work with typed pointers only.

I make the following suggestions.

First, a pet peeve of mine. Unsafe[Mutable][Raw]BufferPointer should be renamed to Unsafe[Mutable][Raw]Buffer. It's not a pointer. It's a buffer (structure) that contains a pointer (baseAddress) and a count.

Rename the "conversion function names" as follows (assuming the above rename of BufferPointer to Buffer)

  • Typed pointer: withUnsafe[Mutable]Pointer<T>
  • Raw pointer: withUnsafe[Mutable]RawPointer
  • Typed buffer: withUnsafe[Mutable]Buffer<T>
  • Raw buffer: withUnsafe[Mutable]RawBuffer

At the very least, add a method to Data that works with a (typed? raw?) buffer. Not sure if, for example, Array needs a function to worth with pointers directly, since its easy enough to use baseAddress of the buffer.

No idea if its reasonable to expect this to happen, but I had to bring it up.


(Ben Rimmington) #2

@Andrew_Trick suggested some API changes in SR-5363, which might be implemented in: