Bot releases are visible (Hide)
Version 4.0.0 of Microsoft's implementation of the C++ Core Guidelines Support Library (GSL) is now available! This release maintains the safety guarantees that we have always offered, and adds improvements to various parts of the library.
gsl::string_span
<gsl/multi_span>
gsl_
prefixnot_null
gsl::span
and std::span
now use the correct specialization of gsl::at
zstring
family no longer requires empty brackets to be used: issue#992
void foo(zstring<> str);
should now be void foo(zstring str);
gsl::narrowing_error
now has a helpful what()
messagefinally
and final_action
are now [[nodiscard]]
GSL_NO_IOSTREAMS
flag: #953
gsl::string_span
isocpp/CppCoreGuidelines#1680 removed string_span
from the C++ Core Guidelines. The recommendation is to use std::string_view
, std::span<char>
or gsl::span<char>
instead. To more closely align Microsoft’s GSL with the C++ Core Guidelines, we deprecated our implementation of string_span
and zstring_span
, including basic_string_span
, basic_zstring_span
, and all related types. For the time being, we will continue to provide the <gsl/string_span>
header, but it will not be actively worked on or maintained. A table of all supported and unsupported types/features can be found in the README.md.
<gsl/multi_span>
multi_span
, strided_span
, and everything else in <gsl/multi_span>
were deprecated over a year ago in GSL 3.0.0, and it is time for them and their associated tests to be removed from the library.
gsl_
prefixAll headers which previously contained a gsl_
prefix in their name have had this prefix removed. For example, <gsl/gsl_algorithm>
is now <gsl/algorithm>
. The gsl_
prefixed files still exist and pass through to the updated files, but will be removed in a future release.
not_null
To more closely align Microsoft’s GSL with the C++ Core Guidelines, gsl::not_null
now accepts only types which are comparable to nullptr
. Previously, it accepted only types which are assignable from nullptr
, but this was stricter than what was intended by the Core Guidelines.
The functions make_not_null
and make_strict_not_null
, and the not_null
comparison operators, are now all noexcept
.
gsl::span
and std::span
now use the correct specialization of gsl::at
gsl::span
and std::span
now have their own separate specializations of gsl::at
, to ensure consistent behavior between the two versions of span. Both overloads are included when importing <gsl/span>
. The std::span
overload can be separately included from <gsl/util>
.
gsl::narrow
is the only part of the library which may throw exceptions and has been moved into its own header <gsl/narrow>
. This header is included in <gsl/gsl>
only if exceptions are enabled. This allows users of the library who are working in environments without exceptions to use all of the other components of the library.
Note: gsl::narrow_cast
is still in <gsl/util>
, since it does not throw exceptions.
The list of supported compilers/toolsets has been updated with newer versions. More info on compiler support can be found in the README.md.
Compiler/Toolset | Version |
---|---|
XCode | 13.2.1 & 12.5.1 |
GCC | 11.1.0 & 10.3.0 |
Clang | 12.0.0 & 11.0.0 |
Visual Studio with MSVC | VS2022 (17.0) & VS2019 (16.11) |
Visual Studio with LLVM | VS2022 (17.0) & VS2019 (16.11) |
GSL_INSTALL
: #964
CMAKE_CXX_STANDARD
if it's provided #953
GSL_SUPPRESS
warning for intel compilers: #906
std::span
: #993
VS_ADD_NATIVE_VISUALIZERS
has been renamed to GSL_VS_ADD_NATIVE_VISUALIZERS
: #941
Published by JordanMaples over 4 years ago
Published by JordanMaples over 4 years ago
This is a minor release that addresses a bug in gsl::narrow
.
Bug details: Previously gsl::narrow
was changed to follow the same termination behavior as contract violations. However the Core Guidelines explicitly says gsl::narrow
should throw a gsl::narrowing_error
on failure.
Fix: PR #873 corrects this issue and re-introduces the throwing behavior for gsl::narrow
.
Published by JordanMaples over 4 years ago
Version 3.0.0 of Microsoft's implementation of the C++ Core Guidelines Support Library (GSL) is now available! Microsoft’s implementation of gsl::span
has played a pivotal role in the standardization of span for C++20. However, the standard does not provide any runtime checking guarantees for memory bounds safety. The bounds safety provided by gsl::span
has been very successful in preventing security issues in Microsoft products. This release maintains the safety guarantees that we have always offered but modernizes our implementation to align with C++20 span.
gsl::span
and gsl::span_iterator
that align to the C++ 20 standard.gsl::multi_span
and gsl::strided_span
.By default, use std::span
which is shipping in VS2019 16.6 (with additional interface changes in 16.7, see release notes) if you have enabled C++20 mode and do not need runtime bounds checking guarantees. Use gsl::span
if you need support for a version of C++ lower than C++20 (gsl::span
supports C++14 and higher) or runtime bounds checking guarantees (all operations performed on gsl::span
and its iterators have explicit bounds safety checks.)
With the standardization of span nearing completion, we decided it was time to align our implementation with the design changes in the standard. The new implementation provides full bounds checking, guaranteeing bounds safety if the underlying data is valid.
gsl::span
was rewritten to have its interface align to std::span
. The biggest change is that span's Extent is now unsigned. It is now implemented as std::size_t
whereas previously it was std::ptrdiff_t
. By extension, dynamic_extent
is now defined as static_cast<std::size_t>(-1)
instead of just -1
.
span::index_type
was removed, superseded by span::size_type
.These are the changes required to align gsl::span
to the interface of std::span
.
span::operator()
span::at
span::cbegin
span::cend
span::crbegin
span::crend
span::front
span::back
span::as_writeable_bytes
was renamed to span::as_writable_bytes
Our implementation of span_iterator
has been completely rewritten to be more range-like. Previously, the implementation consisted of a span pointer and an offset. The new implementation is a set of three pointers: begin, end, and current.
The new implementation can perform all of the bounds checks by itself, instead of calling into the span. By relying on pointers to the underlying data, rather than a pointer to the span, the new span_iterator
can outlive the underlying span.
The <gsl/span_ext> header was created to support our customers who rely on portions of the old span implementation that no longer exist in the standard definition of span.
gsl::make_span
gsl::at
gsl::begin
gsl::rbegin
gsl::crbegin
gsl::end
gsl::rend
gsl::crend
Contract violations are no longer configurable. Contract violations always result in termination, rather than providing a compile-time option to throw or disregard the contract violation. This is subject to change in the future. Some concerns over this decision have been raised and the conversation continues here: isocpp/CppCoreGuidelines#1561. As a side note, the removal of the throwing behavior required the migration of our test infrastructure from Catch2 to Google Test, whose support of death tests easily enabled testing of contract violation behavior.
This release now supports find_package
. Once installed, use find_package(Microsoft.GSL CONFIG)
to easily consume the GSL.
To more closely align Microsoft’s GSL to the C++ Core Guidelines, we decided to deprecate our implementation of gsl::multi_span
and gsl::strided_span
. For the time being, we will continue to provide these headers, but they will not be actively worked on or maintained unless the C++ Core Guidelines identifies a need for them.
std::ptrdiff_t
to unsigned std::size_t
in gsl::span
may introduce signed/unsigned mismatches.
static_cast
or gsl::narrow_cast
to resolve mismatches.gsl::multi_span
and gsl::strided_span
have been deprecated.
gsl::multi_span
.gsl::make_span
, etc.
The paper P1976R2 that came out of the WG21 Prague meeting has yet to be implemented in GSL. A minor release will be issued when it is added to GSL.
Published by JordanMaples almost 5 years ago
Published by annagrin about 6 years ago
Main API changes include
Test changes:
Also fixed CppCorecheck warnings and made numerous bug fixes.
Published by annagrin over 6 years ago
GSL commits are all CI verified and considered stable. However, we would like to mark significant changes (such as API breaking ones or adding extra functionality) by changing versions.
Those commits are additionally verified by compiling and testing MS Static analysis tools that use GSL.