gsl-lite v1.0.1

Fixes

• Add span<> constructor overloads for span<>::iterator arguments. (fec81ab)
  This improves backward compatibility, since our iterator used to be a pointer in v0.*, which made span{ otherSpan.begin(), 0 } work because we have constructor overloads that accept pointers.
• Add missing alias templates for polyfills. (62afbe9)

Full Changelog: v1.0.0...v1.0.1

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

Additions:

• not_null<> now supports function pointers and nullable function objects such as std::function<> and (for C++11 and newer) defines a conditionally enabled forwarding operator() to permit function-call syntax (#353, thanks to @n0F4x)
• not_null<> now supports implicit construction from non-nullable arguments such as function objects and functions (#353)
• Add is_nullable<> trait (#353, thanks to @BenFrantzDale)
• Add tentative C++26 detection macro gsl_CPP26_OR_GREATER, CONSTEXPR_26 language feature, and gsl_constexpr26 keyword macro (61b8d1b, 150c418)
• For C++20 and newer, define operator<=> for not_null<> in C++20 (613a9ff)
• For C++20 and newer, add gsl_NO_UNIQUE_ADDRESS which uses MSVC's ABI-breaking [[msvc::no_unique_address]] attribute if necessary (315c935, a45222f, 991aee6)

Changes:

• Add feature macro gsl_FEATURE_STRING_SPAN, defaulting to 0 for version-1 defaults, to control the availability of string spans, which are no longer part of the GSL specification and have been deprecated for a while (2117b41)
• Add feature macro gsl_FEATURE_BYTE, defaulting to 0 for version-1 defaults, to control the availability of byte, which has been superseded by std::byte in C++17 (dd3251e)
• If gsl_FEATURE_STRING_SPAN=0, we now avoid pulling in standard library header files <ios> and <string> (2117b41)
• In version-1 mode, default to gsl_CONFIG_CONTRACT_VIOLATION_ASSERTS rather than gsl_CONFIG_CONTRACT_VIOLATION_TERMINATES, which is more convenient in practice (4e24de0)
• gsl_FEATURE_WITH_CONTAINER_TO_STD now defaults to 0 with version-1 defaults (#353)
• Remove unsupported CUDA toolkits and older GCC versions no longer available through Azure Pipelines (#353)

Fixes:

• Add [[maybe_unused]] annotations to macro-generated function definitions to avoid Clang warnings about unused functions in anonymous namespaces (30e1390)

Additions:

• Define gsl_MAYBE_UNUSED_MEMBER for [[maybe_unused]] annotations on members (34ba514)
• Support not_null<void*> (#341, thanks to @BenFrantzDale)
• Support not_null<> for unique_ptr<void, D> and shared_ptr<void> (#349, thanks to @BenFrantzDale)

Changes:

• For modern (≥v1) defaults, finally(), on_return(), and on_error() are now implemented without virtual function calls (#342)
• Deprecate finally(), on_return(), and on_error() for pre-C++11 (#342)
• narrow_failfast<>() now uses gsl_Assert() rather than gsl_Expects() to express the contract check (#351)
• std::hash<gsl_lite::byte> now forwards to std::hash<unsigned char> (#343)
• Add Continuous Integration for GCC 13, Clang 17 to 19, and for NVCC 12.6; remove CI for GCC 10 on macOS and for Apple Clang 12.0.5 and earlier (#351)

Fixes:

• std::terminate() cannot be called from CUDA device code, but the call may go undetected due to a NVCC issue; for !gsl_CONFIG( NARROW_THROWS_ON_TRUNCATION ), narrow<>() now makes sure that the program is terminated by issuing a trap instruction if std::terminate() is not available (#351, thanks to @pauleonix for helping track this down)
• narrow<>() no longer responds to gsl_CONFIG_CONTRACT_VIOLATION_THROWS because it does not do contract checking; therefore, it now plainly fails to compile if gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION is set to 1 even though exceptions are unavailable (e.g. in device code) (#351)
• Fix issues in test suite (#338, thanks to @musicinmybrain)

Additions:

• Add tentative C++23 detection macro gsl_CPP23_OR_GREATER, CONSTEXPR_23 language feature, and gsl_constexpr23 keyword macro (#329)
• Add gsl_CONFIG_VALIDATES_UNENFORCED_CONTRACT_EXPRESSIONS config switch for suppressing the compile-time syntax validation of contract check expressions (#330)

Changes:

• Deprecate string_span and zstring_span and prepare for removal (#335)
• Continuous Integration now also tests GCC 12, Clang 14 thru 16, and NVCC 11.8 and 12.1
• Remove Continuous Integration for GCC 6 and earlier, Clang 5 and earlier, Apple Clang 11.0.0 and earlier, and CUDA 10.2 and earlier (#333, #334)

Fixes:

• Use NVCC's __builtin_assume() for gsl_ASSUME_() in device code (#324, thanks to @codecircuit)
• Fix not_null_ic<> copy construction (#326, thanks to @runer112)
• Respect libc++ configuration option to disable wchar_t (#331, thanks to @burnpanck)
• Suppress "-Wweak-vtables" warning for Clang (#332, thanks to @mrahn)
• Suppress "-Wuseless-cast" warning for GCC (#332, thanks to @wirew0rm)

Additions:

• Add debug-mode contract checking macros gsl_ExpectsDebug(), gsl_EnsuresDebug(), gsl_AssertDebug() which are sensitive to the NDEBUG macro, and thus similar to assert() (#316)
• Add dedicated contract check configuration macros for device code: gsl_CONFIG_DEVICE_CONTRACT_CHECKING_AUDIT/ON/OFF, gsl_CONFIG_DEVICE_CONTRACT_VIOLATION_ASSERTS/TRAPS/CALLS_HANDLER, and gsl_CONFIG_DEVICE_UNENFORCED_CONTRACTS_ASSUME/ELIDE (#317)
• Add gsl::is_valid() for explicitly detecting the moved-from state of a gsl::not_null<> object (#318)
• Add device code detection macro gsl_DEVICE_CODE (evaluates to 1 when compiling CUDA device code, 0 when compiling host code)

Changes:

• Continuous Integration now also tests Clang 13 and updates CUDA version to 11.5
• Improve documentation for contract checking macros and configuration macros

Fixes:

• Check for gsl:: target rather than nonexistent gsl-lite:: target in Config.cmake (#315, thanks to @Ram-Z)

Additions:

• Add gsl::make_unique<T>() and gsl::make_shared<T>() which resemble the eponymous functions from std but return gsl::not_null<std::unique_ptr<T>> and gsl::not_null<std::shared_ptr<T>> (#312)
• Add basic support for NVHPC compiler (#308, thanks to @olupton)

Changes:

• Continuous Integration now also tests GCC 11, Clang 12, and AppleClang 12.0.5 and 13, and updates CUDA version to 11.4 (#314)
• Remove C++98 polyfills std98::equal(), std98::lexicographical_compare() from public interface (#313)

Fixes:

• gsl::not_null<std::shared_ptr<T>> now correctly converts to std::weak_ptr<T> (#311, thanks to @stohrendorf)

Additions:

• Add feature detection macro gsl_HAVE( C99_PREPROCESSOR )
• Add gsl_CONSTRAINT() which can be used to impose concept requirements on template type parameters in a backward-compatible manner:
  template< gsl_CONSTRAINT(Concept) T > expands to template< Concept T > for C++20 and to template< typename T > otherwise
• Add C++20 polyfill std20::endian() (#305)
• Restore Continuous Integration testing for NVCC 10.2
• Add basic CUDA runtime tests to test suite (#307)

Changes:

• Continuous Integration now also tests "RelWithDebInfo" configuration for select compilers and platforms

Fixes:

• Fix regression in precondition/postcondition/assertion checks for CUDA (cf. #302, thanks to @Spielix)
• Add workaround for GCC bug to test suite (cf. #303, thanks to @sanjayankur31)
• Fix endianness issues in test suite (cf. #304, thanks to @sanjayankur31)
• Improve constexpr support for span<>; add constexpr tests (#306)

Additions:

• Add macros gsl_Assert(), gsl_AssertAudit() to express checks which are neither pre- nor postconditions (#294)
• Add fail-fast operation gsl_FailFast() which is guaranteed to terminate normal execution in some way
  (exception, std::terminate(), or trap instruction) (#294)
• Add configuration option gsl_CONFIG_CONTRACT_VIOLATION_TRAPS which makes gsl_Expects()/gsl_Ensures()/gsl_Assert() (and the Audit variants if audit mode is enabled) and gsl_FailFast() execute a trap instruction in case of a contract violation
• Add configuration option gsl_CONFIG_CONTRACT_VIOLATION_ASSERTS which implements gsl_Expects()/gsl_Ensures()/gsl_Assert() (and the Audit variants if audit mode is enabled) in terms of the assert() macro from the standard library. This has the benefits that both legacy assertions and contract checks can be globally suppressed with a single macro (NDEBUG), and that assert() prints an informative error message which contains the contract check expression.
• Add as_nullable() function (#251, thanks to @petamas)
• Add compiler detection macro for NVCC (#294)
• Add compiler detection macro and tentative support (no CI) for ARMCC (#293; thanks to @woodsking2)
• Add conditional std::hash<> specialization for not_null<> (#297; thanks to @mbs-c)
• Track language and library versions separately; new macros gsl_STDLIB_CPPxx_OR_GREATER indicate availability of the standard library
• Add feature detection macros gsl_HAVE( HASH ), gsl_HAVE( MOVE_FORWARD ), gsl_HAVE( OVERRIDE_FINAL )
• Add size_type to span<> and basic_string_span<>
• Add Continuous Integration testing for NVCC 11.0-11.2 (CUDA14, CUDA17), Clang 10-11, GCC 10, Apple Clang 12.0.0
• Add Continuous Integration testing for Clang with libstdc++
• Add Valgrind "memcheck" run to Continuous Integration
• Add testing for more configuration scenarios, e.g. building with exceptions disabled and using different ways of precondition violation handling

Changes:

• Remove dependency on standard library headers <algorithm> and <iterator> (#290, #295; thanks to @mpusz)
• Use of gsl_HAVE(), gsl_CONFIG(), gsl_FEATURE() with unknown arguments now causes compilation errors (#272)
• narrow<>() now issues a static_assert() that refers to narrow_failfast<>() if exceptions are unavailable (#269)
• With version-1 defaults, not_null<> now has a specialization for raw pointers which avoids unnecessary contract checks (#300)
• The contract expression is now part of the exception message in gsl_CONFIG_CONTRACT_VIOLATION_THROWS mode
• narrowing_error now produces a less unhelpful exception message ("narrowing_error")
• gsl_noexcept now falls back to throw() if noexcept is unavailable
• Most symbols are now accessible through both namespace gsl and namespace gsl_lite to ease migration
• not_null_ic<> is now also visible in namespace gsl_lite (#280; thanks to @woodsking2)
• nullptr_t comparison operators for not_null<> are now explicitly deleted
• More uses of gsl_NODISCARD throughout the library
• For NVCC ≥11.3, make use of new __builtin_unreachable() intrinsic in gsl_CONFIG_UNENFORCED_CONTRACTS_ASSUME mode

Fixes:

• Many bugfixes (#249, #250, #255, #256, #262, #263, #268, #270, #271, #286, #287, #292; thanks to @fodinabor, @KazDragon,
  @martinmoene, @Maximus5, @Pesa, @petamas, @travnick)

Additions:

• Add configuration option gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION
• Add configuration option gsl_CONFIG_ALLOWS_SPAN_COMPARISON
• Add narrow_failfast<>(), a fast-fail variant of narrow<>() (#52)
• Add front() and back() to span<> and basic_string_span<> (#241, thanks to @ned14)

Changes:

• Rename as_writeable_bytes() -> as_writable_bytes() to follow C++20 in spelling; the old name is still provided for compatibility
• Rename gsl_DEPRECATED() -> gsl_DEPRECATED_MSG(), add gsl_DEPRECATED
• Add more gsl_DEPRECATED() annotations
• Deprecate span<>::at(), basic_string_span<>::at(), and call indexing
• Minor documentation improvements
• Unify internal SFINAE macros to gsl_ENABLE_IF_() (#238; thanks to @martinmoene)
• Add more comprehensive tests for narrow<>() and narrow_failfast<>()

Fixes:

• Fix spurious static assertion for pre-/postcondition check arguments explicitly convertible to bool if gsl_CONFIG_CONTRACT_CHECKING_OFF is defined
• Fix hard failure in span<> constrained constructor (#242, thanks to @orangeturtle739)
• Make gsl::detail::is_compatible_container<> a proper type trait