Improve documentation and refactor `copy` + `move` in mutable APIs
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Refactor
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- haskell
- Domain
- api, documentation
Research direction
Start with the Data-Vector-Mutable documentation linked in the issue and compare the documented copy and move contracts. Determine whether the requested wording changes and overlap-handling or deprecation proposal are accepted; done means the API behavior and documentation have a settled, tested design.
Written by the indexing model from the issue text.
Description
- 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.
- 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.
- Dominant language
- Haskell
- Stars
- 401
- Forks
- 145
- PR merge metrics
- No merged PRs in 30d
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from haskell/vector
-
Difficulty 1/5 Under an hour Newbie friendliness 68/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 3/5 1-2 days Newbie friendliness 55/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Similar issues
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
enhancement tricorder
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
zip-archive-0.5 Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
commercialhaskell/stackage#8124 · 1 comment ·
-
chore
Difficulty 1/5 Under an hour Newbie friendliness 91/100
alunduil/alunduil-chezmoi#792 ·