status_value is a single-file header-only library for objects that represent a status and an optional value. It is intended for use with C++11 and later. There is a separate variant for use with C++98 and later.
The library is based on the proposal for status_value [1]. Please read On proposed status_value by Andrey Upadyshev [5] and consider if you truly want to use this library.
Contents
- Example usage
- In a nutshell
- License
- Dependencies
- Installation
- Synopsis
- Comparison with like types
- Reported to work with
- Implementation notes
- Notes and references
- Appendix
#include "nonstd/status_value.hpp"
#include <cstdlib>
#include <iostream>
#include <string>
using namespace nonstd;
using namespace std::literals;
auto to_int( char const * const text ) -> status_value<std::string, int>
{
char * pos = nullptr;
auto value = strtol( text, &pos, 0 );
if ( pos != text ) return { "Excellent", value };
else return { "'"s + text + "' isn't a number" };
}
int main( int argc, char * argv[] )
{
auto text = argc > 1 ? argv[1] : "42";
auto svi = to_int( text );
if ( svi ) std::cout << svi.status() << ": '" << text << "' is " << *svi << ", ";
else std::cout << "Error: " << svi.status();
}prompt> g++ -std=c++14 -Wall -I../include -o 01-basic.exe 01-basic.cpp && 01-basic.exe 123 && 01-basic.exe abc
Excellent: '123' is 123, Error: 'abc' isn't a number
status_value is a single-file header-only library to represent objects that contain a status and an optional value. The library is an implementation of the proposal for std::status_value [1,2] for use with C++11 and later.
Features and properties of status_value are ease of installation (single header), construction of a status, or a status and a value from a value that is convertible to the underlying type, move-construction from another status_value of the same type, testing for the presence of a value, operators and method value() for checked access to the value and access to the status.
Not provided are copy-construction of a status_value (by design), ... .
For more examples, see [1].
status_value is distributed under the Boost Software License.
status_value has no other dependencies than the C++ standard library.
status_value is a single-file header-only library. Put status_value.hpp directly into the project source tree or somewhere reachable from your project.
Contents
If the compiler supports __has_include(), status_value lite supports the tweak header mechanism. Provide your tweak header as nonstd/status_value.tweak.hpp in a folder in the include-search-path. In the tweak header, provide definitions as documented below, like #define nsstsv_CPLUSPLUS 201103L.
-Dnsstsv_CPLUSPLUS=199711L
Define this macro to override the auto-detection of the supported C++ standard, if your compiler does not set the __cpluplus macro correctly.
-Dnsstsv_CONFIG_NO_EXCEPTIONS=0
Define this to 1 if you want to compile without exceptions. If not defined, the header tries and detect if exceptions have been disabled (e.g. via -fno-exceptions). Disabling exceptions will force contract violation to call std::abort(). Default is 0.
-Dnsstsv_CONFIG_CONFIRMS_COMPILATION_ERRORS=0
Define this macro to 1 to experience the by-design compile-time errors of the library in the test suite. Default is 0.
| Kind | Method | Result |
|---|---|---|
| Type |
template<typename S> class bad_status_value_access; |
|
| Construction | bad_status_value_access( S s ) | move-construct from status |
| Type |
template<typename S, typename V> class status_value; |
|
| Construction | status_value() = delete | disallow default construction |
| status_value( status_value && other ) | move-construct from other | |
| status_value( status_type const & s ) | copy-construct from status | |
| status_value( status_type const & s, value_type && v ) | copy-construct from status, move construct from value |
|
| status_value( status_type const & s, value_type const & v ) | copy-construct from status and value | |
| Destruction | ~status_value() | status, value destroyed if present |
| Observers | operator bool() const | true if contains value |
| bool has_value() const | true if contains value | |
| status_type const & status() const | the status | |
| value_type const & value() const | the value (const ref); see note 1 |
|
| value_type & value() | the value (non-const ref); see note 1 |
|
| value_type const & operator *() const | the value (const ref); see note 1 |
|
| value_type & operator *() | the value (non-const ref); see note 1 |
|
| value_type const & operator ->() const | the element value (const ref); see note 1 |
|
| value_type & operator ->() | the element value (non-const ref); see note 1 |
Note 1: checked access: if no content, throws bad_status_value_access containing status value.
| Feature | std::optional | std::expected | nonstd::status_value |
|---|---|---|---|
| More information | see [4] | see [3] | this work |
| C++98 | – note 2 | – | – note 4 |
| C++11 | – | – note 3 | ✓ |
| C++14 | – | – | ✓ |
| C++17 | ✓ | – | ✓ |
| DefaultConstructible | ✓ | ✓ | ✓ |
| In-place construction | ✓ | ✓ | – |
| Literal type | ✓ | ✓ | – |
| Disengaged information | – | ✓ | ✓ status |
| Vary disengaged type | – | ✓ | ✓ status |
| Engaged nonuse throws | – | – | – |
| Disengaged use throws | ✓ value() | ✓ value() | ✓ all |
| Proxy (rel.ops) | ✓ | ✓ | – |
| References | ✓ | – | – |
| Chained visitor(s) | – | ✓ | – |
Note 2: optional lite - Optional (nullable) objects for C++98 and later.
Note 3: expected lite - Expected objects for C++11 and later.
Note 4: This project provides a variant of status_value for use with C++98 and later.
status_value is reported to work with the following compilers:
- Visual VC14 (VS2015)
- GNUC 5.2.0 with -std=c++11, -std=c++14, -std=c++1y
- clang 3.6, 3.7 with -std=c++11, -std=c++14 (on Travis)
[1] Lawrence Crowl and Chris Mysen. p0262 - A Class for Status and Optional Value (latest), 14 February 2016. N4233, 10 October 2014.
[2] Lawrence Crowl. p0157 - Handling Disappointment in C++ (latest), 7 July 2015.
[3] Vicente J. Botet Escriba. p0323 - A proposal to add a utility class to represent expected object (latest) (PDF). (r6, r5, r4, r3, r2, r1, r0, draft).
[4] Fernando Cacciola and Andrzej Krzemieński. N3793 - A proposal to add a utility class to represent optional objects (Revision 5). 03 October 2013. N3672 r4, N3527 r3, N3406 r2, N1878 r1, N3966 - Fixes for optional objects.
[5] Andrey Upadyshev. On proposed status_value. 20 January 2022.
The version of status-value lite is available via tag [.version]. The following tags are available for information on the compiler and on the C++ standard library used: [.compiler], [.stdc++], [.stdlanguage] and [.stdlibrary].
click to expand
status_value<>: Disallows default construction
status_value<>: Allows construction from only status
status_value<>: Allows construction from status and non-default-constructible value
status_value<>: Allows construction from copied status and moved value
status_value<>: Allows construction from copied status and copied value
status_value<>: Disallows copy-construction from other status_value of the same type
status_value<>: Allows move-construction from other status_value of the same type
status_value<>: Allows to observe its status
status_value<>: Allows to observe the presence of a value (has_value())
status_value<>: Allows to observe the presence of a value (operator bool)
status_value<>: Allows to observe its value (value())
status_value<>: Allows to observe its value (operator*)
status_value<>: Allows to observe its value (operator->)
status_value<>: Throws when observing non-engaged (value())
status_value<>: Throws when observing non-engaged (operator*())
status_value<>: Throws when observing non-engaged (operator->())
tweak header: reads tweak header if supported [tweak]