TODO: `unslice` - throw exception or adjust documentation? - The documentation says we should throw if parts is not in `[0..1]` - The implementation does not throw, and just checks `part == 0`, i.e. separates zero and non-zero. For consistency with the part number elsewhere, we should probably throw in the implementation.
-------------------------------------- Found while working on JDK-8369699. In general, the Vector API documentation is a bit vague around part numbers. There was considerable confusion around expansion/contraction: are we talking about logical, physical or output expansion/contraction? Confusingly, in some places we called expansions things that go from more to fewer bits, and we called contractions that went from fewer to more bits. And exception messages are not very helpful, for example they don't provide the legal range. @rose00 took a first stab at improving things (https://github.com/openjdk/jdk/pull/29306), and I eventually took over the project. -------------------------------------- Principles: - Expansion means fewer->more bits. - Contraction means more->fewer bits. - Be clear about input, logical result and output. - We primarily use: - conversion lanewise expansion (logical) - conversion lanewise contraction (logical) - conversion lanewise in-place (logical) - reinterpret (logical) - select, for truncation (output) - insert, for padding (output) - in-place, logical fits output (output) Please review this PR in this order: - Changes in the "Expansions, contractions, and partial results" section of `Vector.java`. We must first agree on the definitions here, before we go and disagree elsewhere ;) - Changes in affected methods `convertShape`, `convert`, and `reinterpretShape`. - Internal changes in `AbstractVector.java`: adjust nomenclature and exception message. - New test. I think it is necessary, I caught some mistakes I made. And when I wanted to add tests for `unslice` I realized that it does not throw for out of bounds `part`. So I think it is justified. In general, I'm a bit worried that the documentation is a bit too long, and feels a bit heavy/overwhelming. To a large degree, this is due to the complexity of part numbers. We could drop some paragraphs and some repetition. Let me know what you think is too much. More explanations may help make things clearer, but also risk being too much and overwhelming. I'm open to cut things down more, and any other constructive suggestions ;) ------------- Commit messages: - fix up documentation a little more - more small updates - fix small issues - small fix in test and assert code - Merge branch 'master' into JDK-8375631-part-number-exception-and-documentation - more testing - cleanup and testReinterpret - systematic test - streamline - add test - ... and 20 more: https://git.openjdk.org/jdk/compare/e9446e15...4bfc90a5 Changes: https://git.openjdk.org/jdk/pull/30113/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=30113&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8375631 Stats: 1737 lines in 3 files changed: 1440 ins; 104 del; 193 mod Patch: https://git.openjdk.org/jdk/pull/30113.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/30113/head:pull/30113 PR: https://git.openjdk.org/jdk/pull/30113
