status_value: A class for status and optional value for C++11 and later

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

Example usage

#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();
}

Compile and run

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

In a nutshell

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].

License

status_value is distributed under the Boost Software License.

Dependencies

status_value has no other dependencies than the C++ standard library.

Installation

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.

Synopsis

Contents

• Configuration macros
• Interface of status_value

Configuration macros

Tweak header

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.

Standard selection macro

-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.

Disable exceptions

-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.

Enable compilation errors

-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.

Interface of status_value

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.

Comparison with like types

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.

Reported to work with

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)

Implementation notes

Notes and references

[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.

Appendix

A.1 Compile-time information

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].

A.2 Status_value test specification

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]