Single-header libraries

Corrade functionality exposed in easy-to-integrate single-header libraries.

Selected Corrade functionality is also available as single-header libraries, with the goal of providing significantly smaller, faster-compiling and generally better alternatives to commonly available implementations while being as easy as possible to integrate into existing projects. The general rule is having preprocessed size not exceeding 10k lines — to put this in perspective, not even the <string> header can fit there.

So far, the following classes, libraries and utility headers are provided as single-header libs, all of them available for download through the magnum-singles repository. Each of them is automatically generated from unmodified Corrade sources using the builtin single-header generator tool.

Class, library or headerSingle-header version
Containers::ArrayView,
Containers::ArrayView<void>,
Containers::ArrayView<const void>,
Containers::StaticArrayView		CorradeArrayView.h
Containers::StridedArrayView,
Containers::StridedArrayView<dimensions, void>,
Containers::StridedArrayView<dimensions, const void>		CorradeStridedArrayView.h, depends on CorradeArrayView.h
Containers::Array,
Containers::StaticArray		CorradeArray.h, depends on CorradeArrayView.h
Growable APIs for Containers::ArrayCorradeGrowableArray.h, depends on CorradeArray.h
Containers::EnumSetCorradeEnumSet.h
Containers::FunctionCorradeFunction.h
Containers::OptionalCorradeOptional.h
Containers::PairCorradePointer.h
Containers::PointerCorradePointer.h
Containers::ReferenceCorradeReference.h
Containers::ScopeGuardCorradeScopeGuard.h
Containers::String,
Containers::StringView,
Containers::MutableStringView		CorradeString.hpp, depends on CorradeEnumSet.h; the implementation additionally depends on CorradeCpu.hpp and CorradePair.h
Containers::TripleCorradePointer.h
Corrade::CpuCorradeCpu.hpp
Corrade/Utility/StlForwardArray.hCorradeStlForwardArray.h
Corrade/Utility/StlForwardString.hCorradeStlForwardString.h
Corrade/Utility/StlForwardTuple.hCorradeStlForwardTuple.h
Corrade/Utility/StlForwardVector.hCorradeStlForwardVector.h
Corrade/Utility/StlMath.hCorradeStlMath.h

Behavior

To keep file size small, the single-header versions have all the comments and documentation stripped away, except for a short description and a single top-level license block, containing also credit information for all contributors. Documentation is meant to be retrieved online, the wrapping namespaces and all API naming stay completely the same as when using Corrade directly.

The files retain their own include guards, which makes it possible to mix them together. However, when combining more than one, make sure to have all files from the same revision to avoid API mismatches. The concrete revision that was used to generate each library is printed in its header comment.

There are two kinds of libraries, distinguished with file extension:

  • The *.h extension denotes libraries that have everything inline in the header. A simple #include is all you need.

  • The *.hpp extension denotes libraries that have a separate implementation part with non-inline definitions. Desired usage is to build the implementation just once by defining a macro before including the library header:

    #define CORRADE_LIBRARYNAME_IMPLEMENTATION
#include <CorradeLibraryName.hpp>

    In all other files the library is meant to be included without defining the macro. Thanks to this approach, complex implementation details don't inflate compile times while still keeping the library as a single file.

Customization points

All headers above are created with CORRADE_STANDARD_ASSERT enabled to avoid dragging the whole Utility::Debug class along. Apart from that, every header includes only the assertion macros it actually needs and it's possible to override them by providing e.g. your own #define CORRADE_ASSERT before including the file. See the Corrade/Utility/Assert.h file documentation for more information.

Some files contain additional disabled-by-default functionality (for example the STL compatibility of Containers::Pointer), see documentation of each class, library or header for detailed library-specific behavior.