span lite - A single-file header-only version of a C++20-like span for C++98, C++11 and later

Contents

Example usage
In a nutshell
License
Dependencies
Installation and use
Synopsis
Reported to work with
Building the tests
Other implementations of span
Notes and references
Appendix

Example usage

#include "nonstd/span.hpp"
#include <array>
#include <vector>
#include <iostream>

std::ptrdiff_t size( nonstd::span<const int> spn )
{
    return spn.size();
}

int main()
{
    int arr[] = { 1, };
    
    std::cout << 
        "C-array:" << size( arr ) <<
        " array:"  << size( std::array <int, 2>{ 1, 2, } ) <<
        " vector:" << size( std::vector<int   >{ 1, 2, 3, } );
}

Compile and run

prompt> g++ -std=c++11 -Wall -I../include/ -o 01-basic.exe 01-basic.cpp && 01-basic.exe
C-array:1 array:2 vector:3

In a nutshell

span lite is a single-file header-only library to provide a bounds-safe view for sequences of objects. The library provides a C++20-like span for use with C++98 and later. If available, std::span is used, unless configured otherwise.

Features and properties of span lite are ease of installation (single header), freedom of dependencies other than the standard library. To compensate for the class template argument deduction that is missing from pre-C++17 compilers, nonstd::span can provide make_span functions. See configuration.

License

span lite uses the MIT license.

Dependencies

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

Installation and use

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

Synopsis

Contents
Documentation of std::span
Non-standard extensions
Configuration

Documentation of `std::span`

Depending on the compiler and C++-standard used, nonstd::span behaves less or more like std::span. To get an idea of the capabilities of nonstd::span with your configuration, look at the output of the tests, issuing span-lite.t --pass @. For std::span, see its documentation at cppreference.

Non-standard extensions

Construct from container

To construct a span from a container with compilers that cannot constrain such a single-parameter constructor to containers, span lite provides a constructor that takes an additional parameter of type with_container_t. Use with_container as value for this parameter.

`make_span`

span lite can provide make_span creator functions to compensate for the class template argument deduction that is missing from pre-C++17 compilers. See the table below and section configuration.

Kind	std	Function or method
Types		with_container_t type to disambiguate below constructors
Objects		with_container value to disambiguate below constructors
Methods		template<class Container> constexpr span(with_container_t, Container & cont)
		template<class Container> constexpr span(with_container_t, Container const & cont)

Free functions		macro `span_CONFIG_PROVIDE_MAKE_SPAN`
		template<class T> constexpr span<T> make_span(T * first, T * last) noexcept
		template<class T> constexpr span<T> make_span(T * ptr, index_t count) noexcept
		template<class T, size_t N> constexpr span<T,N> make_span(T (&arr)[N]) noexcept
	>= C++11	template<class T, size_t N> constexpr span<T,N> make_span(std::array<T,N> & arr) noexcept
	>= C++11	template<class T, size_t N> constexpr span<const T,N> make_span(std::array<T,N > const & arr) noexcept
	>= C++11	template<class Container> constexpr auto make_span(Container & cont) -> span<typename Container::value_type> noexcept
	>= C++11	template<class Container> constexpr auto make_span(Container const & cont) -> span<const typename Container::value_type> noexcept
	< C++11	template<class Container> span<typename Container::value_type> make_span( with_container_t, Container & cont )
	< C++11	template<class Container> span<const typename Container::value_type> make_span( with_container_t, Container const & cont )
	< C++11	template<class T, Allocator> span<T> make_span(std::vector<T, Allocator> & cont)
	< C++11	template<class T, Allocator> span<const T> make_span(std::vector<T, Allocator> const & cont)

Configuration

Select `std::span` or `nonstd::span`

At default, span lite uses std::span if it is available and lets you use it via namespace nonstd. You can however override this default and explicitly request to use std::span as nonstd::span or use span lite's nonstd::span via the following macros.

-Dspan_CONFIG_SELECT_STD_SPAN=1
Define this to 1 to select std::span as nonstd::span. Default is undefined.

-Dspan_CONFIG_SELECT_NONSTD_SPAN=1
Define this to 1 to select span lite's nonstd::span. Default is undefined.

Provide `make_span` functions

-Dspan_CONFIG_PROVIDE_MAKE_SPAN=1
Define this to 1 to provide creator functions nonstd::make_span. Default is undefined.

Contract violation response macros

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

-Dspan_CONFIG_CONTRACT_LEVEL_ON
Define this macro to include both span_EXPECTS and span_ENSURES in the code. This is the default case.

-Dspan_CONFIG_CONTRACT_LEVEL_OFF
Define this macro to exclude both span_EXPECTS and span_ENSURES from the code.

-Dspan_CONFIG_CONTRACT_LEVEL_EXPECTS_ONLY
Define this macro to include span_EXPECTS in the code and exclude span_ENSURES from the code.

-Dspan_CONFIG_CONTRACT_LEVEL_ENSURES_ONLY
Define this macro to exclude span_EXPECTS from the code and include span_ENSURES in the code.

-Dspan_CONFIG_CONTRACT_VIOLATION_TERMINATES
Define this macro to call std::terminate() on a contract violation in span_EXPECTS, span_ENSURES. This is the default case.

