search

haskell / vector

An efficient implementation of Int-indexed arrays (both mutable and immutable), with a powerful loop optimisation framework .
Other
367 stars 139 forks source link

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

Open oshyshko opened 2 years ago

oshyshko commented 2 years ago
  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.

Shimuuar commented 2 years ago

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: https://github.com/haskell/vector/issues/88