/gsl-lite

A single-file header-only version of ISO C++ Guidelines Support Library (GSL) for C++98, C++03 and later

Primary LanguageC++MIT LicenseMIT

GSL Lite: Guidelines Support Library for C++98, C++03 and C++11 up

Language Standard Standard Standard License Build Status Build status Version download

GSL Lite is based on the Microsoft Guidelines Support Library (GSL).

Contents

Example usage

#include "gsl-lite.h"

using namespace gsl;

int * use( not_null<int *> p ) 
{
    // use p knowing it's not nullptr, NULL or 0.
    
    return p;
}

struct Widget
{
    Widget() : owned_ptr( new int(42) ) {}
    ~Widget() { delete owned_ptr; }

    void work() { non_owned_ptr = use( owned_ptr ); }
    
    owner<int *> owned_ptr;	// if alias template support
//  Owner(int *) owned_ptr;	// C++98 up
    int * non_owned_ptr;
};

int main()
{
    Widget w;
    w.work();
}

Compile and run

prompt>g++ -std=c++03 -Wall -I../include/gsl -o 01-basic.exe 01-basic.cpp && 01-basic.exe

In a nutshell

gsl-lite is a single-file header-only variant of Microsoft's implementation of the Guidelines Support Library (GSL) adapted for C++98, C++03. It should also work when compiled as C++11, C++14.

The Guidelines Support Library (GSL) contains functions and types that are suggested for use by the C++ Core Guidelines maintained by the Standard C++ Foundation. The library includes types like owner<>, not_null<>, span<>, string_span and others.

gsl-lite recognizes when it is compiled for the CUDA platform and decorates functions (methods) with __host__ and __device__. See also section API macro.

License

gsl-lite uses the MIT license.

Dependencies

gsl-lite has no other dependencies than the C++ standard library.

Installation

gsl-lite is a single-file header-only library. Put gsl-lite.h in the include folder directly into the project source tree or somewhere reachable from your project.

Building the tests

To build the tests you need:

The lest test framework is included in the test folder.

The following steps assume that the GSL Lite source code has been cloned into a directory named c:\gsl-lite.

  1. Create a directory for the build outputs for a particular architecture.
    Here we use c:\gsl-lite\build-win-x86-vc10.

     cd c:\gsl-lite
     md build-win-x86-vc10
     cd build-win-x86-vc10
    
  2. Configure CMake to use the compiler of your choice (run cmake --help for a list).

     cmake -G "Visual Studio 10 2010" ..
    
  3. Build the test suite in the Debug configuration (alternatively use Release).

     cmake --build . --config Debug
    
  4. Run the test suite.

     ctest -V -C Debug
    

All tests should pass, indicating your platform is supported and you are ready to use gsl-lite. See the table with supported types and functions.

Synopsis

Contents

API macro

-Dgsl_api=""
Functions (methods) are decorated with gsl_api. At default gsl_api is defined empty for non-CUDA platforms and __host__ __device__ for the CUDA platform. Define this macro to specify your own function decoration.

Feature selection macros

-Dgsl_FEATURE_HAVE_IMPLICIT_MACRO=1
Define this macro to 0 to omit the implicit macro. Default is 1.

-Dgsl_FEATURE_HAVE_OWNER_MACRO=1
At default macro Owner() is defined for all C++ versions. This may be useful to transition from a compiler that doesn't provide alias templates to one that does. Define this macro to 0 to omit the Owner() macro. Default is 1.

Contract violation response macros

gsl-lite provides contract violation response control as suggested in proposal N4415.

-Dgsl_CONFIG_CONTRACT_LEVEL_ON
Define this macro to include both Expects and Ensures in the code. This is the default case.

-Dgsl_CONFIG_CONTRACT_LEVEL_OFF
Define this macro to exclude both Expects and Ensures from the code.

-Dgsl_CONFIG_CONTRACT_LEVEL_EXPECTS_ONLY
Define this macro to include Expects in the code and exclude Ensures from the code.

-Dgsl_CONFIG_CONTRACT_LEVEL_ENSURES_ONLY
Define this macro to exclude Expects from the code and include Ensures in the code.

