[mdspan.extents] - C++20 → C++23

Files changed (1) hide show

tmp/tmp4kb19jvg/{from.md → to.md} +279 -0

tmp/tmp4kb19jvg/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,279 @@

+#### Class template `extents` <a id="mdspan.extents">[[mdspan.extents]]</a>
+##### Overview <a id="mdspan.extents.overview">[[mdspan.extents.overview]]</a>
+The class template `extents` represents a multidimensional index space
+of rank equal to `sizeof...(Extents)`. In subclause [[views]], `extents`
+is used synonymously with multidimensional index space.
+``` cpp
+namespace std {
+  template<class IndexType, size_t... Extents>
+  class extents {
+  public:
+    using index_type = IndexType;
+    using size_type = make_unsigned_t<index_type>;
+    using rank_type = size_t;
+    // [mdspan.extents.obs], observers of the multidimensional index space
+    static constexpr rank_type rank() noexcept { return sizeof...(Extents); }
+    static constexpr rank_type rank_dynamic() noexcept { return dynamic-index(rank()); }
+    static constexpr size_t static_extent(rank_type) noexcept;
+    constexpr index_type extent(rank_type) const noexcept;
+    // [mdspan.extents.cons], constructors
+    constexpr extents() noexcept = default;
+    template<class OtherIndexType, size_t... OtherExtents>
+      constexpr explicit(see below)
+        extents(const extents<OtherIndexType, OtherExtents...>&) noexcept;
+    template<class... OtherIndexTypes>
+      constexpr explicit extents(OtherIndexTypes...) noexcept;
+    template<class OtherIndexType, size_t N>
+      constexpr explicit(N != rank_dynamic())
+        extents(span<OtherIndexType, N>) noexcept;
+    template<class OtherIndexType, size_t N>
+      constexpr explicit(N != rank_dynamic())
+        extents(const array<OtherIndexType, N>&) noexcept;
+    // [mdspan.extents.cmp], comparison operators
+    template<class OtherIndexType, size_t... OtherExtents>
+      friend constexpr bool operator==(const extents&,
+                                       const extents<OtherIndexType, OtherExtents...>&) noexcept;
+    // [mdspan.extents.expo], exposition-only helpers
+    constexpr size_t fwd-prod-of-extents(rank_type) const noexcept;     // exposition only
+    constexpr size_t rev-prod-of-extents(rank_type) const noexcept;     // exposition only
+    template<class OtherIndexType>
+      static constexpr auto index-cast(OtherIndexType&&) noexcept;      // exposition only
+  private:
+    static constexpr rank_type dynamic-index(rank_type) noexcept;       // exposition only
+    static constexpr rank_type dynamic-index-inv(rank_type) noexcept;   // exposition only
+    array<index_type, rank_dynamic()> dynamic-extents{};                // exposition only
+  };
+  template<class... Integrals>
+    explicit extents(Integrals...)
+      -> see below;
+}
+```
+*Mandates:*
+- `IndexType` is a signed or unsigned integer type, and
+- each element of `Extents` is either equal to `dynamic_extent`, or is
+  representable as a value of type `IndexType`.
+Each specialization of `extents` models `regular` and is trivially
+copyable.
+Let Eᵣ be the rᵗʰ element of `Extents`. Eᵣ is a *dynamic extent* if it
+is equal to `dynamic_extent`, otherwise Eᵣ is a *static extent*. Let Dᵣ
+be the value of `dynamic-extents[dynamic-index(r)]` if Eᵣ is a dynamic
+extent, otherwise Eᵣ.
+The rᵗʰ interval of the multidimensional index space represented by an
+`extents` object is [0, Dᵣ).
+##### Exposition-only helpers <a id="mdspan.extents.expo">[[mdspan.extents.expo]]</a>
+``` cpp
+static constexpr rank_type dynamic-index(rank_type i) noexcept;
+```
+*Preconditions:* `i <= rank()` is `true`.
+*Returns:* The number of Eᵣ with r < `i` for which Eᵣ is a dynamic
+extent.
+``` cpp
+static constexpr rank_type dynamic-index-inv(rank_type i) noexcept;
+```
+*Preconditions:* `i < rank_dynamic()` is `true`.
+*Returns:* The minimum value of r such that
+*`dynamic-index`*`(`r` + 1) == i + 1` is `true`.
+``` cpp
+constexpr size_t fwd-prod-of-extents(rank_type i) const noexcept;
+```
+*Preconditions:* `i <= rank()` is `true`.
+*Returns:* If `i > 0` is `true`, the product of `extent(`k`)` for all k
+in the range [0, `i`), otherwise `1`.
+``` cpp
+constexpr size_t rev-prod-of-extents(rank_type i) const noexcept;
+```
+*Preconditions:* `i < rank()` is `true`.
+*Returns:* If `i + 1 < rank()` is `true`, the product of `extent(`k`)`
+for all k in the range [`i + 1`, `rank()`), otherwise `1`.
+``` cpp
+template<class OtherIndexType>
+  static constexpr auto index-cast(OtherIndexType&& i) noexcept;
+```
+*Effects:*
+- If `OtherIndexType` is an integral type other than `bool`, then
+  equivalent to `return i;`,
+- otherwise, equivalent to `return static_cast<index_type>(i);`.
+[*Note 1*: This function will always return an integral type other than
+`bool`. Since this function’s call sites are constrained on
+convertibility of `OtherIndexType` to `index_type`, integer-class types
+can use the `static_cast` branch without loss of
+precision. — *end note*]
+##### Constructors <a id="mdspan.extents.cons">[[mdspan.extents.cons]]</a>
+``` cpp
+template<class OtherIndexType, size_t... OtherExtents>
+  constexpr explicit(see below)
+    extents(const extents<OtherIndexType, OtherExtents...>& other) noexcept;
+```
+*Constraints:*
+- `sizeof...(OtherExtents) == rank()` is `true`.
+- `((OtherExtents == dynamic_extent || Extents == dynamic_extent || OtherExtents == Extents) && ...)`
+  is `true`.
+*Preconditions:*
+- `other.extent(`r`)` equals Eᵣ for each r for which Eᵣ is a static
+  extent, and
+- either
+  - `sizeof...(OtherExtents)` is zero, or
+  - `other.extent(`r`)` is representable as a value of type `index_type`
+    for every rank index r of `other`.
+*Ensures:* `*this == other` is `true`.
+*Remarks:* The expression inside `explicit` is equivalent to:
+``` cpp
+(((Extents != dynamic_extent) && (OtherExtents == dynamic_extent)) || ... ) ||
+(numeric_limits<index_type>::max() < numeric_limits<OtherIndexType>::max())
+```
+``` cpp
+template<class... OtherIndexTypes>
+  constexpr explicit extents(OtherIndexTypes... exts) noexcept;
+```
+Let `N` be `sizeof...(OtherIndexTypes)`, and let `exts_arr` be
+`array<index_type, N>{static_cast<`
+`index_type>(std::move(exts))...}`.
+*Constraints:*
+- `(is_convertible_v<OtherIndexTypes, index_type> && ...)` is `true`,
+- `(is_nothrow_constructible_v<index_type, OtherIndexTypes> && ...)` is
+  `true`, and
+- `N == rank_dynamic() || N == rank()` is `true`. \[*Note 1*: One can
+  construct `extents` from just dynamic extents, which are all the
+  values getting stored, or from all the extents with a
+  precondition. — *end note*]
+*Preconditions:*
+- If `N != rank_dynamic()` is `true`, `exts_arr[`r`]` equals Eᵣ for each
+  r for which Eᵣ is a static extent, and
+- either
+  - `sizeof...(exts) == 0` is `true`, or
+  - each element of `exts` is nonnegative and is representable as a
+    value of type `index_type`.
+*Ensures:* `*this == extents(exts_arr)` is `true`.
+``` cpp
+template<class OtherIndexType, size_t N>
+  constexpr explicit(N != rank_dynamic())
+    extents(span<OtherIndexType, N> exts) noexcept;
+template<class OtherIndexType, size_t N>
+  constexpr explicit(N != rank_dynamic())
+    extents(const array<OtherIndexType, N>& exts) noexcept;
+```
+*Constraints:*
+- `is_convertible_v<const OtherIndexType&, index_type>` is `true`,
+- `is_nothrow_constructible_v<index_type, const OtherIndexType&>` is
+  `true`, and
+- `N == rank_dynamic() || N == rank()` is `true`.
+*Preconditions:*
+- If `N != rank_dynamic()` is `true`, `exts[`r`]` equals Eᵣ for each r
+  for which Eᵣ is a static extent, and
+- either
+  - `N` is zero, or
+  - `exts[`r`]` is nonnegative and is representable as a value of type
+    `index_type` for every rank index r.
+*Effects:*
+- If `N` equals `dynamic_rank()`, for all d in the range
+  [0, `rank_dynamic()`), direct-non-list-initializes
+  *`dynamic-extents`*`[`d`]` with `as_const(exts[`d`])`.
+- Otherwise, for all d in the range [0, `rank_dynamic()`),
+  direct-non-list-initializes *`dynamic-extents`*`[`d`]` with
+  `as_const(exts[`*`dynamic-index-inv`*`(`d`)])`.
+``` cpp
+template<class... Integrals>
+  explicit extents(Integrals...) -> see below;
+```
+*Constraints:* `(is_convertible_v<Integrals, size_t> && ...)` is `true`.
+*Remarks:* The deduced type is `dextents<size_t, sizeof...(Integrals)>`.
+##### Observers of the multidimensional index space <a id="mdspan.extents.obs">[[mdspan.extents.obs]]</a>
+``` cpp
+static constexpr size_t static_extent(rank_type i) noexcept;
+```
+*Preconditions:* `i < rank()` is `true`.
+*Returns:* E_`i`.
+``` cpp
+constexpr index_type extent(rank_type i) const noexcept;
+```
+*Preconditions:* `i < rank()` is `true`.
+*Returns:* D_`i`.
+##### Comparison operators <a id="mdspan.extents.cmp">[[mdspan.extents.cmp]]</a>
+``` cpp
+template<class OtherIndexType, size_t... OtherExtents>
+  friend constexpr bool operator==(const extents& lhs,
+                                   const extents<OtherIndexType, OtherExtents...>& rhs) noexcept;
+```
+*Returns:* `true` if `lhs.rank()` equals `rhs.rank()` and if
+`lhs.extent(r)` equals `rhs.extent(r)` for every rank index `r` of
+`rhs`, otherwise `false`.
+##### Alias template `dextents` <a id="mdspan.extents.dextents">[[mdspan.extents.dextents]]</a>
+``` cpp
+template<class IndexType, size_t Rank>
+  using dextents = see below;
+```
+*Result:* A type `E` that is a specialization of `extents` such that
+`E::rank() == Rank && E::rank() == E::rank_dynamic()` is `true`, and
+`E::index_type` denotes `IndexType`.

Diff to HTML by rtfpessoa