std::extents

Introduction

std::extents is a class template introduced in C++23 as part of the multidimensional array support. It represents the extents (sizes) of each dimension in a multidimensional array or view. This class is particularly useful when working with std::mdspan, which provides a view over multidimensional array data. Let's explore std::extents through various examples to understand its usage and benefits.

Example 1: Basic Usage of std::extents

#include <iostream>
#include <array>
#include <span>

int main() {
    // Create extents for a 3x4 array
    std::extents<std::size_t, 3, 4> ex;

    std::cout << "Rank: " << ex.rank() << std::endl;
    std::cout << "Extent of dimension 0: " << ex.extent(0) << std::endl;
    std::cout << "Extent of dimension 1: " << ex.extent(1) << std::endl;
    std::cout << "Total size: " << ex.prod() << std::endl;

    return 0;
}

Explanation

• We create an std::extents object ex representing a 3x4 array.
• rank() returns the number of dimensions (2 in this case).
• extent(0) and extent(1) return the sizes of the first and second dimensions, respectively.
• prod() returns the total number of elements (3 * 4 = 12).

Example 2: Dynamic Extents

#include <iostream>
#include <array>
#include <span>

int main() {
    std::size_t rows = 3;
    std::size_t cols = 4;

    // Create extents with dynamic dimensions
    std::extents<std::size_t, std::dynamic_extent, std::dynamic_extent> ex(rows, cols);

    std::cout << "Rank: " << ex.rank() << std::endl;
    std::cout << "Extent of dimension 0: " << ex.extent(0) << std::endl;
    std::cout << "Extent of dimension 1: " << ex.extent(1) << std::endl;
    std::cout << "Is dimension 0 dynamic? " << ex.is_dynamic(0) << std::endl;
    std::cout << "Is dimension 1 dynamic? " << ex.is_dynamic(1) << std::endl;

    return 0;
}

Explanation

• We create an std::extents object with dynamic dimensions using std::dynamic_extent.
• The actual sizes are provided at runtime (3 and 4 in this case).
• is_dynamic(0) and is_dynamic(1) return true, indicating that both dimensions are dynamic.

Example 3: Using std::extents with std::mdspan

#include <iostream>
#include <vector>
#include <mdspan>

int main() {
    std::vector<int> data = {1, 2, 3, 4, 5, 6};

    // Create extents for a 2x3 array
    std::extents<std::size_t, 2, 3> ex;

    // Create an mdspan using the extents
    std::mdspan<int, decltype(ex)> matrix(data.data(), ex);

    // Access elements using 2D indexing
    for (std::size_t i = 0; i < ex.extent(0); ++i) {
        for (std::size_t j = 0; j < ex.extent(1); ++j) {
            std::cout << matrix[i, j] << " ";
        }
        std::cout << std::endl;
    }

    return 0;
}

Explanation

• We create an std::extents object ex representing a 2x3 array.
• We use this ex to create an std::mdspan over a vector of data.
• The mdspan allows us to access the data using 2D indexing, even though the underlying data is stored in a 1D vector.

Example 4: Comparing and Manipulating Extents

#include <iostream>
#include <array>
#include <span>

int main() {
    std::extents<std::size_t, 3, 4> ex1;
    std::extents<std::size_t, 3, 4> ex2;
    std::extents<std::size_t, 3, 5> ex3;

    std::cout << "ex1 == ex2: " << (ex1 == ex2) << std::endl;
    std::cout << "ex1 == ex3: " << (ex1 == ex3) << std::endl;

    // Create a new extents object by adding a dimension
    auto ex4 = ex1.prepend_extent(2);
    std::cout << "Rank of ex4: " << ex4.rank() << std::endl;
    std::cout << "First dimension of ex4: " << ex4.extent(0) << std::endl;

    return 0;
}

Explanation

• We compare different std::extents objects using the == operator.
• We use the prepend_extent() method to create a new std::extents object with an additional dimension at the beginning.
• The resulting ex4 object has a rank of 3 and dimensions 2x3x4.

Summary

std::extents is a powerful tool for representing the dimensions of multidimensional arrays in C++23. It provides a type-safe way to work with array dimensions, supporting both static and dynamic extents. Key features include:

1. Representing fixed and dynamic dimensions
2. Querying the rank and individual extents
3. Calculating the total size of the array
4. Checking if dimensions are dynamic
5. Comparing extents objects
6. Manipulating extents (e.g., adding dimensions)

When used in conjunction with std::mdspan, std::extents enables efficient and flexible handling of multidimensional array views, improving code readability and maintainability in scientific computing, image processing, and other domains that frequently work with multidimensional data.

Related

• What is the purpose of std::extents in C++
• How does std::extents differ from other extent types in C++
• Can you provide examples of using std::extents in C++ code
• Is std::extents part of the C++ Standard Library
• How does std::extents interact with other C++ templates