-Dgsl_CONFIG_CONTRACT_VIOLATION_TERMINATES
Define this macro to call std::terminate() on a GSL contract violation. This is the default case.

-Dgsl_CONFIG_CONTRACT_VIOLATION_THROWS
Define this macro to throw a std::runtime_exception-derived exception gsl::fail_fast instead of calling std::terminate() on a GSL contract violation.

Microsoft GSL compatibility macros

-DGSL_UNENFORCED_ON_CONTRACT_VIOLATION
Equivalent to -Dgsl_CONFIG_CONTRACT_LEVEL_OFF.

-DGSL_THROW_ON_CONTRACT_VIOLATION
Equivalent to -Dgsl_CONFIG_CONTRACT_VIOLATION_THROWS.

-DGSL_TERMINATE_ON_CONTRACT_VIOLATION
Equivalent to -Dgsl_CONFIG_CONTRACT_VIOLATION_TERMINATES.

Other configuration macros

-Dgsl_CONFIG_ALLOWS_NONSTRICT_SPAN_COMPARISON=1
Define this macro to 0 to omit the ability to compare spans of different types, e.g. of different const-volatile-ness. To be able to comapare a string_span with a cstring_span, non-strict span comparison must be available. Default is 1.

-Dgsl_CONFIG_ALLOWS_UNCONSTRAINED_SPAN_CONTAINER_CTOR=1
Define this macro to 0 to omit the unconstrained span constructor for containers for pre-C++11 compilers that cannot constrain the constructor. This constructor may prove too greedy and interfere with other constructors. Default is 1.

Note: an alternative is to use the constructor tagged with_container: span<value_type> s(with_container, cont).

-Dgsl_CONFIG_CONFIRMS_COMPILATION_ERRORS=0
Define this macro to 1 to experience the by-design compile-time errors of the GSL components in the test suite. Default is 0.

Features

See also section GSL: Guideline support library of the C++ Core Guidelines [2].

Feature / library GSL M-GSL GSL-Lite Notes
1.Lifetime safety        
1.1 Indirection        
not_null<> Wrap any indirection and enforce non-null
maybe_null<> - -  
1.2 Ownership        
owner<> >=C++11 Owned raw pointers
Owner() - - Macro for pre-C++11;
see also Feature selection macros
unique_ptr<> >=C++11 std::unique_ptr<>
unique_ptr<> - - < C++11 VC10, VC11
shared_ptr<> >=C++11 std::shared_ptr<>
shared_ptr<> - - < C++11 VC10, VC11
see also Extract Boost smart pointers
stack_array<> - - A stack-allocated array, fixed size
dyn_array<> ? - - A heap-allocated array, fixed size
2.Bounds safety        
2.1 Tag Types        
zstring a char* (C-style string)
wzstring - a wchar_t* (C-style string)
czstring a const char* (C-style string)
cwzstring - a const wchar_t* (C-style string)
2.2 Views        
span<> 1D views A view of contiguous T's, replace (*,len)
span_p<> - - A view of contiguous T's that ends at the first element for which predicate(*p) is true
as_span() - Create a span
string_span span<char>
wstring_span - span<wchar_t >
cstring_span span<const char>
cwstring_span - span<const wchar_t >
ensure_z() - Create a cstring_span or cwstring_span
to_string() - Convert a string_span to std::string or std::wstring
2.3 Indexing        
at() >=C++11 Bounds-checked way of accessing
static arrays, std::array, std::vector
at() - - < C++11 static arrays, std::vector
std::array : VC11
3. Assertions        
Expects() Precondition assertion
Ensures() Postcondition assertion
4. Utilities        
final_act<> >=C++11 Action at the end of a scope
final_act - - < C++11 Currently only void(*)()
finally() >=C++11 Make a final_act<>
finally() - - < C++11 Make a final_act
narrow_cast<> Searchable narrowing casts of values
narrow() Checked version of narrow_cast()
implicit - Symmetric with explicit
move_owner ? - - ...
5. Concepts        
...        

