Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation and refactor copy + move in mutable APIs #440

Open
oshyshko opened this issue Jul 8, 2022 · 1 comment
Open

Improve documentation and refactor copy + move in mutable APIs #440

oshyshko opened this issue Jul 8, 2022 · 1 comment

Comments

@oshyshko
Copy link

oshyshko commented Jul 8, 2022

  1. Consider updating existing documentation for copy/move:
    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:

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.

  1. 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.

@oshyshko 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
@Shimuuar
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants