[SR-13486] _withUnsafeMutableBufferPointerIfSupported/withContiguousMutableStorageIfAvailable semantics and docs #55928
Labels
bug
A deviation from expected or documented behavior. Also: expected but undesirable behavior.
standard library
Area: Standard library umbrella
Additional Detail from JIRA
md5: 35b6ecbdcb3043b2bac85f7ab2130a33
Issue Description:
These two methods have identical doc comments. If I'm working on the stdlib, how should I understand the difference?
Secondly, the doc comments should start with "Calls," not "Call"
Third, they contradict themselves:
> Call `body(p)`, where `p` is a pointer to the collection's mutable contiguous storage. If no such storage exists, it is first created.
Okay, so mutable contiguous storage is created if none is available, and body is called on it.
> If the collection does not support an internal representation in a form of mutable contiguous storage, `body` is not called and `nil` is returned.
In a collection that doesn't support an internal representation in a form of mutable contiguous storage, obviously no such storage exists, so according to the second sentence it should be created. This is a contradiction, and the inability to clearly specify what the method does is a big part of the reason I originally opposed its inclusion in the library: we clearly don't know what it is.
I think (though I'm guessing) what's actually meant is something more like, “If the collection supports a mutable contiguous storage representation, converts (if necessary) the instance to use that representation and returns the result of passing the storage to `body`; returns `nil` otherwise.“
But note that this description doesn't work for the immutable contiguous storage method on
Sequence
, becauseArray
implements the operation but can't change its representation in a non-mutating method.I still think these operations are highly suspect, but at least please clear up their meaning.
Thanks
The text was updated successfully, but these errors were encountered: