[views.contiguous] - C++20 → C++23

Files changed (1) hide show

tmp/tmphim1yn76/{from.md → to.md} +516 -0

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

	@@ -0,0 +1,516 @@

+### Contiguous access <a id="views.contiguous">[[views.contiguous]]</a>
+#### Header `<span>` synopsis <a id="span.syn">[[span.syn]]</a>
+``` cpp
+namespace std {
+  // constants
+  inline constexpr size_t dynamic_extent = numeric_limits<size_t>::max();
+  // [views.span], class template span
+  template<class ElementType, size_t Extent = dynamic_extent>
+    class span;
+  template<class ElementType, size_t Extent>
+    constexpr bool ranges::enable_view<span<ElementType, Extent>> = true;
+  template<class ElementType, size_t Extent>
+    constexpr bool ranges::enable_borrowed_range<span<ElementType, Extent>> = true;
+  // [span.objectrep], views of object representation
+  template<class ElementType, size_t Extent>
+    span<const byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
+      as_bytes(span<ElementType, Extent> s) noexcept;
+  template<class ElementType, size_t Extent>
+    span<byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
+      as_writable_bytes(span<ElementType, Extent> s) noexcept;
+}
+```
+#### Class template `span` <a id="views.span">[[views.span]]</a>
+##### Overview <a id="span.overview">[[span.overview]]</a>
+A `span` is a view over a contiguous sequence of objects, the storage of
+which is owned by some other object.
+All member functions of `span` have constant time complexity.
+``` cpp
+namespace std {
+  template<class ElementType, size_t Extent = dynamic_extent>
+  class span {
+  public:
+    // constants and types
+    using element_type = ElementType;
+    using value_type = remove_cv_t<ElementType>;
+    using size_type = size_t;
+    using difference_type = ptrdiff_t;
+    using pointer = element_type*;
+    using const_pointer = const element_type*;
+    using reference = element_type&;
+    using const_reference = const element_type&;
+    using iterator = implementation-defined  // type of span::iterator;        // see [span.iterators]
+    using const_iterator = std::const_iterator<iterator>;
+    using reverse_iterator = std::reverse_iterator<iterator>;
+    using const_reverse_iterator = std::const_iterator<reverse_iterator>;
+    static constexpr size_type extent = Extent;
+    // [span.cons], constructors, copy, and assignment
+    constexpr span() noexcept;
+    template<class It>
+      constexpr explicit(extent != dynamic_extent) span(It first, size_type count);
+    template<class It, class End>
+      constexpr explicit(extent != dynamic_extent) span(It first, End last);
+    template<size_t N>
+      constexpr span(type_identity_t<element_type> (&arr)[N]) noexcept;
+    template<class T, size_t N>
+      constexpr span(array<T, N>& arr) noexcept;
+    template<class T, size_t N>
+      constexpr span(const array<T, N>& arr) noexcept;
+    template<class R>
+      constexpr explicit(extent != dynamic_extent) span(R&& r);
+    constexpr span(const span& other) noexcept = default;
+    template<class OtherElementType, size_t OtherExtent>
+      constexpr explicit(see below) span(const span<OtherElementType, OtherExtent>& s) noexcept;
+    ~span() noexcept = default;
+    constexpr span& operator=(const span& other) noexcept = default;
+    // [span.sub], subviews
+    template<size_t Count>
+      constexpr span<element_type, Count> first() const;
+    template<size_t Count>
+      constexpr span<element_type, Count> last() const;
+    template<size_t Offset, size_t Count = dynamic_extent>
+      constexpr span<element_type, see below> subspan() const;
+    constexpr span<element_type, dynamic_extent> first(size_type count) const;
+    constexpr span<element_type, dynamic_extent> last(size_type count) const;
+    constexpr span<element_type, dynamic_extent> subspan(
+      size_type offset, size_type count = dynamic_extent) const;
+    // [span.obs], observers
+    constexpr size_type size() const noexcept;
+    constexpr size_type size_bytes() const noexcept;
+    [[nodiscard]] constexpr bool empty() const noexcept;
+    // [span.elem], element access
+    constexpr reference operator[](size_type idx) const;
+    constexpr reference front() const;
+    constexpr reference back() const;
+    constexpr pointer data() const noexcept;
+    // [span.iterators], iterator support
+    constexpr iterator begin() const noexcept;
+    constexpr iterator end() const noexcept;
+    constexpr const_iterator cbegin() const noexcept { return begin(); }
+    constexpr const_iterator cend() const noexcept { return end(); }
+    constexpr reverse_iterator rbegin() const noexcept;
+    constexpr reverse_iterator rend() const noexcept;
+    constexpr const_reverse_iterator crbegin() const noexcept { return rbegin(); }
+    constexpr const_reverse_iterator crend() const noexcept { return rend(); }
+  private:
+    pointer data_;              // exposition only
+    size_type size_;            // exposition only
+  };
+  template<class It, class EndOrSize>
+    span(It, EndOrSize) -> span<remove_reference_t<iter_reference_t<It>>>;
+  template<class T, size_t N>
+    span(T (&)[N]) -> span<T, N>;
+  template<class T, size_t N>
+    span(array<T, N>&) -> span<T, N>;
+  template<class T, size_t N>
+    span(const array<T, N>&) -> span<const T, N>;
+  template<class R>
+    span(R&&) -> span<remove_reference_t<ranges::range_reference_t<R>>>;
+}
+```
+`span<ElementType, Extent>` is a trivially copyable type
+[[term.trivially.copyable.type]].
+`ElementType` is required to be a complete object type that is not an
+abstract class type.
+##### Constructors, copy, and assignment <a id="span.cons">[[span.cons]]</a>
+``` cpp
+constexpr span() noexcept;
+```
+*Constraints:* `Extent == dynamic_extent || Extent == 0` is `true`.
+*Ensures:* `size() == 0 && data() == nullptr`.
+``` cpp
+template<class It>
+  constexpr explicit(extent != dynamic_extent) span(It first, size_type count);
+```
+*Constraints:* Let `U` be `remove_reference_t<iter_reference_t<It>>`.
+- `It` satisfies `contiguous_iterator`.
+- `is_convertible_v<U(*)[], element_type(*)[]>` is `true`.
+  \[*Note 1*: The intent is to allow only qualification conversions of
+  the iterator reference type to `element_type`. — *end note*]
+*Preconditions:*
+- \[`first`, `first + count`) is a valid range.
+- `It` models `contiguous_iterator`.
+- If `extent` is not equal to `dynamic_extent`, then `count` is equal to
+  `extent`.
+*Effects:* Initializes *`data_`* with `to_address(first)` and *`size_`*
+with `count`.
+*Throws:* Nothing.
+``` cpp
+template<class It, class End>
+  constexpr explicit(extent != dynamic_extent) span(It first, End last);
+```
+*Constraints:* Let `U` be `remove_reference_t<iter_reference_t<It>>`.
+- `is_convertible_v<U(*)[], element_type(*)[]>` is `true`.
+  \[*Note 2*: The intent is to allow only qualification conversions of
+  the iterator reference type to `element_type`. — *end note*]
+- `It` satisfies `contiguous_iterator`.
+- `End` satisfies `sized_sentinel_for<It>`.
+- `is_convertible_v<End, size_t>` is `false`.
+*Preconditions:*
+- If `extent` is not equal to `dynamic_extent`, then `last - first` is
+  equal to `extent`.
+- \[`first`, `last`) is a valid range.
+- `It` models `contiguous_iterator`.
+- `End` models `sized_sentinel_for<It>`.
+*Effects:* Initializes *`data_`* with `to_address(first)` and *`size_`*
+with `last - first`.
+*Throws:* When and what `last - first` throws.
+``` cpp
+template<size_t N> constexpr span(type_identity_t<element_type> (&arr)[N]) noexcept;
+template<class T, size_t N> constexpr span(array<T, N>& arr) noexcept;
+template<class T, size_t N> constexpr span(const array<T, N>& arr) noexcept;
+```
+*Constraints:* Let `U` be `remove_pointer_t<decltype(data(arr))>`.
+- `extent == dynamic_extent || N == extent` is `true`, and
+- `is_convertible_v<U(*)[], element_type(*)[]>` is `true`.
+  \[*Note 3*: The intent is to allow only qualification conversions of
+  the array element type to `element_type`. — *end note*]
+*Effects:* Constructs a `span` that is a view over the supplied array.
+[*Note 1*: `type_identity_t` affects class template argument
+deduction. — *end note*]
+*Ensures:* `size() == N && data() == data(arr)` is `true`.
+``` cpp
+template<class R> constexpr explicit(extent != dynamic_extent) span(R&& r);
+```
+*Constraints:* Let `U` be
+`remove_reference_t<ranges::range_reference_t<R>>`.
+- `R` satisfies `ranges::contiguous_range` and `ranges::sized_range`.
+- Either `R` satisfies `ranges::borrowed_range` or
+  `is_const_v<element_type>` is `true`.
+- `remove_cvref_t<R>` is not a specialization of `span`.
+- `remove_cvref_t<R>` is not a specialization of `array`.
+- `is_array_v<remove_cvref_t<R>>` is `false`.
+- `is_convertible_v<U(*)[], element_type(*)[]>` is `true`.
+  \[*Note 4*: The intent is to allow only qualification conversions of
+  the range reference type to `element_type`. — *end note*]
+*Preconditions:*
+- If `extent` is not equal to `dynamic_extent`, then `ranges::size(r)`
+  is equal to `extent`.
+- `R` models `ranges::contiguous_range` and `ranges::sized_range`.
+- If `is_const_v<element_type>` is `false`, `R` models
+  `ranges::borrowed_range`.
+*Effects:* Initializes *`data_`* with `ranges::data(r)` and *`size_`*
+with `ranges::size(r)`.
+*Throws:* What and when `ranges::data(r)` and `ranges::size(r)` throw.
+``` cpp
+constexpr span(const span& other) noexcept = default;
+```
+*Ensures:* `other.size() == size() && other.data() == data()`.
+``` cpp
+template<class OtherElementType, size_t OtherExtent>
+  constexpr explicit(see below) span(const span<OtherElementType, OtherExtent>& s) noexcept;
+```
+*Constraints:*
+- `extent == dynamic_extent` `||` `OtherExtent == dynamic_extent` `||`
+  `extent == OtherExtent` is `true`, and
+- `is_convertible_v<OtherElementType(*)[], element_type(*)[]>` is
+  `true`. \[*Note 5*: The intent is to allow only qualification
+  conversions of the `OtherElementType` to
+  `element_type`. — *end note*]
+*Preconditions:* If `extent` is not equal to `dynamic_extent`, then
+`s.size()` is equal to `extent`.
+*Effects:* Constructs a `span` that is a view over the range
+\[`s.data()`, `s.data() + s.size()`).
+*Ensures:* `size() == s.size() && data() == s.data()`.
+*Remarks:* The expression inside `explicit` is equivalent to:
+``` cpp
+extent != dynamic_extent && OtherExtent == dynamic_extent
+```
+``` cpp
+constexpr span& operator=(const span& other) noexcept = default;
+```
+*Ensures:* `size() == other.size() && data() == other.data()`.
+##### Deduction guides <a id="span.deduct">[[span.deduct]]</a>
+``` cpp
+template<class It, class EndOrSize>
+  span(It, EndOrSize) -> span<remove_reference_t<iter_reference_t<It>>>;
+```
+*Constraints:* `It` satisfies `contiguous_iterator`.
+``` cpp
+template<class R>
+  span(R&&) -> span<remove_reference_t<ranges::range_reference_t<R>>>;
+```
+*Constraints:* `R` satisfies `ranges::contiguous_range`.
+##### Subviews <a id="span.sub">[[span.sub]]</a>
+``` cpp
+template<size_t Count> constexpr span<element_type, Count> first() const;
+```
+*Mandates:* `Count <= Extent` is `true`.
+*Preconditions:* `Count <= size()` is `true`.
+*Effects:* Equivalent to: `return R{data(), Count};` where `R` is the
+return type.
+``` cpp
+template<size_t Count> constexpr span<element_type, Count> last() const;
+```
+*Mandates:* `Count <= Extent` is `true`.
+*Preconditions:* `Count <= size()` is `true`.
+*Effects:* Equivalent to: `return R{data() + (size() - Count), Count};`
+where `R` is the return type.
+``` cpp
+template<size_t Offset, size_t Count = dynamic_extent>
+  constexpr span<element_type, see below> subspan() const;
+```
+*Mandates:*
+``` cpp
+Offset <= Extent && (Count == dynamic_extent || Count <= Extent - Offset)
+```
+is `true`.
+*Preconditions:*
+``` cpp
+Offset <= size() && (Count == dynamic_extent || Count <= size() - Offset)
+```
+is `true`.
+*Effects:* Equivalent to:
+``` cpp
+return span<ElementType, see below>(
+  data() + Offset, Count != dynamic_extent ? Count : size() - Offset);
+```
+*Remarks:* The second template argument of the returned `span` type is:
+``` cpp
+Count != dynamic_extent ? Count
+                        : (Extent != dynamic_extent ? Extent - Offset
+                                                    : dynamic_extent)
+```
+``` cpp
+constexpr span<element_type, dynamic_extent> first(size_type count) const;
+```
+*Preconditions:* `count <= size()` is `true`.
+*Effects:* Equivalent to: `return {data(), count};`
+``` cpp
+constexpr span<element_type, dynamic_extent> last(size_type count) const;
+```
+*Preconditions:* `count <= size()` is `true`.
+*Effects:* Equivalent to: `return {data() + (size() - count), count};`
+``` cpp
+constexpr span<element_type, dynamic_extent> subspan(
+  size_type offset, size_type count = dynamic_extent) const;
+```
+*Preconditions:*
+``` cpp
+offset <= size() && (count == dynamic_extent || count <= size() - offset)
+```
+is `true`.
+*Effects:* Equivalent to:
+``` cpp
+return {data() + offset, count == dynamic_extent ? size() - offset : count};
+```
+##### Observers <a id="span.obs">[[span.obs]]</a>
+``` cpp
+constexpr size_type size() const noexcept;
+```
+*Effects:* Equivalent to: `return `*`size_`*`;`
+``` cpp
+constexpr size_type size_bytes() const noexcept;
+```
+*Effects:* Equivalent to: `return size() * sizeof(element_type);`
+``` cpp
+[[nodiscard]] constexpr bool empty() const noexcept;
+```
+*Effects:* Equivalent to: `return size() == 0;`
+##### Element access <a id="span.elem">[[span.elem]]</a>
+``` cpp
+constexpr reference operator[](size_type idx) const;
+```
+*Preconditions:* `idx < size()` is `true`.
+*Effects:* Equivalent to: `return *(data() + idx);`
+``` cpp
+constexpr reference front() const;
+```
+*Preconditions:* `empty()` is `false`.
+*Effects:* Equivalent to: `return *data();`
+``` cpp
+constexpr reference back() const;
+```
+*Preconditions:* `empty()` is `false`.
+*Effects:* Equivalent to: `return *(data() + (size() - 1));`
+``` cpp
+constexpr pointer data() const noexcept;
+```
+*Effects:* Equivalent to: `return `*`data_`*`;`
+##### Iterator support <a id="span.iterators">[[span.iterators]]</a>
+``` cpp
+using iterator = implementation-defined  // type of span::iterator;
+```
+The type models `contiguous_iterator` [[iterator.concept.contiguous]],
+meets the *Cpp17RandomAccessIterator*
+requirements [[random.access.iterators]], and meets the requirements for
+constexpr iterators [[iterator.requirements.general]], whose value type
+is `value_type` and whose reference type is `reference`.
+All requirements on container iterators [[container.reqmts]] apply to
+`span::iterator` as well.
+``` cpp
+constexpr iterator begin() const noexcept;
+```
+*Returns:* An iterator referring to the first element in the span. If
+`empty()` is `true`, then it returns the same value as `end()`.
+``` cpp
+constexpr iterator end() const noexcept;
+```
+*Returns:* An iterator which is the past-the-end value.
+``` cpp
+constexpr reverse_iterator rbegin() const noexcept;
+```
+*Effects:* Equivalent to: `return reverse_iterator(end());`
+``` cpp
+constexpr reverse_iterator rend() const noexcept;
+```
+*Effects:* Equivalent to: `return reverse_iterator(begin());`
+#### Views of object representation <a id="span.objectrep">[[span.objectrep]]</a>
+``` cpp
+template<class ElementType, size_t Extent>
+  span<const byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
+    as_bytes(span<ElementType, Extent> s) noexcept;
+```
+*Effects:* Equivalent to:
+`return R{reinterpret_cast<const byte*>(s.data()), s.size_bytes()};`
+where `R` is the return type.
+``` cpp
+template<class ElementType, size_t Extent>
+  span<byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
+    as_writable_bytes(span<ElementType, Extent> s) noexcept;
+```
+*Constraints:* `is_const_v<ElementType>` is `false`.
+*Effects:* Equivalent to:
+`return R{reinterpret_cast<byte*>(s.data()), s.size_bytes()};` where `R`
+is the return type.

Diff to HTML by rtfpessoa