Skip to content

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

Open
@oshyshko

Description

@oshyshko
  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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions