You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It's not clear what is the difference between "copy" and "move".
Consider changing "may" to a strong "must" and adding a line on what happens otherwise:
Copy a vector. The two vectors must have the same length and may not overlap.
To:
Copy contents of one vector to another.
The two vectors must have the same length and must not overlap.
An error is thrown if vectors have different lengths or if overlap.
It was unclear what is the meaning of "moving a vector" and what is the difference VS "copying data".
Consider explaining "move" in terms of "copy" and changing:
Move the contents of a vector. The two vectors must have the same length.
To:
Same as "copy", but allows vectors to overlap -- at additional cost, by allocating a temporary vector for copying.
Improvement: consider deprecating "move", but make "copy" deal with overlapping vectors (at no additional cost -- see below).
In short: different copying order. If two vectors overlap, the order of copying offset + (zero..length) VS offset + (length..zero) can be chosen, depending on which of the two vectors (source and target) goes first in address (index) space. No need to allocate temporary memory.
The text was updated successfully, but these errors were encountered:
oshyshko
changed the title
Improve documentation refactor copy/unsafeCopy + move/unsafeMove in mutable APIs
Improve documentation and refactor copy + move in mutable APIs
Jul 8, 2022
I agree that documentation is rather confusing and assumes that reader is familiar with memcpy/memmove and their corresponding gotchas
copy
Copy a vector from source to destination. Both vectors must have same length and may not overlap. If any condition is violated exception is thrown.
move
Copy vector from source to destination. Both vectors must have same length. Unlike copy it allows source and destination to overlap.
Dropping distinction between copy and move would be nice of course. But then there's question: how much performance do we get by maintaining that distinction?
There's also problem of overlap not being powerful enough: #88
https://hackage.haskell.org/package/vector-0.13.0.0/docs/Data-Vector-Mutable.html#g:13
It's not clear what is the difference between "copy" and "move".
Consider changing "may" to a strong "must" and adding a line on what happens otherwise:
To:
It was unclear what is the meaning of "moving a vector" and what is the difference VS "copying data".
Consider explaining "move" in terms of "copy" and changing:
To:
In short: different copying order. If two vectors overlap, the order of copying
offset + (zero..length)
VSoffset + (length..zero)
can be chosen, depending on which of the two vectors (source and target) goes first in address (index) space. No need to allocate temporary memory.The text was updated successfully, but these errors were encountered: