On Wed, Jan 21, 2026 at 1:56 PM Andrzej Krzemienski <akrzemi1@gmail.com> wrote:
What do you mean by contract?
All the characteristics that are usually described when documenting the Standard Library functions: https://cppreference.com/w/cpp/utility/optional/transform.html
Like: return type, constraints, const/constexpr properties, postconditions. In this case, I was interested in what properties the returned range has: random-access, contiguous? I naturally expect that it is a contiguous range for multi::array and multi::array_ref, so I wanted to confirm that. I suppose it is different for subarrays. I can hardly imagine they would have the same range category.
return type: A custom `elements_type`, which is a random access range. for `multi::array` the type is `multi::subarray<T, 1>` because it can be contiguous. no contraints, .elements() always returns something valid, even if the array is empty. it is constexpr. postcontions, nothing changes, .elements() is just another view. I say this now: "As an alternative, the elements can be iterated in a flat manner, using the `.elements()` member. This "elements" range also provides the `begin` and `end` iterators (`.elements().begin()`) and indexing, in the canonical order of the original arrays (rightmost index changes fastest). The elements range is always random-access, but it can be contiguous depending on the original array (`multi::array` generally give contiguous element ranges.)" In the reference section, ``` | `elements` | a flatted random-access view of all the elements rearranged canonically. `A.elements()[0] -> A[0][0]`, `A.elements()[1] -> A[0][1]`, etc. The type of the result is not a subarray but a special kind of random-access range. Takes no arguments. ``` And, later for array_ref, ``` | `elements` | a flatten random-access and contiguous view of all the elements in the array in canonical order. (This is overwritten from the base class, to provide contiguous access) ``` I also added that all member functions are constexpr unless specified differently. (almost all member functions are constexpr, a couple of exceptions is some destructors and some constructors, due to C++17 limitations).
The search box leads me to: "a flatted view of all the elements rearranged canonically. A.elements()[0] → A[0][0], A.elements()[1] → A[0][1], etc. The type of the result is not a subarray but a special kind of range. Takes no argument."
It takes me to subarray::elements, but that doesn't imply that array::elements would have the same contract. "special kind of range" is not the level of detail that I expected. I think you owe the user the range category.
range category: always random access, contiguous for multi::array. Thanks, Alfredo On Wed, Jan 21, 2026 at 1:56 PM Andrzej Krzemienski <akrzemi1@gmail.com> wrote:
6. The interface discoverability is not great: I wanted to quickly check the contract of `array::elements()`. I cannot find it. The reference section only has repeated text "same as for dynamic_array" (no link). Generally, the "redirect" philosophy in the reference documentation is mean.In order to look up the semantics of array::operator(), I am redirected: first from `array` to `dynamic_array`, then to `array_ref`, and only then to `subarray`.
What do you mean by contract?
All the characteristics that are usually described when documenting the Standard Library functions: https://cppreference.com/w/cpp/utility/optional/transform.html
Like: return type, constraints, const/constexpr properties, postconditions. In this case, I was interested in what properties the returned range has: random-access, contiguous? I naturally expect that it is a contiguous range for multi::array and multi::array_ref, so I wanted to confirm that. I suppose it is different for subarrays. I can hardly imagine they would have the same range category.
The search box leads me to: "a flatted view of all the elements rearranged canonically. A.elements()[0] → A[0][0], A.elements()[1] → A[0][1], etc. The type of the result is not a subarray but a special kind of range. Takes no argument."
It takes me to subarray::elements, but that doesn't imply that array::elements would have the same contract. "special kind of range" is not the level of detail that I expected. I think you owe the user the range category.
Regards, &rzej;