Update span-class.md

* Suggestion: mention built-in arrays, `std::array`, and `std::vector` as examples of contiguous storage. May be helpful for readers who don't immediately recognize "contiguous" or "back-to-back". Feel free to discard.
* "indexed by the size of the objects" is unclear - it's talking about indexing from `[0, N)` but at first it sounds like it might be talking about `sizeof(Object)`. Suggestion: simply say "using a pointer and an index".
* "part of the template declaration" isn't the right terminology. The Standard Library contains the declaration (and definition) of `std::span`. The user provides template arguments to `span` when they say `span<int, 5>`.
* `dynamic-size` is nonexistent; replace with `dynamic_extent`.
* Suggestion: Rephrase the descriptions of `const_pointer` and `const_reference` to make it clear where the constness applies.
* FIXME: `operator[]` is mentioned in the table twice, as an accessor and an operator. I added a FIXME note but don't know how to resolve this.
* Monospace `array` and `vector`.
* Replace a smart quote with a plain quote.
* Mention `/std:c++latest` as a requirement.
* Add FIXME notes to examples (didn't attempt to fix all examples)
* Missing semicolon in the declaration of `begin()`.
* `data()` said: "If the span is empty, returns `nullptr`." This is incorrect, so I've removed the sentence. The truth is complicated: a default-constructed span indeed has null `data` and zero `size`. However, it's possible for an empty (zero `size`) span to have non-null `data`; this can be manually constructed, or obtained from `subspan`. This seems weird, but it can be meaningful to have a span denoting a location but zero elements. For example, the `equal_range` algorithm returns a sub-range of equivalent elements in a range; if there are no such elements, it returns an empty subrange located where such elements could be inserted while preserving the ordering. I am unsure how to explain this behavior of `data` briefly. 
* Removed apparently-spurious `difference_type` link right before that section; apologies if I misunderstood what was happening there.
* Fixed typoed and incorrect `difference_type` example - it was subtracting the `int` elements. Instead, `difference_type` is the result of subtracting iterators. Attempted to correct example; haven't actually verified that this compiles (modulo std/void issues).
* Added missing semicolon to `empty` declaration.
* Added missing `noexcept` to `end` declaration (present for `begin`).
* NO CHANGE MADE: `end` talks about "the sentinel" but I am unsure whether this is good terminology. I usually speak of a sentinel node in node-based containers (because such a node physically exists), but for contiguous containers like `vector`, I speak of a "past-the-end location". This is possibly more important for `span` because `span` isn't placing anything special there.
* Remove top-level `const` from `first(size_type count)`'s parameter - this has meaning only to implementers, not to callers.
* Fix `front` example which was calling `first`.
* Don't specify `iterator` as `_Span_iterator<T>`, which is an STL-internal type. I've replaced this with `implementation-defined-iterator-type` (the Standard just says `implementation-defined`).
* Remove `const` from `operator[]`'s parameter. Mark the member function as `const`. Add a semicolon.
* Remove unused (copy-pasted?) `auto i` variable from `operator[]` example.
* FIXME NOTE: The `operator=` example depicts copy-initialization, not copy assignment. Just noted, haven't fixed.
* FIXME NOTE: Also commented for-loop in that example
* Add `noexcept` to `rend` (already present on `rbegin`).
* Replaced incorrect `size_type` description.
* Fixed misleading `size_type` example - it is meant to be used with `size` calculations, not `sizeof` (although it is ultimately `size_t`, the same type).
* FIXME NOTE: `dynamicExtent` in span constructors should be `dynamic_extent`; noted but not fixed.
* ASK CASEY: The `requires` depicted for the `span()` default ctor appears to be incorrectly positioned but I don't really understand concept syntax yet.
* Fix `template <It>` and `template <It, End>` which are not valid syntax.
* Fix `span(It first, End last)` description - it referred to `end` but the variable's name is `last`.
* FIXME: The `subspan` signature had a missing part of a conditional expression; noted as FIXME.
* `subspan` `count` was described as "from the end this span" which is damaged and appears to be copy-pasted from `last`. I believe removing this fixes the description.
* `subspan` `count` also said "If span is `dynamic_extent`" which was a typo; fixed.
* FIXME NOTE: The example prints `subspan<1>` but calls `subspan(1)`. It's unclear to me whether you meant to depict both the 1-function-argument and 1-template-argument forms.
* Removed duplicated `subspan` signature.
* NOT FIXED: `subspan` has a declaration repeatedly mentioning `size_t`. All occurrences of `size_t` in this page should be audited to see whether they should be `size_type` (likely).
* Deduction guides mentioned the STL-internal macro `_RANGES`; replaced with `ranges::` as `std::` appears to be assumed here.

Author: StephanTLavavej

docs/standard-library/span-class.md

@@ -8,11 +8,11 @@ helpviewer_keywords: ["std::span [C++]", "std::span [C++], const_iterator", "std
 ---
 # span Class (C++ Standard Library)
 
-Provides a lightweight view over a contiguous sequence of objects. A span provides a safe way to iterate over, and index into, objects that are arranged back-to-back in memory.
+Provides a lightweight view over a contiguous sequence of objects. A span provides a safe way to iterate over, and index into, objects that are arranged back-to-back in memory (for example, objects stored in a built-in array, `std::array`, or `std::vector`).
 
-If you typically access a sequence of back-to-back objects using a pointer indexed by the size of the objects, span is a safer, lightweight alternative.
+If you typically access a sequence of back-to-back objects using a pointer and an index, span is a safer, lightweight alternative.
 
-A span's size is determined at compile time by specifying it as part of the template declaration, or at runtime by specifying `dynamic-size`.
+A span's size is determined at compile time by specifying it as a template argument, or at runtime by specifying `dynamic_extent`.
 
 ## Syntax
 
@@ -34,8 +34,8 @@ class span;
 
 | **Type Definitions** | **Description** |
 |-|-|
-| [const_pointer](#pointer) | The type of a const pointer to a span element. |
-| [const_reference](#reference) | The type of a const reference to an element. |
+| [const_pointer](#pointer) | The type of a pointer to a `const` element. |
+| [const_reference](#reference) | The type of a reference to a `const` element. |
 | [difference_type](#difference_type) | The type of a signed distance between two elements. |
 | [element_type](#element_type) | The type of a span element. |
 | [iterator](#iterator) | The type of an iterator for a span. |
@@ -66,20 +66,22 @@ class span;
 | [subspan](#sub_view) | Gets a subspan from anywhere in the span.|
 | **Operators** | **Description** |
 |[span::operator=](#op_eq)| Replaces the span.|
-|[span::operator\[\]](#op_at)| Access an element at a specified position.|
+|[span::operator\[\]](#op_at)| Access an element at a specified position. (FIXME: MENTIONED TWICE?) |
 
 ## Remarks
 
 All `span` member functions have constant time complexity.
 
-Unlike array or vector, a span doesn't "own” the elements inside it. A span doesn't free any storage for the items inside it because it doesn't own the storage for those objects.
+Unlike `array` or `vector`, a span doesn't "own" the elements inside it. A span doesn't free any storage for the items inside it because it doesn't own the storage for those objects.
 
 ## Requirements
 
 **Header:** \<span>
 
 **Namespace:** std
 
+**Compiler Option:** /std:c++latest
+
 ## <a name="back"></a> `span::back`
 
 Returns the last element in the span.
@@ -97,11 +99,12 @@ A reference to the last element in the span.
 ```cpp
 #include <span>
 #include <iostream>
+using namespace std; // FIXME: Lack of qualification occurs in many examples below; need using or std::
 
-void main()
+int main() // FIXME: void main() occurs in many examples below
 {
     int a[] = { 0,1,2 };
-    span <int> mySpan(a);
+    span<int> mySpan(a); // FIXME, STYLE: span <int> with an unnecessary space occurs in many examples below
 
     cout << mySpan.back();
 }
@@ -116,7 +119,7 @@ void main()
 Returns an iterator pointing at the first element in the span.
 
 ```cpp
-constexpr iterator begin() const noexcept
+constexpr iterator begin() const noexcept;
 ```
 
 ### Return value
@@ -153,7 +156,7 @@ constexpr pointer data() const noexcept;
 
 ### Return Value
 
-A pointer to the first item stored in the span. If the span is empty, returns `nullptr`.
+A pointer to the first item stored in the span.
 
 ### Example
 
@@ -174,7 +177,6 @@ void main()
 0
 ```
 
-[difference_type](#difference_type)
 ## <a name="difference_type"></a> `span::difference_type`
 
 This type represents the number of elements between two elements in a span.
@@ -194,13 +196,13 @@ void main()
     int a[] = { 0,1,2 };
     span <int> mySpan(a);
 
-    pan<int>::difference_type distance = mySpan[2] - mySpan[0];
+    span<int>::difference_type distance = mySpan.end() - mySpan.begin();
     cout << distance << std::endl;
 }
 ```
 
 ```Output
-2
+3
 ```
 
 ## <a name="element_type"></a> `span::element_type`
@@ -241,7 +243,7 @@ void main()
 Whether the span contains elements.
 
 ```cpp
-constexpr bool empty() const noexcept
+constexpr bool empty() const noexcept;
 ```
 
 ### Return Value
@@ -267,7 +269,7 @@ void main()
 Returns an iterator to the end of the span.
 
 ```cpp
-constexpr iterator end() const;
+constexpr iterator end() const noexcept;
 ```
 
 ### Return Value
@@ -295,7 +297,7 @@ for (auto it = s1.begin(); it != s1.end(); ++it)
 Get a subspan, taken from the front of this span.
 
 ```cpp
-constexpr auto first(const size_type count) const noexcept;
+constexpr auto first(size_type count) const noexcept;
 template <size_t count> constexpr auto first() const noexcept;
 ```
 
@@ -368,7 +370,7 @@ void main()
     int a[] = { 0,1,2 };
     span <int> mySpan(a);
 
-    auto i = mySpan.first();
+    auto i = mySpan.front();
     cout << i;
 }
 ```
@@ -382,7 +384,7 @@ void main()
 The type of an iterator over span elements.
 
 ```cpp
-using iterator = _Span_iterator<T>;
+using iterator = implementation-defined-iterator-type;
 ```
 
 ### Remarks
@@ -469,7 +471,7 @@ mySpan.last<2>: 12
 Access an element in the span at a specified position.
 
 ```cpp
-constexpr reference operator[](const size_type offset)
+constexpr reference operator[](size_type offset) const;
 ```
 
 ### Parameters
@@ -491,7 +493,6 @@ void main()
 {
     int a[] = { 0,1,2 };
     span <int> mySpan(a);
-    auto i = mySpan.begin();
     cout << mySpan[1];
 }
 ```
@@ -531,9 +532,9 @@ void main()
 {
     int a[] = { 0,1,2 };
     span <int> mySpan(a);
-    span <int> mySpan2 = mySpan;
-    for (auto it : mySpan2)
-    {
+    span <int> mySpan2 = mySpan; // FIXME: This is a copy-initialization, not a copy assignment
+    for (auto it : mySpan2) // FIXME: Range-for iterates over elements, not iterators. This will compile and work,
+    { // FIXME: but "it" is misleadingly named (and copied). Should be "auto& i : mySpan2" like other examples.
         cout << it;
     }
 }
@@ -653,7 +654,7 @@ void main()
 Get a random-access iterator to the sentinel just beyond the end of the reversed span.
 
 ```cpp
-constexpr reverse_iterator rend() const;
+constexpr reverse_iterator rend() const noexcept;
 ```
 
 ### Return Value
@@ -774,7 +775,7 @@ void main()
 
 ## <a name="size_type"></a> `span::size_type`
 
-The size of the type of an element in the span.
+An unsigned type, suitable for storing the number of elements in a span.
 
 ```cpp
 using size_type = size_t;
@@ -791,28 +792,29 @@ void main()
     int a[] = { 0,1,2 };
     span <int> mySpan(a);
 
-    span<int>::size_type szType = sizeof(mySpan[0]);
+    span<int>::size_type szType = mySpan.size();
     cout << szType;
 }
 ```
 
 ```Output
-4
+3
 ```
 
 ## <a name="span"></a> `span::span`
 
 `span` constructors.
 
 ```cpp
+// FIXME: dynamicExtent should be dynamic_extent below, repeatedly
 constexpr span() noexcept
 requires (Extent == 0 || Extent == dynamicExtent) = default;
 
-template <It>
+template <class It>
 constexpr explicit(Extent != dynamicExtent)
 span(It first, size_type count) noexcept
 
-template <It, End>
+template <class It, class End>
 constexpr explicit(Extent != dynamicExtent)
 span(It first, End last) noexcept(noexcept(last - first))
 
@@ -874,7 +876,7 @@ A span doesn't free storage for items in the span because it doesn't own the sto
 |---------|---------|
 |`span()` | Constructs an empty span. Only considered during overload resolution when the template parameter `Extent` is `0` or `dynamic_extent`.|
 |`span(It first, size_type count)` | Constructs a span from the first `count` elements from iterator `first`.  Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. |
-|`span(It first, End last)` | Constructs a span from the elements in iterator `first` until the sentinel `end` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a `contiguous_iterator`.  |
+|`span(It first, End last)` | Constructs a span from the elements in iterator `first` until the sentinel `last` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a `contiguous_iterator`.  |
 |`span(array<T, N>& arr) noexcept;`<br /><br />`span(const array<T, N>& arr) noexcept;`<br /><br />`span(type_identity_t<element_type> (&arr)[N]) noexcept;` |  Constructs a span from `N` elements of the specified array. Only considered during overload resolution when template parameter `Extent` is `dynamic_extent` or equals `N`. |
 |`span(R&& r)` |  Constructs a span from a range. Only participates in overload resolution if template parameter `Extent` isn't `dynamic_extent`.|
 |`span(const span& other)` |  The compiler-generated copy constructor. A shallow copy of the data pointer is safe because the span doesn't allocate the memory to hold the elements. |
@@ -910,21 +912,18 @@ Gets a subspan from this span.
 
 ```cpp
 constexpr span<element_type, dynamic_extent>
-subspan(size_t offset, size_t count = dynamic_extent) const noexcept;
-
-constexpr span<element_type, dynamic_extent>
-subspan(const size_type offset, const size_type count = dynamic_extent) const noexcept;
+subspan(size_type offset, size_type count = dynamic_extent) const noexcept;
 
 template <size_t offset, size_t count = dynamic_extent>
 constexpr span<element_type,
-        count != dynamic_extent ? count : (Extent != dynamic_extent ? Extent - _Offset : )>
+        count != dynamic_extent ? count : (Extent != dynamic_extent ? Extent - _Offset : FIXME)>
         subspan() const noexcept
 ```
 
 ### Parameters
 
 *count*\
-The number of elements from the end this span to put in the subspan. If span is `dynamic_extent` (the default value), then gets the elements from `offset` to the end of this span.
+The number of elements to put in the subspan. If `count` is `dynamic_extent` (the default value), then gets the elements from `offset` to the end of this span.
 
 *offset*\
 The location in this span to start the subspan.
@@ -958,7 +957,7 @@ void main()
     {
         cout << i;
     }
-    cout << "\nmySpan.subspan<1>: ";
+    cout << "\nmySpan.subspan<1>: "; // FIXME: Doesn't match actual call
     for (auto& i : mySpan.subspan(1))
     {
         cout << i;
@@ -1025,11 +1024,11 @@ span(It, End) -> span<remove_reference_t<iter_reference_t<It>>>;
 // Allows the element type to be deduced from a range.
 // The range must be contiguous
 
-template <_RANGES contiguous_range Rng>
-span(Rng &&) -> span<remove_reference_t<_RANGES range_reference_t<Rng>>>;
+template <ranges::contiguous_range Rng>
+span(Rng &&) -> span<remove_reference_t<ranges::range_reference_t<Rng>>>;
 ```
 
 ## See also
 
 [\<span>](../standard-library/span.md)  
-[How to use class template argument deduction](https://devblogs.microsoft.com/cppblog/how-to-use-class-template-argument-deduction/)
+[How to use class template argument deduction](https://devblogs.microsoft.com/cppblog/how-to-use-class-template-argument-deduction/)