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.

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.

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.

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.

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.