GSL 4.0.0 Release

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.

What changed in this release?

• Deprecation of gsl::string_span
• Removal of <gsl/multi_span>
• Header files dropped the gsl_ prefix
• Changes to not_null
• gsl::span and std::span now use the correct specialization of gsl::at
• The zstring family no longer requires empty brackets to be used: issue#992
  • for example, void foo(zstring<> str); should now be void foo(zstring str);
• gsl::narrowing_error now has a helpful what() message
• finally and final_action are now [[nodiscard]]
• GSL will work in environments where exceptions are disabled, with some caveats
• GSL will work in environments which do not support ios, via the addition of the GSL_NO_IOSTREAMS flag: #953
• Updated compiler support
• CMake and build improvements

Deprecation of 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.

Removal of <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.

Header files dropped the gsl_ prefix

All 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.

Changes to 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 will work in environments where exceptions are disabled, with some caveats

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.

Updated compiler support

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)

CMake and build improvements

• GSL Install logic is now guarded by a cmake option GSL_INSTALL: #964
• Fix bug which prevented the library from being built on a 32-bit host and then being used on a 64-bit machine: #893
• Build will now use CMAKE_CXX_STANDARD if it's provided #953
• Clean up GSL_SUPPRESS warning for intel compilers: #906
• Fix build failure for C++20 compilers which don't have std::span: #993
• Cleaned up some static analysis warnings
• The cmake cache variable VS_ADD_NATIVE_VISUALIZERS has been renamed to GSL_VS_ADD_NATIVE_VISUALIZERS: #941

---

Updates

• Update 1/28/2022: Bumped the release forward to hotfix a353456

3.1.0 update

New this release

• Implementation of P1976R2 for gsl::span introduces explicit construction of fixed-length spans from dynamic spans.
  • See span_compatibility_tests.cpp for additional details.
  • PR: #887
• Better template argument deduction for gsl::span.
  • See span_tests.cpp for examples.
  • PR: #891
• Improved natvis for span and span derived types.
  • PR: #857
• Added CMake find_package version support.
  • PR: #879

3.0.1

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.

GSL 3.0.0 Release

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.

What changed in this release?

• New implementations of gsl::span and gsl::span_iterator that align to the C++ 20 standard.
• Changes to contract violation behavior.
• Additional CMake support.
• Deprecation of gsl::multi_span and gsl::strided_span.

When should I use gsl::span instead of std::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.)

gsl::span

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.

General changes

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.

• The field span::index_type was removed, superseded by span::size_type.
• Addition of Class Template Argument Deduction (CTAD) support.

Interface alignment

These are the changes required to align gsl::span to the interface of std::span.

Removed functions

• span::operator()
• span::at
• span::cbegin
• span::cend
• span::crbegin
• span::crend

Added functions

• span::front
• span::back

Renamed functions

• span::as_writeable_bytes was renamed to span::as_writable_bytes

gsl::span_iterator

General changes

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.

Benefits of our new implementation

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 new <gsl/span_ext> header

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.

Elements moved from <gsl/span> and inserted into <gsl/span_ext>

• span comparison operators
• gsl::make_span
• span specialization of gsl::at
• gsl::begin
• gsl::rbegin
• gsl::crbegin
• gsl::end
• gsl::rend
• gsl::crend

Contract violations

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.

CMake improvements

This release now supports find_package. Once installed, use find_package(Microsoft.GSL CONFIG) to easily consume the GSL.

Deprecation of multi_span and strided_span

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.

Improvement changes causing potential build breaks and mitigations

• Change: The change from signed std::ptrdiff_t to unsigned std::size_t in gsl::span may introduce signed/unsigned mismatches.
  • Mitigation: Use static_cast or gsl::narrow_cast to resolve mismatches.
• Change: gsl::multi_span and gsl::strided_span have been deprecated.
  • Mitigation: Pass multi-dimensional arrays as constant references instead of gsl::multi_span.
• Change: Code that makes use of moved span helper functions will generate compiler errors. Examples of these functions include span comparison operators, gsl::make_span, etc.
  • Mitigation: Include <gsl/span_ext> instead of <gsl/span> in files where you use these functions.
• Change: Throwing contract violation behavior is removed.
  • Mitigation: Use a terminate handler to log relevant information before termination executes for debugging. Relying on throwing behavior does not guarantee safety.

Upcoming changes

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.

Snapshot: End of 2019

Changes included in this version

Major changes

• Deprecation of multi_span and strided_span.

Minor changes

• Additional constexpr support
• Bug fixes

What to look forward to in future releases

• The GSL is changing how it handles contract violations.
• The test framework is being replaced with GoogleTest to accommodate the contract violation changes.

Additional information on contract violation changes

Previous behavior on contract violation

• Option to ignore, terminate, or throw on contract violation.

New behavior

• Contract violation will always result in termination.

Verified version

Main API changes include

• explicit not_null contructors (see samples/gsl_transition for ideas on how to move to the new version)
• added make_not_null
• cleanup of constexpr and noexcept

Test changes:

• added tests for c++14 and c++17

Also fixed CppCorecheck warnings and made numerous bug fixes.

Started versioning

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.