added a mapper that maps the indexes of a view to the indices of a container

[alexandrehoffmann]

Checklist

• The title and commit message(s) are descriptive.
• Small commits made to fix your PR have been squashed to avoid history pollution.
• Tests have been added for new features or bug fixes.
• API of new functions and classes are documented.

Description

The index_mapper class provides functionality to convert indices from a view's coordinate system
to the corresponding indices in the underlying container. This is particularly useful for views
that contain integral slices (fixed indices), as these slices reduce the dimensionality of the view.

Example:

xt::xarray<double> a = xt::arange(24).reshape({2, 3, 4});
auto view1 = xt::view(a, 1, xt::all(), xt::all());  // Fixed first dimension
index_mapper<decltype(view1)> mapper;

// Map view indices (i,j) to container indices (1,i,j)
double val = mapper.map(a, view1, 0, 0);  // Returns a(1, 0, 0)
double val2 = mapper.map(a, view1, 1, 2); // Returns a(1, 1, 2)

[Copilot]

Pull request overview

This PR introduces a new index_mapper class that enables conversion of indices from a view's coordinate system to the underlying container's coordinate system. This is particularly useful when working with views that contain fixed dimensions (integral slices), which reduce the dimensionality compared to the original container.

Key Changes:

• Implements index_mapper template class with support for xview types
• Provides map() and map_at() methods for index conversion with and without bounds checking
• Adds comprehensive test coverage for 2D and 3D views with various slicing patterns

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 22 comments.

File	Description
include/xtensor/views/index_mapper.hpp	New header file implementing the index_mapper class with template metaprogramming to handle view-to-container index mapping
test/test_xview.cpp	Adds test cases for index_mapper functionality covering simple 2D views and 3D views with various slice configurations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The assertion message is misleading in the documentation. The assertion checks that the index is within bounds (i < slice.size()), but the documentation states it "throws Assertion failure if i >= slice.size()". While technically correct, assertions don't throw exceptions in the traditional sense - they abort the program in debug builds. Consider updating the documentation to clarify this behavior or use proper exception handling if runtime bounds checking is desired.

Suggested change

	* @throws Assertion failure if `i != 0` for integral slices.
	* @throws Assertion failure if `i >= slice.size()` for non-integral slices.
	* @note This function uses assertions to enforce preconditions:
	* - Aborts with assertion failure if `i != 0` for integral slices.
	* - Aborts with assertion failure if `i >= slice.size()` for non-integral slices.
	* These are not exceptions and will terminate the program in debug builds if triggered.

[Copilot]

The dimension() method returns the number of free (non-integral) dimensions, but the method name is ambiguous. It's unclear whether this returns the view's dimension or the container's dimension. Consider renaming to free_dimensions() or view_dimension() to make the purpose clearer.

Suggested change

	constexpr size_t dimension() const { return n_free; }
	constexpr size_t free_dimensions() const { return n_free; }