gsl-lite v1.0.0

Breaking changes

namespace gsl_lite and <gsl-lite/gsl-lite.hpp>

gsl-lite now lives in the single header file <gsl-lite/gsl-lite.hpp>, and all its symbols reside in namespace gsl_lite. By default, gsl-lite no longer defines a namespace gsl or the unprefixed Expects() and Ensures() macros for precondition and postcondition checking.

This change enables coexistence with Microsoft GSL or other GSL implementations. (#194)

To minimize the impact of the breaking changes, gsl-lite introduces an optional GSL compatibility mode controlled by the new configuration switch gsl_FEATURE_GSL_COMPATIBILITY_MODE, which is is disabled by default and can be enabled by defining gsl_FEATURE_GSL_COMPATIBILITY_MODE=1. This should not be used in public header files of libraries which use gsl-lite because it precludes the use of Microsoft GSL in the same translation unit.

The legacy header file <gsl/gsl-lite.hpp> now forwards to <gsl-lite/gsl-lite.hpp> and implicitly enables the GSL compatibility mode. When the legacy header is included, it emits a warning message which urges to either migrate to header <gsl-lite/gsl-lite.hpp>, namespace gsl_lite, and the prefixed contract checking macros gsl_Expects() and gsl_Ensures(), or to explicitly request GSL compatibility by defining gsl_FEATURE_GSL_COMPATIBILITY_MODE=1.

Please refer to the migration guide in the gsl-lite documentation for guidance on how to adapt your code.

Other changes

• span<> now implements static extents. This was achieved by adapting the span<> implementation from Microsoft GSL, back-porting it to support C++98 and older compilers. (#153; 14c9f73)

• span<>::iterator now is a proper class instead of a pointer. Span iterator operations are now checked with gsl_ExpectsDebug(). (#153; 14c9f73)

• gsl-lite v1 has different defaults for the numerous configuration options and switches:

  • gsl_FEATURE_STRING_SPAN:
    Version-1 default: gsl_FEATURE_STRING_SPAN=0
    Version-0 default: gsl_FEATURE_STRING_SPAN=1
    Reason: string spans are no longer part of the GSL specification.
  • gsl_FEATURE_BYTE:
    Version-1 default: gsl_FEATURE_BYTE=0
    Version-0 default: gsl_FEATURE_BYTE=1
    Reason: byte has been superseded by std::byte in C++17.
  • gsl_CONFIG_DEPRECATE_TO_LEVEL:
    Version-1 default: gsl_CONFIG_DEPRECATE_TO_LEVEL=9
    Version-0 default: gsl_CONFIG_DEPRECATE_TO_LEVEL=0
  • gsl_CONFIG_INDEX_TYPE:
    Version-1 default: std::ptrdiff_t
    Version-0 default: gsl_CONFIG_SPAN_INDEX_TYPE (defaults to std::size_t)
    Reason: the GSL specifies gsl::index to be a signed type.
  • gsl_CONFIG_ALLOWS_SPAN_COMPARISON:
    Version-1 default: gsl_CONFIG_ALLOWS_SPAN_COMPARISON=0
    Version-0 default: gsl_CONFIG_ALLOWS_SPAN_COMPARISON=1
    Reason: C++20 std::span<> does not support comparison because semantics (deep vs. shallow) are unclear.
  • gsl_CONFIG_NOT_NULL_EXPLICIT_CTOR:
    Version-1 default: gsl_CONFIG_NOT_NULL_EXPLICIT_CTOR=1
    Version-0 default: gsl_CONFIG_NOT_NULL_EXPLICIT_CTOR=0
    Reason: see M-GSL/#395. (Note that not_null<> in Microsoft GSL has an implicit constructor, cf. M-GSL/#699.)
  • gsl_CONFIG_TRANSPARENT_NOT_NULL:
    Version-1 default: gsl_CONFIG_TRANSPARENT_NOT_NULL=1
    Version-0 default: gsl_CONFIG_TRANSPARENT_NOT_NULL=0
    Reason: enables conformant behavior for not_null<>::get().
  • gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION:
    Version-1 default: gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION=1
    Version-0 default: gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION=0
    Reason: enables conformant behavior for narrow<>() (cf. #52).
  • default runtime contract violation handling:
    Version-1 default: gsl_CONFIG_CONTRACT_VIOLATION_ASSERTS
    Version-0 default: gsl_CONFIG_CONTRACT_VIOLATION_TERMINATES
    Reason: the mode enabled by gsl_CONFIG_CONTRACT_VIOLATION_ASSERTS is consistent with the behavior of the assert() macro
    while retaining runtime contract checks even if NDEBUG is defined.

• narrow<>() and narrow_failfast<>() now support non-totally-ordered types such as std::complex<>, borrowing from microsoft/GSL#986. (#309; 238f8a3)

• gsl-lite now emits a warning if a configuration option alters the binary interface, leading to possible ODR violations. The warning can be explicitly overridden by defining gsl_CONFIG_ACKNOWLEDGE_NONSTANDARD_ABI. (cb76beb)

• For MSVC on Windows, gsl-lite now uses #pragma detect_mismatch() to diagnose ABI incompatibilities at link time. (cb76beb)

Fixes

• In C++98 mode, the faulty definition of the internal function macro gsl_STATIC_ASSERT_() was corrected, fixing an unwanted predicate inversion for some internal compile-time checks. (ad2ffbd)
• Contract check macros now always expand to an expression or a statement, which avoids compiler warnings. (4654752)

Deprecations and removals

• Deprecated unsafe span<> member function as_span<>(). (14c9f73)
• Removed Owner() and implicit macros, which already were disabled by default. (10952e7)
• Removed finally(), on_error(), and on_return() implementation for C++98. (6bae768)
• Removed many deprecated functions: (6163d13, 14c9f73)
  • as_writeable_bytes()
  • basic_string_span<> member function operator() for indexing
  • span<> constructor overloads and make_span() overloads accepting reference arguments, unique_ptr<>, or shared_ptr<> arguments
  • span<> member functions at() and operator() for indexing
  • span<> member functions length(), length_bytes(), as_bytes(), as_writeable_bytes()
• Removed the non-templated functions finally(), on_return(), and on_error() for C++98. (6bae768)

Full Changelog: v0.43.0...v1.0.0