Skip to content

Commit e52bfb1

Browse files
TylerMSFTTyler WhitneyStephanTLavavejColin Robertson
authored
Twhitney span (#2880)
* start draft * draft * draft * draft * draft * draft * draft * remove my bookmarks * fix typos * fix build warnings * acrolinx and link fixes * draft * draft * typos * add top- links * mark code headings as code so they don't get localized * Update span.md * Monospace `vector` and `array`, being the names of Standard containers. * `void main()` is non-Standard; it should be `int main()`. (There's a special rule that `return 0;` is unnecessary here.) * Qualify `std::cout`, otherwise the example won't compile. (There are still no spaces or newlines being printed after each element.) * Mention `/std:c++latest` as a requirement. * 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 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 for `span` because `span` isn't placing anything special there. * Remove top- `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 : 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 . * Update span-functions.md * Rename parameter from `span` to `s` to avoid "shadowing" ambiguity. (The Standard says `s` .) * Add semicolons to declarations. * Fix `Dynamic_Extent` capitalization to `dynamic_extent`. * FIXME NOTES: The claimed return types are incorrect; these functions return `span<const byte, MEOW>` and `span<byte, MEOW>` where `MEOW` is a conditional expression. Noted but not fixed. * RENAMED: The Standard name of the function is `as_writable_bytes`, not `writeable`. I've replaced all occurrences in this document; please check any cross-references. (This was renamed during Standardization, so old mentions may be common. We never shipped the old name in the STL.) * incorp tech review * incorp tech review * remove nullptr info * update ms.date * fix backtick * a little wordsmithing * Fix template name The other correction may not be needed - I'd proposed adding the template parameters to the Parameters section of the `span::span` constructors. Co-authored-by: Tyler Whitney <Tyler.Whitney@microsoft.com> Co-authored-by: Stephan T. Lavavej <stl@microsoft.com> Co-authored-by: Colin Robertson <corob@microsoft.com>
1 parent cd999d5 commit e52bfb1

5 files changed

Lines changed: 1256 additions & 1 deletion

File tree

‎docs/standard-library/cpp-standard-library-header-files.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Header files for the C++ standard library and extensions, by category.
2323
| Ordered associative containers| [\<map>](map.md), [\<set>](set.md) |
2424
| Unordered associative containers | [\<unordered_map>](unordered-map.md)<sup>11</sup>, [\<unordered_set>](unordered-set.md)<sup>11</sup> |
2525
| Container adaptors | [\<queue>](queue.md), [\<stack>](stack.md) |
26-
| Container views | \<span><sup>20</sup> |
26+
| Container views | [\<span>](span.md)<sup>20</sup> |
2727
| [Errors and exception handling](../cpp/errors-and-exception-handling-modern-cpp.md) | [\<cassert>](cassert.md), [\<exception>](exception.md), [\<stdexcept>](stdexcept.md), [\<system_error>](system-error.md)<sup>11</sup> |
2828
| General utilities | \<any><sup>17</sup>, [\<bitset>](bitset.md), \<charconv><sup>17</sup>, [\<cstdlib>](cstdlib.md), \<execution><sup>17</sup>, [\<functional>](functional.md), [\<memory>](memory.md), \<memory_resource><sup>17</sup>, \<optional><sup>17</sup>, [\<ratio>](ratio.md)<sup>11</sup>, [\<scoped_allocator>](scoped-allocator.md)<sup>11</sup>, [\<tuple>](tuple.md)<sup>11</sup>, [\<type_traits>](type-traits.md)<sup>11</sup>, [\<typeindex>](typeindex.md)<sup>11</sup>, [\<utility>](utility.md), \<variant><sup>17</sup> |
2929
| [I/O and formatting](../text/string-and-i-o-formatting-modern-cpp.md) | [\<cinttypes>](cinttypes.md)<sup>11</sup>, [\<cstdio>](cstdio.md), [\<filesystem>](filesystem.md)<sup>17</sup>, [\<fstream>](fstream.md), [\<iomanip>](iomanip.md), [\<ios>](ios.md), [\<iosfwd>](iosfwd.md), [\<iostream>](iostream.md), [\<istream>](istream.md), [\<ostream>](ostream.md), [\<sstream>](sstream.md), [\<streambuf>](streambuf.md), [\<strstream>](strstream.md)<sup>c</sup>, \<syncstream><sup>20</sup> |

0 commit comments

Comments
 (0)