Document drop index ordering and reset reused slice offsets

[allenflux]

Checklist

• The title and commit message(s) are descriptive.
• Small commits made to fix the PR have been squashed.
• Tests have been added for the bug fix.
• The affected API contract is documented.

Description

Fixes #2595 by documenting the ordering precondition for xt::drop: indices must be in increasing order after negative indices are resolved relative to the sliced axis. For an axis of size 6, drop(0, -1) resolves to {0, 5}, whereas drop(-1, 0) is outside this contract. Callers ensure the order; the library performs no sorting or order check.

Reset the cumulative offset map before rebuilding a reused drop slice. With drop(-2, -1), normalization for axis sizes 4 and then 6 uses ordered positions in both cases, but an old offset entry makes slice(2) return 4 instead of 2. A single two-assertion regression covers this stale state. Existing keep behavior is unchanged.

Validation on macOS arm64 with Apple Clang 21 and C++20:

• The regression fails against the original upstream implementation and passes with the fix.
• Official complete test_xtensor_lib: 1,251 cases / 19,719 assertions pass, including optional JSON/MIME coverage; no cases skipped.
• test_xview and test_xdynamic_view pass in Release, combined ASan/UBSan, and default column-major builds. Sanitizer coverage is limited to these related targets; leak detection is disabled on macOS and the existing CMake configuration disables signed-integer-overflow instrumentation.
• Pinned clang-format 17.0.6, standalone-header compilation, new RST paragraph syntax, and git diff --check pass. Full Sphinx/Doxygen output was not built.

The existing xsort compilation warnings and non-failing xinfo type-name warning remain unchanged. AI assistance was used for investigation, implementation, tests, validation, and this description. Duplicate and out-of-range indices remain outside this change's scope.

[codspeed]

Merging this PR will not alter performance

⚠️ 1 benchmark measured no execution time

Nothing ran under measurement, usually because the compiler removed the code under test. This result is not comparable, so it counts as unchanged.

Preventing compiler optimizations

• create_xview

✅ 255 untouched benchmarks

---

_{Comparing allenflux:oct11-fix-drop-index-order (19e11a2) with master (d9a57b6)}

[JohanMabille]

Thanks for the fix! I think it would be better to require the indices to be sorted and let the user check that to avoid performance hit, what do you think?

[JohanMabille]

Thanks again. The failure is unrelated to this PR.