<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jul 14, 2017, at 9:33 AM, Taylor Swift <<a href="mailto:kelvin13ma@gmail.com" class="">kelvin13ma@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class=""><div class=""><div class="">How would you feel about:<br class=""><br class=""><span style="font-family:monospace,monospace" class="">struct UnsafeMutableRawBufferPointer<br class="">{<br class=""><br class="">--- static func allocate(count:Int) -> UnsafeMutableRawBufferPointer<br class="">+++ static func allocate(bytes:Int, alignedTo:Int) -> UnsafeMutableRawBufferPointer<br class=""></span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class=""> </span>func deallocate()<br class=""></span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">+++ </span>func bindMemory<Element>(to:Element.Type, capacity:Int)<br class=""></span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">+++ </span>func copy(from:UnsafeRawBufferPointer, bytes:Int)<br class=""></span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">+++ </span>func initializeMemory<Element>(as:Element.Type, at:Int,</span><span style="font-family: monospace, monospace;" class=""> </span><span style="font-family: monospace, monospace;" class="">to:Element, </span><span style="font-family: monospace, monospace;" class="">count:Int)</span></div></div></div></div></blockquote><blockquote type="cite" class=""><div class=""><div dir="ltr" class=""><div class=""><div class=""><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">+++ </span>func initializeMemory<Element>(as:Element.Type, from:UnsafeBufferPointer<Element>, count:Int)<br class=""></span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">+++ </span>func moveInitializeMemory<Element>(as:Element.Type, from:UnsafeMutableBufferPointer<Element>, count:Int<br class="">}<br class=""><br class=""></span></div><div class=""><span style="font-family:monospace,monospace" class="">“bytes” = 8 bit quantities (don’t @ me we’re assuming 8 bit bytes)<br class=""></span></div><div class=""><span style="font-family:monospace,monospace" class="">“capacity” = strided quantities, not </span><span style="font-family:monospace,monospace" class=""><span style="font-family:monospace,monospace" class="">assumed</span> to be initialized <br class=""></span></div><div class=""><span style="font-family:monospace,monospace" class="">“count” = strided quantities, assumed to be initialized<br class=""></span></div><div class=""><span style="font-family:monospace,monospace" class=""><br class=""></span></div><span style="font-family:monospace,monospace" class=""><font face="arial,helvetica,sans-serif" class="">It’s also worth nothing that a lot of what the proposal tries to add to </font>UnsafeBufferPointer<font face="arial,helvetica,sans-serif" class=""> is already present in </font>UnsafeMutableRawPointer<font face="arial,helvetica,sans-serif" class=""> like a sizeless </font>deallocate()<font face="arial,helvetica,sans-serif" class=""> and a sizeless </font>copyBytes(from:)<font face="arial,helvetica,sans-serif" class="">.</font><br class=""></span><span style="font-family:arial,helvetica,sans-serif" class=""><br class=""></span></div><span style="font-family:arial,helvetica,sans-serif" class="">Although I’m not sure what’s going on <a href="https://developer.apple.com/documentation/swift/unsafemutablerawbufferpointer/2635415-copybytes" class="">with the latter one</a>…lol swiftdoc<br class=""></span></div></div></blockquote><div><br class=""></div><div>Purely in terms of label names, what you have above is perfectly fine.</div><div><br class=""></div><div>You’re going to have a problem adding the alignment constraint to buffer pointer, but that’s another topic.</div><div><br class=""></div><div>-Andy</div><br class=""><blockquote type="cite" class=""><div class=""><div class="gmail_extra"><div class="gmail_quote">On Fri, Jul 14, 2017 at 1:57 AM, Andrew Trick <span dir="ltr" class=""><<a href="mailto:atrick@apple.com" target="_blank" class="">atrick@apple.com</a>></span> wrote:<br class=""><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word" class=""><span class=""><br class=""><div class=""><blockquote type="cite" class=""><div class="">On Jul 13, 2017, at 10:30 PM, Taylor Swift <<a href="mailto:kelvin13ma@gmail.com" target="_blank" class="">kelvin13ma@gmail.com</a>> wrote:</div><br class="m_-6519521782113237754Apple-interchange-newline"><div class=""><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant-caps:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class="">I’m confused I thought we were talking about the naming choices for the argument labels in those functions. I think defining and abiding by consistent meanings for `<span style="font-family:monospace,monospace" class="">count</span>`, `<span style="font-family:monospace,monospace" class="">capacity</span>`, and `<span style="font-family:monospace,monospace" class="">bytes</span>` is a good idea, and it’s part of what this proposal tries to accomplish. Right now half the time we use `count` to refer to “bytes” and half the time we use it to refer to “instances”. The same goes for the word “capacity”. This is all laid out in the document:<br class=""><br class="">“““<br class=""><em class="">Finally, the naming and design of some<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">UnsafeMutableRawPointer</code><span class="m_-6519521782113237754Apple-converted-space"> </span>m<wbr class="">embers deserves to be looked at. The usage of<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">capacity</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">bytes</code>, and<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">count</code><span class="m_-6519521782113237754Apple-converted-space"> </span>as argument labels is wildly inconsistent and confusing. In<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">copyBytes(from:count:)</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">cou<wbr class="">nt</code><span class="m_-6519521782113237754Apple-converted-space"> </span>refers to the number of bytes, while in<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">initializeMemory<T>(as:at:<wbr class="">count:to:)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>and<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">initializeMemor<wbr class="">y<T>(as:from:count:)</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">count</code><span class="m_-6519521782113237754Apple-converted-space"> </span>re<wbr class="">fers to the number of strides. Meanwhile<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">bindMemory<T>(to:<wbr class="">capacity:)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>uses<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">capacity</code><span class="m_-6519521782113237754Apple-converted-space"> </span>to refer to this quantity. The always-problematic<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">deallocate(<wbr class="">bytes:alignedTo)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>method and<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">allocate(bytes:alignedTo:)</code><span class="m_-6519521782113237754Apple-converted-space"><wbr class=""> </span>type methods use<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">bytes</code><span class="m_-6519521782113237754Apple-converted-space"> </span>to refer to byte-quantities. Adding to the confusion,<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">UnsafeMutableRawBuf<wbr class="">ferPointer</code><span class="m_-6519521782113237754Apple-converted-space"> </span>offers an<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">allocate(count:)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>type method (the same signature method we’re trying to add to<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">UnsafeMutableBufferPointer</code>)<wbr class="">, except the<span class="m_-6519521782113237754Apple-converted-space"> </span><code class="">count</code><span class="m_-6519521782113237754Apple-converted-space"> </span>in this method refers to bytes. This kind of API naming begets stride bugs and makes Swift needlessly difficult to learn.</em><br class="">”””<br class=""><br class=""></div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant-caps:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class="">The only convenience methods this proposal is trying to add is the functionality on the buffer pointer types. There seems to be broad support for adding this functionality as no one has really opposed that part of the proposal yet. Any other new methods like `<span style="font-family:monospace,monospace" class="">UnsafeMutablePointer.assign(<wbr class="">to:)</span>` are there for API consistency.<br class=""><br class=""></div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant-caps:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class="">This proposal also calls for getting rid of one of those “redundant initializers” :)</div></div></blockquote></div><br class=""></span><div class="">Since we’re not bike-shedding the specifics yet, I’ll just give you some background.</div><div class=""><br class=""></div><div class="">We would ultimately like APIs that allocate and initialize in one go. It’s important that the current lower-level (dangerous) APIs make a clear distinction between initialized and uninitialized memory to avoid confusing them with future (safer) APIs. `capacity` always refers to memory that may be uninitialized. I think that’s very clear and helpful.</div><div class=""><br class=""></div><div class="">In the context of pointers `count` should always be in strides. For raw pointers, that happens to be the same as as `bytes`.</div><div class=""><br class=""></div><div class="">I initially proposed copy(bytes:from:), but someone thought that `bytes` in this particular context did not properly convey the "count of bytes" as opposed to the source of the bytes. You’re right, that’s inconsistent with allocate/deallocate(bytes:), because allocateBytes(count:) would be silly. Just be aware that the inconsistency is a result of over-thinking and excessive bike shedding to the detriment of something that looks nice and is easy to remember.</div><div class=""><br class=""></div><div class="">I should also point out that the inconsistencies in functionality across pointer types, in terms of collection support and other convenience, is also known but was deliberately stripped from proposals as “additive”.</div><div class=""><br class=""></div><div class="">-Andy</div></div></blockquote></div><br class=""></div>
</div></blockquote></div><br class=""></body></html>