[views.span] - C++17 → C++20

Files changed (1) hide show

tmp/tmpwy98bq70/{from.md → to.md} +669 -0

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

	@@ -0,0 +1,669 @@

+### 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 reverse_iterator = std::reverse_iterator<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 reverse_iterator rbegin() const noexcept;
+    constexpr reverse_iterator rend() const noexcept;
+  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>>>;
+}
+```
+`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]]. All requirements
+on container iterators [[container.requirements]] 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.
+<!-- Link reference definitions -->
+[alg.sorting]: algorithms.md#alg.sorting
+[algorithm.stable]: library.md#algorithm.stable
+[algorithms]: algorithms.md#algorithms
+[algorithms.requirements]: algorithms.md#algorithms.requirements
+[allocator.requirements]: library.md#allocator.requirements
+[allocator.requirements.completeness]: library.md#allocator.requirements.completeness
+[allocator.traits.members]: utilities.md#allocator.traits.members
+[array]: #array
+[array.cons]: #array.cons
+[array.creation]: #array.creation
+[array.members]: #array.members
+[array.overview]: #array.overview
+[array.special]: #array.special
+[array.syn]: #array.syn
+[array.tuple]: #array.tuple
+[array.zero]: #array.zero
+[associative]: #associative
+[associative.general]: #associative.general
+[associative.map.syn]: #associative.map.syn
+[associative.reqmts]: #associative.reqmts
+[associative.reqmts.except]: #associative.reqmts.except
+[associative.set.syn]: #associative.set.syn
+[basic.string]: strings.md#basic.string
+[class.copy.ctor]: class.md#class.copy.ctor
+[class.default.ctor]: class.md#class.default.ctor
+[class.dtor]: class.md#class.dtor
+[container.adaptors]: #container.adaptors
+[container.adaptors.general]: #container.adaptors.general
+[container.alloc.req]: #container.alloc.req
+[container.assoc.req]: #container.assoc.req
+[container.hash.req]: #container.hash.req
+[container.insert.return]: #container.insert.return
+[container.node]: #container.node
+[container.node.compat]: #container.node.compat
+[container.node.cons]: #container.node.cons
+[container.node.dtor]: #container.node.dtor
+[container.node.modifiers]: #container.node.modifiers
+[container.node.observers]: #container.node.observers
+[container.node.overview]: #container.node.overview
+[container.opt]: #container.opt
+[container.req]: #container.req
+[container.requirements]: #container.requirements
+[container.requirements.dataraces]: #container.requirements.dataraces
+[container.requirements.general]: #container.requirements.general
+[container.rev.req]: #container.rev.req
+[container.seq.opt]: #container.seq.opt
+[container.seq.req]: #container.seq.req
+[containers]: #containers
+[containers.general]: #containers.general
+[containers.summary]: #containers.summary
+[dcl.init.aggr]: dcl.md#dcl.init.aggr
+[deque]: #deque
+[deque.capacity]: #deque.capacity
+[deque.cons]: #deque.cons
+[deque.erasure]: #deque.erasure
+[deque.modifiers]: #deque.modifiers
+[deque.overview]: #deque.overview
+[deque.syn]: #deque.syn
+[forward.list.erasure]: #forward.list.erasure
+[forward.list.syn]: #forward.list.syn
+[forwardlist]: #forwardlist
+[forwardlist.access]: #forwardlist.access
+[forwardlist.cons]: #forwardlist.cons
+[forwardlist.iter]: #forwardlist.iter
+[forwardlist.modifiers]: #forwardlist.modifiers
+[forwardlist.ops]: #forwardlist.ops
+[forwardlist.overview]: #forwardlist.overview
+[hash.requirements]: library.md#hash.requirements
+[iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
+[iterator.requirements]: iterators.md#iterator.requirements
+[iterator.requirements.general]: iterators.md#iterator.requirements.general
+[list]: #list
+[list.capacity]: #list.capacity
+[list.cons]: #list.cons
+[list.erasure]: #list.erasure
+[list.modifiers]: #list.modifiers
+[list.ops]: #list.ops
+[list.overview]: #list.overview
+[list.syn]: #list.syn
+[map]: #map
+[map.access]: #map.access
+[map.cons]: #map.cons
+[map.erasure]: #map.erasure
+[map.modifiers]: #map.modifiers
+[map.overview]: #map.overview
+[multimap]: #multimap
+[multimap.cons]: #multimap.cons
+[multimap.erasure]: #multimap.erasure
+[multimap.modifiers]: #multimap.modifiers
+[multimap.overview]: #multimap.overview
+[multiset]: #multiset
+[multiset.cons]: #multiset.cons
+[multiset.erasure]: #multiset.erasure
+[multiset.overview]: #multiset.overview
+[priority.queue]: #priority.queue
+[priqueue.cons]: #priqueue.cons
+[priqueue.cons.alloc]: #priqueue.cons.alloc
+[priqueue.members]: #priqueue.members
+[priqueue.overview]: #priqueue.overview
+[priqueue.special]: #priqueue.special
+[queue]: #queue
+[queue.cons]: #queue.cons
+[queue.cons.alloc]: #queue.cons.alloc
+[queue.defn]: #queue.defn
+[queue.ops]: #queue.ops
+[queue.special]: #queue.special
+[queue.syn]: #queue.syn
+[random.access.iterators]: iterators.md#random.access.iterators
+[res.on.data.races]: library.md#res.on.data.races
+[sequence.reqmts]: #sequence.reqmts
+[sequences]: #sequences
+[sequences.general]: #sequences.general
+[set]: #set
+[set.cons]: #set.cons
+[set.erasure]: #set.erasure
+[set.overview]: #set.overview
+[span.cons]: #span.cons
+[span.deduct]: #span.deduct
+[span.elem]: #span.elem
+[span.iterators]: #span.iterators
+[span.objectrep]: #span.objectrep
+[span.obs]: #span.obs
+[span.overview]: #span.overview
+[span.sub]: #span.sub
+[span.syn]: #span.syn
+[stack]: #stack
+[stack.cons]: #stack.cons
+[stack.cons.alloc]: #stack.cons.alloc
+[stack.defn]: #stack.defn
+[stack.ops]: #stack.ops
+[stack.special]: #stack.special
+[stack.syn]: #stack.syn
+[strings]: strings.md#strings
+[swappable.requirements]: library.md#swappable.requirements
+[tab:container.opt]: #tab:container.opt
+[tab:container.req]: #tab:container.req
+[tab:container.rev.req]: #tab:container.rev.req
+[tab:container.seq.opt]: #tab:container.seq.opt
+[tab:container.seq.req]: #tab:container.seq.req
+[temp.deduct]: temp.md#temp.deduct
+[temp.param]: temp.md#temp.param
+[temp.type]: temp.md#temp.type
+[unord]: #unord
+[unord.general]: #unord.general
+[unord.hash]: utilities.md#unord.hash
+[unord.map]: #unord.map
+[unord.map.cnstr]: #unord.map.cnstr
+[unord.map.elem]: #unord.map.elem
+[unord.map.erasure]: #unord.map.erasure
+[unord.map.modifiers]: #unord.map.modifiers
+[unord.map.overview]: #unord.map.overview
+[unord.map.syn]: #unord.map.syn
+[unord.multimap]: #unord.multimap
+[unord.multimap.cnstr]: #unord.multimap.cnstr
+[unord.multimap.erasure]: #unord.multimap.erasure
+[unord.multimap.modifiers]: #unord.multimap.modifiers
+[unord.multimap.overview]: #unord.multimap.overview
+[unord.multiset]: #unord.multiset
+[unord.multiset.cnstr]: #unord.multiset.cnstr
+[unord.multiset.erasure]: #unord.multiset.erasure
+[unord.multiset.overview]: #unord.multiset.overview
+[unord.req]: #unord.req
+[unord.req.except]: #unord.req.except
+[unord.set]: #unord.set
+[unord.set.cnstr]: #unord.set.cnstr
+[unord.set.erasure]: #unord.set.erasure
+[unord.set.overview]: #unord.set.overview
+[unord.set.syn]: #unord.set.syn
+[vector]: #vector
+[vector.bool]: #vector.bool
+[vector.capacity]: #vector.capacity
+[vector.cons]: #vector.cons
+[vector.data]: #vector.data
+[vector.erasure]: #vector.erasure
+[vector.modifiers]: #vector.modifiers
+[vector.overview]: #vector.overview
+[vector.syn]: #vector.syn
+[views]: #views
+[views.general]: #views.general
+[views.span]: #views.span
+[^1]: Equality comparison is a refinement of partitioning if no two
+    objects that compare equal fall into different partitions.
+[^2]: These member functions are only provided by containers whose
+    iterators are random access iterators.
+[^3]: As specified in  [[allocator.requirements]], the requirements in
+    this Clause apply only to lists whose allocators compare equal.
+[^4]: `reserve()` uses `Allocator::allocate()` which may throw an
+    appropriate exception.

Diff to HTML by rtfpessoa