Repository navigation
Fix git push error for protected CLA branch - #2233
Merged
Merged
Conversation
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
…into twhitney-span
* 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.
* 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.
* Rename parameter from `span` to `s` to avoid "shadowing" ambiguity. (The Standard says `s` here.) * 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.)
Update span.md
Update span-class.md
Update span-functions.md
…into twhitney-span
…into twhitney-span
…into twhitney-span
The other correction may not be needed - I'd proposed adding the template parameters to the Parameters section of the `span::span` constructors.
Fix template name
* 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>
…into twhitney-span
incorp pr review
Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master)
Publish \<span> docs to live
Colin Robertson (colin-home)
approved these changes
May 31, 2020
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The pull request is created from master637263929302347004 to master to fix git push error for protected CLA branch