<div dir="ltr"><div><div>How would you feel about:<br><br><span style="font-family:monospace,monospace">struct UnsafeMutableRawBufferPointer<br>{<br><br>--- static func allocate(count:Int) -&gt; UnsafeMutableRawBufferPointer<br>+++ static func allocate(bytes:Int, alignedTo:Int) -&gt; UnsafeMutableRawBufferPointer<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">    </span>func deallocate()<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">+++ </span>func bindMemory&lt;Element&gt;(to:Element.Type, capacity:Int)<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">+++ </span>func copy(from:UnsafeRawBufferPointer, bytes:Int)<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">+++ </span>func initializeMemory&lt;Element&gt;(as:Element.Type, at:Int, count:Int, to:Element)<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">+++ </span>func initializeMemory&lt;Element&gt;(as:Element.Type, from:UnsafeBufferPointer&lt;Element&gt;, count:Int)<br></span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">+++ </span>func moveInitializeMemory&lt;Element&gt;(as:Element.Type, from:UnsafeMutableBufferPointer&lt;Element&gt;, count:Int<br>}<br><br></span></div><div><span style="font-family:monospace,monospace">“bytes”    = 8 bit quantities (don’t @ me we’re assuming 8 bit bytes)<br></span></div><div><span style="font-family:monospace,monospace">“capacity” = strided quantities, not </span><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">assumed</span> to be initialized <br></span></div><div><span style="font-family:monospace,monospace">“count”    = strided quantities, assumed to be initialized<br></span></div><div><span style="font-family:monospace,monospace"><br></span></div><span style="font-family:monospace,monospace"><font face="arial,helvetica,sans-serif">It’s also worth nothing that a lot of what the proposal tries to add to </font>UnsafeBufferPointer<font face="arial,helvetica,sans-serif"> is already present in </font>UnsafeMutableRawPointer<font face="arial,helvetica,sans-serif"> like a sizeless </font>deallocate()<font face="arial,helvetica,sans-serif"> and a sizeless </font>copyBytes(from:)<font face="arial,helvetica,sans-serif">.</font><br></span><span style="font-family:arial,helvetica,sans-serif"><br></span></div><span style="font-family:arial,helvetica,sans-serif">Although I’m not sure what’s going on <a href="https://developer.apple.com/documentation/swift/unsafemutablerawbufferpointer/2635415-copybytes">with the latter one</a>…lol swiftdoc<br></span><span style="font-family:monospace,monospace"><br></span></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Jul 14, 2017 at 1:57 AM, Andrew Trick <span dir="ltr">&lt;<a href="mailto:atrick@apple.com" target="_blank">atrick@apple.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><span class=""><br><div><blockquote type="cite"><div>On Jul 13, 2017, at 10:30 PM, Taylor Swift &lt;<a href="mailto:kelvin13ma@gmail.com" target="_blank">kelvin13ma@gmail.com</a>&gt; wrote:</div><br class="m_-6519521782113237754Apple-interchange-newline"><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">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">count</span>`, `<span style="font-family:monospace,monospace">capacity</span>`, and `<span style="font-family:monospace,monospace">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><br>“““<br><em>Finally, the naming and design of some<span class="m_-6519521782113237754Apple-converted-space"> </span><code>UnsafeMutableRawPointer</code><span class="m_-6519521782113237754Apple-converted-space"> </span>m<wbr>embers deserves to be looked at. The usage of<span class="m_-6519521782113237754Apple-converted-space"> </span><code>capacity</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code>bytes</code>, and<span class="m_-6519521782113237754Apple-converted-space"> </span><code>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>copyBytes(from:count:)</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code>cou<wbr>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>initializeMemory&lt;T&gt;(as:at:<wbr>count:to:)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>and<span class="m_-6519521782113237754Apple-converted-space"> </span><code>initializeMemor<wbr>y&lt;T&gt;(as:from:count:)</code>,<span class="m_-6519521782113237754Apple-converted-space"> </span><code>count</code><span class="m_-6519521782113237754Apple-converted-space"> </span>re<wbr>fers to the number of strides. Meanwhile<span class="m_-6519521782113237754Apple-converted-space"> </span><code>bindMemory&lt;T&gt;(to:<wbr>capacity:)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>uses<span class="m_-6519521782113237754Apple-converted-space"> </span><code>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>deallocate(<wbr>bytes:alignedTo)</code><span class="m_-6519521782113237754Apple-converted-space"> </span>method and<span class="m_-6519521782113237754Apple-converted-space"> </span><code>allocate(bytes:alignedTo:)</code><span class="m_-6519521782113237754Apple-converted-space"><wbr> </span>type methods use<span class="m_-6519521782113237754Apple-converted-space"> </span><code>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>UnsafeMutableRawBuf<wbr>ferPointer</code><span class="m_-6519521782113237754Apple-converted-space"> </span>offers an<span class="m_-6519521782113237754Apple-converted-space"> </span><code>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>UnsafeMutableBufferPointer</code>)<wbr>, except the<span class="m_-6519521782113237754Apple-converted-space"> </span><code>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>”””<br><br></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">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">UnsafeMutablePointer.assign(<wbr>to:)</span>` are there for API consistency.<br><br></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">This proposal also calls for getting rid of one of those “redundant initializers” :)</div></div></blockquote></div><br></span><div>Since we’re not bike-shedding the specifics yet, I’ll just give you some background.</div><div><br></div><div>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><br></div><div>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><br></div><div>I initially proposed copy(bytes:from:), but someone thought that `bytes` in this particular context did not properly convey the &quot;count of bytes&quot; 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><br></div><div>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><br></div><div>-Andy</div></div></blockquote></div><br></div>