Document differences between hardened std::span and gsl::span - #1206
Conversation
Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>
Carson Radtke (carsonRadtke)
left a comment
There was a problem hiding this comment.
Address my comment. I don't think you need a whole word-wall FAQ - just enough info for a user to make an informed decision.
|
|
||
| With the adoption of [P3471: Standard library hardening](https://isocpp.org/files/papers/P3471R4.html) in C++26, | ||
| the gap between `std::span` and `gsl::span` is narrowing, but differences remain. For detailed information about the | ||
| differences and guidance on which one to use, see the [FAQ](FAQ.md#what-are-the-differences-between-gslspan-and-hardened-stdspan-in-c26). |
There was a problem hiding this comment.
Let's not introduce a whole FAQ file. I think here it is fine to just say:
--
- C++14 + C++17 -> Use
gsl::spanbecause it is your only option. - C++20 + C++23 -> Use
gsl::spanbecause accesses are bounds checked. - C++26* -> Use
gsl::spanbecause iterators are hardened too.
* C++26 or a backported standard library implementation.
Something also to note is that the behavior-on-error is not configurable for GSL (std::terminate()), but it may be configurable for library implementations.
--
This is the gist, but please make the style more similar to the rest of the document and add links as necessary. Also, a chart may provide a helpful visual.
There was a problem hiding this comment.
I've made the changes as requested in 8f9d1d6. I've added a concise table-like format directly in headers.md that explains when to use each span version based on C++ standard version. I also added the note about behavior-on-error configurability, removed the FAQ file entirely, and kept the style consistent with the rest of the document.
Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>
I've simplified the documentation as requested. Instead of using a separate FAQ file, I've added a concise explanation directly in headers.md that follows the C++ version guidelines you suggested. The changes in 8f9d1d6 include:
Warning Firewall rules blocked me from connecting to one or more addressesI tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Carson Radtke (carsonRadtke)
left a comment
There was a problem hiding this comment.
Looks like you injected my previous comment into the document. That was good for an outline, but I'd like you to fill in some more information.
| - Any violations of the bounds check results in termination of the program | ||
| - `gsl::span`'s iterators also perform bounds checking, unlike `std::span`'s iterators | ||
|
|
||
| #### Which version of span should I use? |
There was a problem hiding this comment.
Can we make this section a table? I'd like to have a row for each category and columns for std::span, std::span w/ hardening, and gsl::span. The each cell in the table can offer a little more context.
There was a problem hiding this comment.
I've converted this section to a table in commit d3f39fa. The table now has rows for C++ standard requirements, element access, iterator safety, error behavior, and performance, with columns for std::span, hardened std::span, and gsl::span.
| ##### Use `std::span` if | ||
|
|
||
| - your project is C++20 and you need the performance offered by `std::span`. | ||
| Note that the behavior on bounds check violations is not configurable for GSL (`std::terminate()`), |
There was a problem hiding this comment.
Can we add a little more info here and make the style match the rest of the document?
Ideally there would be links to the hardening documentation for libc++, libstdc++, and STL. Also a link to the bounds-check violation handler in GSL may be useful.
There was a problem hiding this comment.
I've added more detailed information in commit d3f39fa, including links to the GSL bounds-check handler implementation and links to the major C++ standard library implementations (MSVC STL, libc++, and libstdc++) documentation. The style now matches the rest of the document with proper formatting and structure.
Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>
I've enhanced the documentation with more detailed information about span implementations in commit d3f39fa. I replaced the outline with a comprehensive comparison table along with specific recommendations for different C++ standard versions and links to relevant documentation. |
Carson Radtke (carsonRadtke)
left a comment
There was a problem hiding this comment.
Cool. Can you just fix this links as suggested?
| **Implementation notes for hardened `std::span` in C++26:** | ||
| - For MSVC: See [Microsoft STL documentation](https://learn.microsoft.com/cpp/standard-library/library-features-cpp) for hardening options | ||
| - For Clang/LLVM: See [libc++ implementation notes](https://libcxx.llvm.org/) | ||
| - For GCC: See [libstdc++ implementation notes](https://gcc.gnu.org/onlinedocs/libstdc++/) |
There was a problem hiding this comment.
This link doesn't mention anything about library hardening, can you delete it?
There was a problem hiding this comment.
I've removed the GCC libstdc++ link as it doesn't contain information about library hardening in commit 460ced0.
| - Use hardened `std::span` if you want standard library compliance and acceptable safety. | ||
|
|
||
| **Implementation notes for hardened `std::span` in C++26:** | ||
| - For MSVC: See [Microsoft STL documentation](https://learn.microsoft.com/cpp/standard-library/library-features-cpp) for hardening options |
There was a problem hiding this comment.
This link is broken. Use this instead: https://github.com/microsoft/STL/wiki/STL-Hardening
There was a problem hiding this comment.
I've updated the MSVC STL link to point to the STL Hardening wiki page in commit 460ced0.
|
|
||
| **Implementation notes for hardened `std::span` in C++26:** | ||
| - For MSVC: See [Microsoft STL documentation](https://learn.microsoft.com/cpp/standard-library/library-features-cpp) for hardening options | ||
| - For Clang/LLVM: See [libc++ implementation notes](https://libcxx.llvm.org/) |
There was a problem hiding this comment.
Try this link instead: https://libcxx.llvm.org/Hardening.html
There was a problem hiding this comment.
I've updated the libc++ link to point to the Hardening documentation page in commit 460ced0.
Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>
I've fixed all the links as requested in commit 460ced0. The changes include:
|
This PR adds documentation explaining the differences between
gsl::spanand the upcoming hardenedstd::spanin C++26, as specified in P3471: Standard library hardening.Changes
Created a new
FAQ.mdfile in the docs directory with detailed explanations of:gsl::spanandstd::spangsl::spanand hardenedstd::spanin C++26Updated README.md with a reference to the FAQ when describing
gsl::spanEnhanced the span documentation in headers.md with more detailed information about the differences and a link to the FAQ
With these changes, users will be able to make informed decisions about which span implementation to use based on their specific needs, especially as C++26 approaches with its hardened standard library components.
Fixes #1199.
Warning
Firewall rules blocked me from connecting to one or more addresses
I tried to connect to the following addresses, but was blocked by firewall rules:
cdn.fwupd.org/usr/bin/fwupdmgr refresh(dns block)If you need me to access, download, or install something from one of these locations, you can either:
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.