Containers: added enumSetDebugOutput() helper.

Helps with implementing printing of EnumSet types to debug output
by reusing existing implementation of debug output for the underlying
enum type.

Doxyfile

@@ -785,6 +785,7 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = *.cpp \
                          *.h \
+                         *.hpp \
                          *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should

doc/corrade-changelog.dox

@@ -42,6 +42,8 @@ namespace Corrade {
 -   New @ref Containers::arrayCast() function to `reinterpret_cast` arrays with
     correct size recalculation
 -   Added XOR operators to @ref Containers::EnumSet
+-   New @ref Containers::enumSetDebugOutput() utility to help with implementing
+    debug operators for @ref Containers::EnumSet types
 
 ### PluginManager library
 

src/Corrade/Containers/CMakeLists.txt

@@ -28,6 +28,7 @@ set(CorradeContainers_HEADERS
     ArrayView.h
     Containers.h
     EnumSet.h
+    EnumSet.hpp
     LinkedList.h
     StaticArray.h
     Tags.h)

src/Corrade/Containers/EnumSet.h

@@ -102,6 +102,8 @@ template<class T> class Object {
         typedef Implementation::ObjectFlags Flags;
 };
 @endcode
+
+@see @ref enumSetDebugOutput()
 */
 #ifdef DOXYGEN_GENERATING_OUTPUT
 template<class T, typename std::underlying_type<T>::type fullValue = typename std::underlying_type<T>::type(~0)>

src/Corrade/Containers/EnumSet.hpp

@@ -0,0 +1,110 @@
+#ifndef Corrade_Containers_EnumSet_hpp
+#define Corrade_Containers_EnumSet_hpp
+/*
+    This file is part of Corrade.
+
+    Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
+                2017 Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+/** @file
+ * @brief Function @ref Corrade::Containers::enumSetDebugOutput()
+ */
+
+#include "Corrade/Containers/EnumSet.h"
+#include "Corrade/Utility/Debug.h"
+
+namespace Corrade { namespace Containers {
+
+/** @relatedalso EnumSet
+@brief Print enum set to debug output
+@param debug    Debug output
+@param value    Value to be printed
+@param enums    Recognized enum values
+@param empty    What to print in case of an empty enum set
+
+Assuming underlying enum type has already implemented `operator<<` for
+@ref Utility::Debug, this function is able to print value of given enum set.
+Example usage:
+@code
+enum class Feature: unsigned int {
+    Fast = 1 << 0,
+    Cheap = 1 << 1,
+    Tested = 1 << 2,
+    Popular = 1 << 3
+};
+
+// already defined to print values as e.g. Feature::Fast and Features(0xabcd)
+// for unknown values
+Utility::Debug& operator<<(Utility::Debug&, Feature);
+
+typedef EnumSet<Feature> Features;
+CORRADE_ENUMSET_OPERATORS(Features)
+
+Utility::Debug& operator<<(Utility::Debug& debug, Features value) {
+    return enumSetDebugOutput(debug, value, "Features{}", {
+        Feature::Fast,
+        Feature::Cheap,
+        Feature::Tested,
+        Feature::Popular});
+}
+
+// prints Feature::Fast|Feature::Cheap
+Utility::Debug{} << Feature::Fast|Feature::Cheap;
+
+// prints Feature::Popular|Feature(0xdead)
+Utility::Debug{} << Feature::Popular|Feature(0xdead000);
+
+// prints Features{}
+Utility::Debug{} << Features{};
+@endcode
+
+@attention This function assumes that the recognized values have unique bits
+    set. The output is undefined if more than one value share the same bit.
+*/
+template<class T, typename std::underlying_type<T>::type fullValue> Utility::Debug& enumSetDebugOutput(Utility::Debug& debug, EnumSet<T, fullValue> value, const char* empty, std::initializer_list<T> enums) {
+    /* Print the empty value in case there is nothing */
+    if(!value) return debug << empty;
+
+    /* Print known values, if set, and strip them out of the value */
+    bool separate = false;
+    for(const T e: enums) if(value >= e) {
+        if(separate) debug << Utility::Debug::nospace << "|" << Utility::Debug::nospace;
+        else separate = true;
+        debug << e;
+
+        /* Avoid stripping out the unknown bits by the EnumSet operator~ */
+        value &= T(~typename std::underlying_type<T>::type(e));
+    }
+
+    /* If there are leftover, pass them to the original debug operator and
+       expect it will print them as raw value */
+    if(value) {
+        if(separate) debug << Utility::Debug::nospace << "|" << Utility::Debug::nospace;
+        debug << T(typename std::underlying_type<T>::type(value));
+    }
+
+    return debug;
+}
+
+}}
+
+#endif

src/Corrade/Containers/Test/EnumSetTest.cpp

@@ -23,7 +23,9 @@
     DEALINGS IN THE SOFTWARE.
 */
 
-#include "Corrade/Containers/EnumSet.h"
+#include <sstream>
+
+#include "Corrade/Containers/EnumSet.hpp"
 #include "Corrade/TestSuite/Tester.h"
 
 namespace Corrade { namespace Containers { namespace Test {
@@ -40,19 +42,46 @@ struct EnumSetTest: TestSuite::Tester {
     void operatorBool();
     void operatorInverse();
     void compare();
+
+    void debug();
 };
 
+namespace {
+
 enum class Feature: int {
     Fast = 1 << 0,
     Cheap = 1 << 1,
     Tested = 1 << 2,
     Popular = 1 << 3
 };
 
+Utility::Debug& operator<<(Utility::Debug& debug, Feature value) {
+    switch(value) {
+        #define _c(value) case Feature::value: return debug << "Feature::" #value;
+        _c(Fast)
+        _c(Cheap)
+        _c(Tested)
+        _c(Popular)
+        #undef _c
+    }
+
+    return debug << "Feature(" << Utility::Debug::nospace << reinterpret_cast<void*>(int(value)) << Utility::Debug::nospace << ")";
+}
+
 typedef EnumSet<Feature, 15> Features;
 
 CORRADE_ENUMSET_OPERATORS(Features)
 
+Utility::Debug& operator<<(Utility::Debug& debug, Features value) {
+    return enumSetDebugOutput(debug, value, "Features{}", {
+        Feature::Fast,
+        Feature::Cheap,
+        Feature::Tested,
+        Feature::Popular});
+}
+
+}
+
 EnumSetTest::EnumSetTest() {
     addTests({&EnumSetTest::construct,
               &EnumSetTest::constructNoInit,
@@ -62,7 +91,9 @@ EnumSetTest::EnumSetTest() {
               &EnumSetTest::operatorXor,
               &EnumSetTest::operatorBool,
               &EnumSetTest::operatorInverse,
-              &EnumSetTest::compare});
+              &EnumSetTest::compare,
+
+              &EnumSetTest::debug});
 }
 
 void EnumSetTest::construct() {
@@ -166,6 +197,13 @@ void EnumSetTest::compare() {
     CORRADE_VERIFY(!(features >= (Feature::Popular|Feature::Fast|Feature::Cheap|Feature::Tested)));
 }
 
+void EnumSetTest::debug() {
+    std::stringstream out;
+
+    Utility::Debug{&out} << Features{} << (Feature::Fast|Feature::Cheap) << (Feature(0xdead000)|Feature::Popular);
+    CORRADE_COMPARE(out.str(), "Features{} Feature::Fast|Feature::Cheap Feature::Popular|Feature(0xdead000)\n");
+}
+
 }}}
 
 CORRADE_TEST_MAIN(Corrade::Containers::Test::EnumSetTest)