G
YouTube TikTok Games
Skip to content

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

Open

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.

Activity

  1. changed the title [-]Improve documentation refactor copy/unsafeCopy + move/unsafeMove in mutable APIs[/-] [+]Improve documentation and refactor `copy` + `move` in mutable APIs[/+] on Jul 8, 2022
  2. Shimuuar commented on Jul 18, 2022

    @Shimuuar
    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

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