-Dspan_CONFIG_CONTRACT_VIOLATION_THROWS
Define this macro to throw a std::runtime_exception-derived exception nonstd::span_lite::details::fail_fast instead of calling std::terminate() on a contract violation in span_EXPECTS, span_ENSURES and throw a std::exception-derived exception narrowing_error on discarding information in narrow.

Reported to work with

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

OS	Compiler	Where	Versions
GNU/Linux	Clang/LLVM	Travis	3.5.0, 3.6.2, 3.7.1, 3.8.0, 3.9.1, 4.0.1
	GCC	Travis	5.5.0, 6.4.0, 7.3.0
OS X	?	Local	?
Windows	Clang/LLVM	Local	6.0.0
	GCC	Local	7.2.0
	Visual C++ (Visual Studio)	Local	8 (2005), 10 (2010), 11 (2012), 12 (2013), 14 (2015), 15 (2017)
	Visual C++ (Visual Studio)	AppVeyor	10 (2010), 11 (2012), 12 (2013), 14 (2015), 15 (2017)

Building the tests

To build the tests you need:

CMake, version 3.0 or later to be installed and in your PATH.
A suitable compiler.

The lest test framework is included in the test folder.

The following steps assume that the span lite source code has been cloned into a directory named ./span-lite.

Create a directory for the build outputs.
```
 cd ./span-lite
 md build && cd build
```
Configure CMake to use the compiler of your choice (run cmake --help for a list).
```
 cmake -G "Unix Makefiles" ..
```
Optional. You can control above configuration through the following options:

-DSPAN_LITE_OPT_BUILD_TESTS=ON: build the tests for span, default on -DSPAN_LITE_OPT_BUILD_EXAMPLES=OFF: build the examples, default off
Build the test suite.
```
 cmake --build .
```
Run the test suite.
```
 ctest -V
```

All tests should pass, indicating your platform is supported and you are ready to use span lite.

Other implementations of span

gsl-lite span.
Microsoft GSL span.
Google Abseil span.
Search span c++ on GitHub.

Notes and references

Interface and specification

Presentations

Proposals

Appendix

A.1 span lite test specification

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 to default-construct
span<>: Allows to construct from a nullptr and a zero size (C++11)
span<>: Allows to construct from two pointers
span<>: Allows to construct from two pointers to const
span<>: Allows to construct from a non-null pointer and a size
span<>: Allows to construct from a non-null pointer to const and a size
span<>: Allows to construct from a temporary pointer and a size
span<>: Allows to construct from a temporary pointer to const and a size
span<>: Allows to construct from any pointer and a zero size
span<>: Allows to construct from a C-array
span<>: Allows to construct from a const C-array
span<>: Allows to construct from a C-array with size via decay to pointer (potentially dangerous)
span<>: Allows to construct from a const C-array with size via decay to pointer (potentially dangerous)
span<>: Allows to construct from a std::array<> (C++11)
span<>: Allows to construct from a std::array<> with const data (C++11)
span<>: Allows to construct from a container (std::vector<>)
span<>: Allows to tag-construct from a container (std::vector<>)
span<>: Allows to tag-construct from a const container (std::vector<>)
span<>: Allows to copy-construct from another span of the same type
span<>: Allows to copy-construct from another span of a compatible type
span<>: Allows to copy-construct from a temporary span of the same type (C++11)
span<>: Allows to copy-assign from another span of the same type
span<>: Allows to copy-assign from a temporary span of the same type (C++11)
span<>: Allows to create a sub span of the first n elements
span<>: Allows to create a sub span of the last n elements
span<>: Allows to create a sub span starting at a given offset
span<>: Allows to create a sub span starting at a given offset with a given length
span<>: Allows forward iteration
span<>: Allows const forward iteration
span<>: Allows reverse iteration
span<>: Allows const reverse iteration
span<>: Allows to observe an element via array indexing
span<>: Allows to observe an element via call indexing
span<>: Allows to observe an element via data()
span<>: Allows to change an element via array indexing
span<>: Allows to change an element via call indexing
span<>: Allows to change an 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 the number of elements via size()
span<>: Allows to obtain the number of bytes via size_bytes()
span<>: Allows to view the elements as read-only bytes
span<>: Allows to view and change the elements as writable bytes
make_span(): Allows building from two pointers
make_span(): Allows building from two const pointers
make_span(): Allows building from a non-null pointer and a size
make_span(): Allows building from a non-null const pointer and a size
make_span(): Allows building from a C-array
make_span(): Allows building from a const C-array
make_span(): Allows building from a std::array<> (C++11)
make_span(): Allows building from a const std::array<> (C++11)
make_span(): Allows building from a container (std::vector<>)
make_span(): Allows building from a const container (std::vector<>)
make_span(): Allows building from a container (with_container_t, std::vector<>)
make_span(): Allows building from a const container (with_container_t, std::vector<>)

vietjtnguyen / span-lite Goto Github PK

span-lite's Introduction

span lite - A single-file header-only version of a C++20-like span for C++98, C++11 and later

Example usage

Compile and run

In a nutshell

License

Dependencies

Installation and use

Synopsis

Documentation of std::span

Non-standard extensions

Construct from container

make_span

Configuration

Select std::span or nonstd::span

Provide make_span functions

Contract violation response macros

Reported to work with

Building the tests

Other implementations of span

Notes and references

Appendix

A.1 span lite test specification

span-lite's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org

Documentation of `std::span`

`make_span`

Select `std::span` or `nonstd::span`

Provide `make_span` functions