[swift-evolution] [Review] SE-0184: Unsafe[Mutable][Raw][Buffer]Pointer: add missing methods, adjust existing labels for clarity, and remove deallocation size

[Andrew Trick]

> 
> In the new raw initializeMemory methods, Xiaodi and I agreed to make
> it more clear that the offset is in terms of `self` rather than
> `from`, and to further reduce ambiguity by forcing manual stride
> computation and using an explicit "offset" label. The call site will
> be just as explicit as dropping down to `baseAddress` but without any
> pointer conversion boilerplate.
> 
> UMRBP (raw buffer):
> +++ func initializeMemory<T>(atByteOffset:as:from:)
> +++ func moveInitializeMemory<T>(atByteOffset:as:from:)
> 
> 
> Agree, but the label should just be `atByte:`, not `atByteOffset:`. after all, we don’t use `atOffset:` in the strided case; its obvious that it’s an offset
> 
> The existing APIs use the terminology "byte offset"--for example, URP.load(fromByteOffset:as:). The rationale is that "at" without a noun that follows implies, per Swift API naming guidelines, "at index." If you want to specify, as we do here, what the index _is_, then it's written out in full.

Yes, it seems overly cumbersome, but I was following existing conventions which were intentionally very explicit.

> 
> We don't have a consensus, but I think the suggestion to distinguish
> between single value vs. multiple semantics was good. Otherwise,
> adding the default count could be very misleading. Normally, we try to
> minimize surface area, but adding two methods for the single-value case
> avoids ambiguity between the buffer and pointer semantics:
> 
> UMP (pointer)
> --- func initialize(to:count:(=1))
> +++ func initialize(to:)
> +++ func initialize(repeating:count:) // no default count
> +++ func assign(to:)
> +++ func assign(repeating:count:) // no default count
> 
> UMRP (raw pointer):
> --- func initializeMemory<T>(as:at:(=0)count:(1)to:)
> +++ func initializeMemory<T>(as:repeating:count:) // remove default count 
> 
> still extremely suspicious of this but i’m willing to compromise. also there should be an `initializeMemory<T>(at:to:)` to match the typed methods
> 
> Do you mean initializeMemory<T>(as:to:)?

I don’t think it’s necessary since raw buffers are not normally used to hold a single typed element. We don’t need symmetry between raw and typed pointers and I wouldn’t want to add an API that will never be used. So, I would be ok with it only if there’s some use case that I’m overlooking.

-Andy

> 
>> On Tue, Sep 5, 2017 at 11:31 AM, Andrew Trick <atrick at apple.com <mailto:atrick at apple.com>> wrote:
>> I think we’ve agreed to a few minor updates to this proposal. Since there hasn’t been any other feedback on the thread it may be worth posting an amended proposal so we all know what we’ve agreed on.
>> 
>> -Andy
>> 
>>> On Sep 3, 2017, at 8:23 PM, Andrew Trick via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>>> 
>>> 
>>>> On Sep 3, 2017, at 8:05 PM, Xiaodi Wu <xiaodi.wu at gmail.com <mailto:xiaodi.wu at gmail.com>> wrote:
>>>> 
>>>> If we use byte offset, then the at parameter in UnsafeMutableRawPointer should be removed, since pointer arithmetic can be used instead (just like with UnsafeMutablePointer).
>>>> 
>>>> I agree that it seems quite sensible to remove the ‘at’ parameter altogether from the UMRP method.
>>> 
>>> No code in tree or on github is using the `at` argument. I think it can be removed. A fixit should still be possible.
>>> 
>>>> Not convinced moving the at: argument to come before the as: argument is worth it in terms of source breakage.
>>>> 
>>>> Since much of this proposal involves shuffling and relabeling arguments, I’d argue it’s better to break slight more source in one go for the optimal API than to break slightly less for a slightly less optimal API, no? (This is assuming there is agreement that ‘at:as:’ is less prone to misinterpretation than ‘as:at:’.)
>>> 
>>> 
>>> To be clear, we’re just talking about UnsafeMutableRawBufferPointer.initializeMemory now, so this is purely additive.
>>> I think the label needs to be `atByteOffset`, and placing it before `as` makes a lot of sense because it no longer depends on the type’s stride. 
>>> 
>>> -Andy
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170905/4fc0c3de/attachment.html>