Thanks for the feedback so far. I’d like to use some of the feedback to make changes to the proposal.
First, I’d like to use @xwu’s suggestion of fromContentsOf:
as a replacement for my proposed fromElements:
argument label for the copy-from-Collection
functions. It's much better.
Second, as noticed by @benrimmington, one returned tuple had the wrong label. As @xwu noted, adding labels to an existing returned tuple has an extremely small chance of being actually source breaking. Given that, I’d like to standardize the labels of all the tuple returning functions to (unwritten: Iterator, index: Index)
. (The two cases that return the tuple (unwritten: Iterator, initialized: UnsafeMutableBufferPointer)
do not change.)
Finally and most interestingly, Karoy’s arguments are convincing me that we can make an improvement to those copy-from-Collection
functions by requiring the receiving buffer to have enough space to receive every element from the source. My initial inclination was to permissively defer entirely to the user, but that does make the APIs more complicated to use in many cases. This was informed by experience with the Sequence
-based API we’ve had to use before, where a requirement is stated but is spottily enforced, resulting in capricious behavior in practice, where one had to double-check the result regardless. These new API, being Collection
-based, can straightforwardly require that buffer.count
must be larger than source.count
. This won’t change the function signatures, but will change the documentation. Note also that if a user needs the behaviour initially proposed, it can easily be composed it from available information: let index = buffer.initialize(fromElements: source.prefix(buffer.count))
.