Note: GSL Lite treats VC12 (VS2013) and VC14 (VS2015) as C++11 (gsl_CPP11_OR_GREATER: 1).

Reported to work with

The table below mentions the compiler versions gsl-lite is reported to work with.

OS Compiler Versions
Windows Clang/LLVM ?
  GCC 4.8.4, 4.9.2, 5.2.0
  Visual C++
(Visual Studio)
6 (6) via header gsl-lite-vc6.h
8 (2005), 10 (2010), 11 (2012),
12 (2013), 14 (2015)
GNU/Linux Clang/LLVM 3.4
  GCC 5.1
OS X ? ?

Other GSL implementations

Notes and references

References

[1] Standard C++ Foundation.
[2] Standard C++ Foundation. C++ Core Guidelines.
[3] Microsoft. Guidelines Support Library (GSL).
[4] Bjarne Stroustrup. Writing good C++14 (PDF)Video. CppCon 2015.
[5] Herb Sutter. Writing good C++14… By default (PDF)Video. CppCon 2015.
[6] Gabriel Dos Reis. Contracts for Dependable C++ (PDF) — Video. CppCon 2015.
[7] Bjarne Stroustrup et al. A brief introduction to C++’s model for type- and resource-safety.
[8] Herb Sutter and Neil MacIntosh. Lifetime Safety: Preventing Leaks and Dangling. 21 Sep 2015.

Compiler feature testing

[9] cppreference.com. Feature Test Recommendations.
[10] cppreference.com. Feature testing macros.

C++ features in various Visual C++ compilers

[11] Visual CPP Team. C++0x Core Language Features In VC10: The Table. Microsoft. 6 April 2010.
[12] Visual CPP Team. C++11 Features in Visual C++ 11. Microsoft. 12 September 2011.
[13] Joel Coehoorn. C++11 features in Visual Studio 2012. StackOverflow. 14 September 2011.
[14] Stephan T. Lavavej. C++11/14 Features In Visual Studio 14 CTP3. Microsoft. 21 August 2014.
[15] Stephan T. Lavavej. C++11/14/17 Features In VS 2015 RTM. Microsoft. 19 June 2015.

Appendix

A.1 Extract Boost smart pointers

To obtain a subset of Boost only containing the smart pointers, use the bcp command like:

C:\Libraries\boost\boost_1_51>bin\bcp scoped_ptr.hpp shared_ptr.hpp weak_ptr.hpp make_shared.hpp C:\Libraries\boost-shared_ptr

The smart pointers of Boost 1.51 can be used with VC6.

A.2 GSL Lite test specification

