scope-lite - C++ standard libraries extensions, version 3: Generic scope and RAII Wrapper.

Contents

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

Example usage

#include "nonstd/scope.hpp"

using namespace nonstd;

int count = 0;

namespace on { void exit() { ++count; } }

int main()
{
    { auto guard = make_scope_exit(  on::exit ); } // note: on::exit w/o &
    { auto guard = make_scope_exit( &on::exit ); } // note: &on::exit

    return count;
}

Note: do not let stdlib's global function on_exit() bite you. Thanks to Björn Fahller.

Compile and run

$ g++ -std=c++11 -Wall -I../include -o 01-basic 01-basic.cpp && ./01-basic || echo $?
2

In a nutshell

scope lite is a single-file header-only library to provide C++ standard libraries extensions, version 3 for use with C++98 and later. If available, the standard library is used, unless configured otherwise.

Features and properties of scope lite are ease of installation (single header), freedom of dependencies other than the standard library. With C++20, scope guards can be constexpr. This is a configurable extension with respect to the proposal's specification.

Limitations of scope lite are ... .

License

scope lite is distributed under the Boost Software License.

Dependencies

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

Installation

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

Synopsis

Contents
Documentation of C++ standard libraries extensions, version 3
Non-standard extensions
Configuration

Documentation of C++ standard libraries extensions, version 3

Depending on the compiler and C++ standard used, scope lite behaves less or more like the standard's version. To get an idea of the capabilities of scope lite with your configuration, look at the output of the tests, issuing scope-main.t --pass @. For the standard's documentation, see C++ standard libraries extensions, version 3.

Non-standard extensions

constexpr scope guards

With C++20, scope guards can be constexpr. This is a configurable extension with respect to the proposal's specification, see section Configuration, Disable constexpr extension.

Here is an example of constexpr scope guards on Compiler Explorer.

Configuration

Tweak header

If the compiler supports __has_include(), scope lite supports the tweak header mechanism. Provide your tweak header as nonstd/scope.tweak.hpp in a folder in the include-search-path. In the tweak header, provide definitions as documented below, like #define scope_CPLUSPLUS 201103L.

Standard selection macro

-Dscope_CPLUSPLUS=199711L
Define this macro to override the auto-detection of the supported C++ standard, if your compiler does not set the __cplusplus macro correctly.

Select standard library version or scope lite

At default, scope lite uses the standard library's version if it is available and lets you use it via namespace nonstd. You can however override this default and explicitly request to use the standard's version or scope lite's header via the following macros.

-Dscope_CONFIG_SELECT_SCOPE=scope_SCOPE_DEFAULT
Define this to scope_SCOPE_STD to select standard's version. Define this to scope_SCOPE_NONSTD to select scope lite. Default is undefined, which has the same effect as defining to scope_SCOPE_DEFAULT.

Disable extensions

-Dscope_CONFIG_NO_EXTENSIONS=0
Define this to 1 if you want to compile without extensions. Default is undefined.

Disable constexpr extension

-Dscope_CONFIG_NO_CONSTEXPR=0
Define this to 1 if you want to adhere to C++ standard libraries extensions, version 3 and not use constexpr scope guards. Default is undefined.

Reported to work with

TBD

Other implementations of scope

• Example implementation. Peter Sommerlad. 2018.
• scope_guard – A modern C++11 scope guard that is easy to use but hard to misuse. Ricardo Abreu.

Notes and references

Interface and specification

• Cppreference. C++ standard libraries extensions, version 3

Proposals

• p0052 - Generic scope and RAII Wrapper for the Standard Library. Peter Sommerlad and Andrew L. Sandoval with contributions by Eric Niebler and Daniel Krügler

Appendix

The test program provides information on the compiler, the C++ language and library capabilities and the tests performed.

A.1 Compile-time information

The version of scope 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 scope lite test specification

click to expand

scope_exit: exit function is called at end of scope
scope_exit: exit function is called at end of scope (lambda)
scope_exit: exit function is called at end of scope (constexpr) [extension]
scope_exit: exit function is called when an exception occurs
scope_exit: exit function is not called at end of scope when released
scope_fail: exit function is called when an exception occurs
scope_fail: exit function is called when an exception occurs (lambda)
scope_fail: exit function is not called when no exception occurs
scope_fail: exit function is not called when no exception occurs (constexpr) [extension]
scope_fail: exit function is not called when released
scope_success: exit function is called when no exception occurs
scope_success: exit function is called when no exception occurs (lambda)
scope_success: exit function is called when no exception occurs (constexpr) [extension]
scope_success: exit function is not called when an exception occurs
scope_success: exit function is not called when released
scope_success: exit function can throw (lambda)
unique_resource: a successfully acquired resource is deleted
unique_resource: an unsuccessfully acquired resource is not deleted
unique_resource: move construction moves the managed resource and the deleter from the give one's [move-construction]
unique_resource: assignment replaces the managed resource and the deleter with the give one's [move-assignment]
unique_resource: reset() executes deleter
unique_resource: reset(resource) deletes original resource and replaces it with the given one
unique_resource: release() releases the ownership and prevents execution of deleter
unique_resource: get() provides the underlying resource handle
unique_resource: get_deleter() provides the deleter used for disposing of the managed resource
unique_resource: op*() provides the pointee if the resource handle is a pointer
unique_resource: op->() provides the pointee if the resource handle is a pointer 
unique_resource: [move-construction][resource-copy-ctor-throws]
unique_resource: [move-construction][deleter-copy-ctor-throws]
tweak header: reads tweak header if supported [tweak]