Expects(): Allows a true expression
Ensures(): Allows a true expression
Expects(): Terminates on a false expression
Ensures(): Terminates on a false expression
at(): Terminates access to non-existing C-array elements
at(): Terminates access to non-existing std::array elements (C++11)
at(): Terminates access to non-existing std::vector elements
at(): Terminates access to non-existing std::initializer_list elements (C++11)
at(): Terminates access to non-existing gsl::span elements
at(): Allows access to existing C-array elements
at(): Allows access to existing std::array elements (C++11)
at(): Allows access to existing std::vector elements
at(): Allows access to std::initializer_list elements (C++11)
at(): Allows access to gsl::span elements
byte: Allows construction from integral via static cast (C++11)
byte: Allows construction from integral via byte() (C++11)
byte: Allows construction from integral via to_byte()
byte: Allows conversion to integral via to_integer()
byte: Allows comparison operations
byte: Allows bitwise or operation
byte: Allows bitwise and operation
byte: Allows bitwise x-or operation
byte: Allows bitwise or assignment
byte: Allows bitwise and assignment
byte: Allows bitwise x-or assignment
byte: Allows shift-left operation
byte: Allows shift-right operation
byte: Allows shift-left assignment
byte: Allows shift-right assignment
not_null<>: Disallows default construction (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
not_null<>: Disallows construction from nullptr_t, NULL or 0 (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
not_null<>: Disallows construction from a unique pointer to underlying type (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
not_null<>: Disallows assignment from unrelated pointers (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
not_null<>: Terminates construction from a null pointer value
not_null<>: Terminates construction from related pointer types for null pointer value
not_null<>: Terminates assignment from a null pointer value
not_null<>: Terminates assignment from related pointer types for null pointer value
not_null<>: Allows construction from a non-null underlying pointer
not_null<>: Allows construction from a non-null user-defined ref-counted type
not_null<>: Allows construction from a non-null related pointer
not_null<>: Allows construction from a not_null related pointer type
not_null<>: Allows assignment from a not_null related pointer type
not_null<>: Allows assignment from a non-null bare recast pointer
not_null<>: Allows implicit conversion to underlying type
owner<>: Allows its use as the (pointer) type it stands for
Owner(): Allows its use as the (pointer) type it stands for
span<>: Disallows construction from a temporary value (C++11) (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
span<>: Disallows construction from a C-array of incompatible type (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
span<>: Disallows construction from a std::array of incompatible type (C++11) (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
span<>: Terminates construction from a nullptr and a non-zero size (C++11)
span<>: Terminates construction from two pointers in the wrong order
span<>: Terminates construction from a null pointer and a non-zero size
span<>: Terminates creation of a sub span of the first n elements for n exceeding the span
span<>: Terminates creation of a sub span of the last n elements for n exceeding the span
span<>: Terminates creation of a sub span outside the span
span<>: Terminates access outside the span
span<>: Allows default construction
span<>: Allows construction from a nullptr and a zero size (C++11)
span<>: Allows construction from a l-value (C++11)
span<>: Allows construction from a const l-value (C++11)
span<>: Allows construction from two pointers
span<>: Allows construction from two pointers to const
span<>: Allows construction from a non-null pointer and a size
span<>: Allows construction from a non-null pointer to const and a size
span<>: Allows construction from a temporary pointer and a size
span<>: Allows construction from a temporary pointer to const and a size
span<>: Allows construction from any pointer and a zero size
span<>: Allows construction from a C-array
span<>: Allows construction from a const C-array
span<>: Allows construction from a C-array with size via decay to pointer (potentially dangerous)
span<>: Allows construction from a const C-array with size via decay to pointer (potentially dangerous)
span<>: Allows construction from a std::array<> (C++11)
span<>: Allows construction from a std::array<> with const data (C++11)
span<>: Allows construction from a container (std::vector<>)
span<>: Allows tagged construction from a container (std::vector<>)
span<>: Allows construction from another span of the same type
span<>: Allows construction from another span of a compatible type
span<>: Allows assignment from another span of the same type
span<>: Allows move-construction from another span of the same type (C++11)
span<>: Allows move-assignment from another span of the same type (C++11)
span<>: Allows creation of a sub span of the first n elements
span<>: Allows creation of a sub span of the last n elements
span<>: Allows creation of a sub span starting at a given offset
span<>: Allows creation of a sub span starting at a given offset with a given length
span<>: Allows creation of an empty sub span at full offset
span<>: Allows creation of an empty sub span at full offset with zero length
span<>: Allows forward iteration
span<>: Allows const forward iteration
span<>: Allows reverse iteration
span<>: Allows const reverse iteration
span<>: Allows to observe element via array indexing
span<>: Allows to observe element via call indexing
span<>: Allows to observe element via at()
span<>: Allows to observe element via data()
span<>: Allows to change element via array indexing
span<>: Allows to change element via call indexing
span<>: Allows to change element via at()
span<>: Allows to change element via data()
span<>: Allows to compare equal to another span of the same type
span<>: Allows to compare unequal to another span of the same type
span<>: Allows to compare less than another span of the same type
span<>: Allows to compare less than or equal to another span of the same type
span<>: Allows to compare greater than another span of the same type
span<>: Allows to compare greater than or equal to another span of the same type
span<>: Allows to compare to another span of the same type and different cv-ness (non-standard)
span<>: Allows to compare empty spans as equal
span<>: Allows to test for empty span via empty(), empty case
span<>: Allows to test for empty span via empty(), non-empty case
span<>: Allows to obtain number of elements via size()
span<>: Allows to obtain number of elements via length()
span<>: Allows to obtain number of elements via used_length()
span<>: Allows to obtain number of bytes via bytes()
span<>: Allows to obtain number of bytes via used_bytes()
span<>: Allows to swap with another span of the same type
span<>: Allows to view the elements as read-only bytes
span<>: Allows to view and change the elements as writable bytes
span<>: Allows to view the elements as a span of another type
span<>: Allows to change the elements from a span of another type
span<>: Allows building from two pointers
span<>: Allows building from two const pointers
span<>: Allows building from a non-null pointer and a size
span<>: Allows building from a non-null const pointer and a size
span<>: Allows building from a C-array
span<>: Allows building from a const C-array
span<>: Allows building from a std::array<> (C++11)
span<>: Allows building from a const std::array<> (C++11)
span<>: Allows building from a container (std::vector<>)
span<>: Allows building from a const container (std::vector<>)
string_span: Disallows construction of a string_span from a const C-string and size (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
string_span: ToDo: Disallows construction of a string_span from a const std::string (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
string_span: Allows to create a string_span from a non-const C-string and size
string_span: Allows to create a string_span from a non-const C-array
string_span: Allows to create a string_span from a non-const std::array (C++11)
string_span: Allows to create a string_span from a non-const std::vector
string_span: ToDo: Allows to create a string_span from a non-const std::string
string_span: Allows to create a cstring_span from a const C-string and size
string_span: Allows to create a cstring_span from a const C-array
string_span: Allows to create a cstring_span from a const std::array (C++11)
string_span: Allows to create a cstring_span from a const std::vector
string_span: Allows to create a cstring_span from a const std::string
string_span: Allows to create a cstring_span from a non-const C-string and size
string_span: Allows to create a cstring_span from a non-const C-array
string_span: Allows to create a cstring_span from a non-const std::array (C++11)
string_span: Allows to create a cstring_span from a non-const std::vector
string_span: Allows to create a cstring_span from a non-const std::string
string_span: Allows to create a wstring_span from a non-const C-string and size
string_span: Allows to create a wstring_span from a non-const C-array
string_span: Allows to create a wstring_span from a non-const std::array (C++11)
string_span: Allows to create a wstring_span from a non-const std::vector
string_span: Allows to create a cwstring_span from a non-const C-string and size
string_span: Allows to create a cwstring_span from a non-const C-array
string_span: Allows to create a cwstring_span from a non-const std::array (C++11)
string_span: Allows to create a cwstring_span from a non-const std::vector
string_span: Allows to create a cwstring_span from a const C-string and size
string_span: Allows to create a cwstring_span from a const C-array
string_span: Allows to create a cwstring_span from a const std::array (C++11)
string_span: Allows to create a cwstring_span from a const std::vector
string_span: Allows to compare a string_span with another string_span
string_span: Allows to compare a string_span with a cstring_span
to_string(): Allows to explicitly convert from string_span to std::string
to_string(): Allows to explicitly convert from cstring_span to std::string
to_string(): Allows to explicitly convert from wstring_span to std::wstring
to_string(): Allows to explicitly convert from cwstring_span to std::wstring
ensure_z(): Disallows to build a string_span from a const C-string
ensure_z(): Disallows to build a wstring_span from a const wide C-string
ensure_z(): Allows to build a string_span from a non-const C-string
ensure_z(): Allows to build a cstring_span from a non-const C-string
ensure_z(): Allows to build a cstring_span from a const C-string
ensure_z(): Allows to build a wstring_span from a non-const wide C-string
ensure_z(): Allows to build a cwstring_span from a non-const wide C-string
ensure_z(): Allows to build a cwstring_span from a const wide C-string
ensure_z(): Allows to specify ultimate location of the sentinel and ensure its presence
finally: Allows lambda to run
finally: Allows function with bind
finally: Allows pointer to function
finally: Allows to move final_act
narrow_cast<>: Allows narrowing without value loss
narrow_cast<>: Allows narrowing with value loss
narrow<>(): Allows narrowing without value loss
narrow<>(): Terminates when narrowing with value loss
narrow<>(): Terminates when narrowing with sign loss