Containers: C++17 structured bindings for fixed-size containers.

Even with the forward declaration header added in the previous commit,
to avoid having to include <utility> the std::tuple_size and
std::tuple_element specializations are put into a separate header.

Co-authored-by: Stanislaw Halik <sthalik@misaki.pl>

doc/corrade-changelog.dox

@@ -130,6 +130,11 @@ namespace Corrade {
 -   Added a family of @ref Containers::arrayInsert(),
     @ref Containers::arrayRemove() and @ref Containers::arrayRemoveUnordered()
     functions for arbitrary insertion into and deletion from growable arrays
+-   Support for C++17 structured bindings for @ref Containers::Pair,
+    @ref Containers::Triple, @ref Containers::StaticArray,
+    @ref Containers::StaticArrayView and @ref Containers::StridedDimensions.
+    See also [mosra/corrade#127](https://github.com/mosra/corrade/pull/127) and
+    [mosra/corrade#157](https://github.com/mosra/corrade/issues/157).
 
 @subsubsection corrade-changelog-latest-new-pluginmanager PluginManager library
 

doc/snippets/CMakeLists.txt

@@ -71,6 +71,7 @@ if(NOT CMAKE_CXX_FLAGS MATCHES "-std=")
        (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS "19.10"))
         add_library(snippets-cpp17 STATIC ${EXCLUDE_FROM_ALL_IF_TEST_TARGET}
             Corrade-cpp17.cpp
+            Containers-cpp17.cpp
             Containers-stl17.cpp)
         target_link_libraries(snippets-cpp17 PRIVATE CorradeUtility)
         set_target_properties(snippets-cpp17 PROPERTIES

doc/snippets/Containers-cpp17.cpp

@@ -0,0 +1,105 @@
+/*
+    This file is part of Corrade.
+
+    Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
+                2017, 2018, 2019, 2020, 2021, 2022, 2023
+              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.
+*/
+
+#include "Corrade/Containers/Pair.h"
+#include "Corrade/Containers/StaticArray.h"
+#include "Corrade/Containers/StridedDimensions.h"
+#include "Corrade/Containers/StructuredBindings.h"
+#include "Corrade/Containers/Triple.h"
+
+#define DOXYGEN_ELLIPSIS(...) __VA_ARGS__
+
+using namespace Corrade;
+
+int main() {
+{
+/* The include is already above, so doing it again here should be harmless */
+/* [Pair-structured-bindings] */
+#include <Corrade/Containers/StructuredBindings.h>
+
+DOXYGEN_ELLIPSIS()
+
+auto [first, second] = Containers::pair(42, 3.14f);
+/* [Pair-structured-bindings] */
+static_cast<void>(first);
+static_cast<void>(second);
+}
+
+{
+/* The include is already above, so doing it again here should be harmless */
+/* [StaticArray-structured-bindings] */
+#include <Corrade/Containers/StructuredBindings.h>
+
+DOXYGEN_ELLIPSIS()
+
+auto [a, b, c] = Containers::Array3<int>{7, 13, 29};
+/* [StaticArray-structured-bindings] */
+static_cast<void>(a);
+static_cast<void>(b);
+static_cast<void>(c);
+}
+
+{
+/* The include is already above, so doing it again here should be harmless */
+/* [StaticArrayView-structured-bindings] */
+#include <Corrade/Containers/StructuredBindings.h>
+
+DOXYGEN_ELLIPSIS()
+
+auto [a, b, c] = Containers::ArrayView3<int>{DOXYGEN_ELLIPSIS()};
+/* [StaticArrayView-structured-bindings] */
+static_cast<void>(a);
+static_cast<void>(b);
+static_cast<void>(c);
+}
+
+{
+/* The include is already above, so doing it again here should be harmless */
+/* [StridedDimensions-structured-bindings] */
+#include <Corrade/Containers/StructuredBindings.h>
+
+DOXYGEN_ELLIPSIS()
+
+auto [height, width] = Containers::Size2D(16, 32);
+/* [StridedDimensions-structured-bindings] */
+static_cast<void>(height);
+static_cast<void>(width);
+}
+
+{
+/* The include is already above, so doing it again here should be harmless */
+/* [Triple-structured-bindings] */
+#include <Corrade/Containers/StructuredBindings.h>
+
+DOXYGEN_ELLIPSIS()
+
+auto [first, second, third] = Containers::triple(42, false, 3.14f);
+/* [Triple-structured-bindings] */
+static_cast<void>(first);
+static_cast<void>(second);
+static_cast<void>(third);
+}
+}

src/Corrade/Containers/ArrayView.h

@@ -1103,6 +1103,18 @@ additional compile-time overloads of @ref slice(), @ref sliceSize(),
 
 @snippet Containers.cpp StaticArrayView-usage
 
+@section Containers-StaticArrayView-structured-bindings C++17 structured bindings
+
+If @ref Corrade/Containers/StructuredBindings.h is included, the class can be
+used in C++17 structured bindings. While the @cpp get<i>() @ce overloads are
+defined inside @ref StaticArrayView itself, a separate header is used for the
+@m_class{m-doc-external} [std::tuple_size](https://en.cppreference.com/w/cpp/utility/tuple_size)
+and @m_class{m-doc-external} [std::tuple_element](https://en.cppreference.com/w/cpp/utility/tuple_element)
+template specializations, as those may require @cpp #include <utility> @ce on
+some STL implementations. Example:
+
+@snippet Containers-cpp17.cpp StaticArrayView-structured-bindings
+
 @section Containers-StaticArrayView-stl STL compatibility
 
 See @ref Containers-ArrayView-stl "ArrayView STL compatibility" for more
@@ -1494,6 +1506,20 @@ template<std::size_t size_, class T> class StaticArrayView {
         #endif
 
     private:
+        #if CORRADE_CXX_STANDARD > 201402
+        /* For C++17 structured bindings, if StructuredBindings.h is included
+           as well. There doesn't seem to be a way to call those directly, and
+           I can't find any practical use of std::tuple_size, tuple_element etc
+           on C++11 and C++14, so this is defined only for newer standards. */
+        template<std::size_t index> constexpr friend T& get(StaticArrayView<size_, T> value) {
+            return value._data[index];
+        }
+        /* As the view is non-owning, a rvalue doesn't imply that its contents
+           are able to be moved out. Thus, unlike StaticArray or Pair/Triple,
+           it takes the view by value and has no difference in behavior
+           depending on whether the input is T&, const T& or T&&. */
+        #endif
+
         T* _data;
 };
 

src/Corrade/Containers/CMakeLists.txt

@@ -69,6 +69,7 @@ set(CorradeContainers_HEADERS
     StringStlHash.h
     StringStlView.h
     StringView.h
+    StructuredBindings.h
     Triple.h
     TripleStl.h)
 

src/Corrade/Containers/Pair.h

@@ -6,6 +6,7 @@
     Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
                 2017, 2018, 2019, 2020, 2021, 2022, 2023
               Vladimír Vondruš <mosra@centrum.cz>
+    Copyright © 2022 Stanislaw Halik <sthalik@misaki.pl>
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
@@ -71,6 +72,18 @@ extra flexibility in how the internals are defined.
 
 There's also a three-element variant, called a @ref Triple.
 
+@section Containers-Pair-structured-bindings C++17 structured bindings
+
+If @ref Corrade/Containers/StructuredBindings.h is included, the class can be
+used in C++17 structured bindings. While the @cpp get<i>() @ce overloads are
+defined inside @ref Pair itself, a separate header is used for the
+@m_class{m-doc-external} [std::tuple_size](https://en.cppreference.com/w/cpp/utility/tuple_size)
+and @m_class{m-doc-external} [std::tuple_element](https://en.cppreference.com/w/cpp/utility/tuple_element)
+template specializations, as those may require @cpp #include <utility> @ce on
+some STL implementations. Example:
+
+@snippet Containers-cpp17.cpp Pair-structured-bindings
+
 @section Containers-Pair-stl STL compatibility
 
 Instances of @ref Pair are implicitly copy- and move-convertible to and from
@@ -314,6 +327,31 @@ template<class F, class S> class Pair {
         /* For the conversion constructor */
         template<class, class> friend class Pair;
 
+        #if CORRADE_CXX_STANDARD > 201402
+        /* For C++17 structured bindings, if StructuredBindings.h is included
+           as well. There doesn't seem to be a way to call those directly, and
+           I can't find any practical use of std::tuple_size, tuple_element etc
+           on C++11 and C++14, so this is defined only for newer standards. */
+        template<std::size_t index, typename std::enable_if<index == 0, F>::type* = nullptr> constexpr friend const F& get(const Pair<F, S>& value) {
+            return value._first;
+        }
+        template<std::size_t index, typename std::enable_if<index == 0, F>::type* = nullptr> CORRADE_CONSTEXPR14 friend F& get(Pair<F, S>& value) {
+            return value._first;
+        }
+        template<std::size_t index, typename std::enable_if<index == 0, F>::type* = nullptr> CORRADE_CONSTEXPR14 friend F&& get(Pair<F, S>&& value) {
+            return Utility::move(value._first);
+        }
+        template<std::size_t index, typename std::enable_if<index == 1, S>::type* = nullptr> constexpr friend const S& get(const Pair<F, S>& value) {
+            return value._second;
+        }
+        template<std::size_t index, typename std::enable_if<index == 1, S>::type* = nullptr> CORRADE_CONSTEXPR14 friend S& get(Pair<F, S>& value) {
+            return value._second;
+        }
+        template<std::size_t index, typename std::enable_if<index == 1, S>::type* = nullptr> CORRADE_CONSTEXPR14 friend S&& get(Pair<F, S>&& value) {
+            return Utility::move(value._second);
+        }
+        #endif
+
         F _first;
         S _second;
 };

src/Corrade/Containers/StaticArray.h

@@ -112,6 +112,18 @@ Owning array type               | ↭ | Non-owning view type
 @ref StaticArray "Array<size, T>" | → | @ref ArrayView "ArrayView<const U>"
 @ref StaticArray "const Array<size, T>" | → | @ref ArrayView "ArrayView<const U>"
 
+@section Containers-StaticArray-structured-bindings C++17 structured bindings
+
+If @ref Corrade/Containers/StructuredBindings.h is included, the class can be
+used in C++17 structured bindings. While the @cpp get<i>() @ce overloads are
+defined inside @ref StaticArray itself, a separate header is used for the
+@m_class{m-doc-external} [std::tuple_size](https://en.cppreference.com/w/cpp/utility/tuple_size)
+and @m_class{m-doc-external} [std::tuple_element](https://en.cppreference.com/w/cpp/utility/tuple_element)
+template specializations, as those may require @cpp #include <utility> @ce on
+some STL implementations. Example:
+
+@snippet Containers-cpp17.cpp StaticArray-structured-bindings
+
 @section Containers-StaticArray-stl STL compatibility
 
 On compilers that support C++2a and @ref std::span, implicit conversion of an
@@ -756,6 +768,22 @@ template<std::size_t size_, class T> class StaticArray {
         #endif
 
     private:
+        #if CORRADE_CXX_STANDARD > 201402
+        /* For C++17 structured bindings, if StructuredBindings.h is included
+           as well. There doesn't seem to be a way to call those directly, and
+           I can't find any practical use of std::tuple_size, tuple_element etc
+           on C++11 and C++14, so this is defined only for newer standards. */
+        template<std::size_t index> friend T& get(StaticArray<size_, T>& value) {
+            return value._data[index];
+        }
+        template<std::size_t index> friend const T& get(const StaticArray<size_, T>& value) {
+            return value._data[index];
+        }
+        template<std::size_t index> friend T&& get(StaticArray<size_, T>&& value) {
+            return Utility::move(value._data[index]);
+        }
+        #endif
+
         union {
             T _data[size_];
         };

src/Corrade/Containers/StridedDimensions.h

@@ -142,6 +142,19 @@ Main property compared to a plain C array of value is convertibility from/to
 @ref StaticArrayView, implicit conversion from/to a scalar type in the
 one-dimensional case and element-wise equality comparison. See
 @ref StridedArrayView and @ref StridedBitArrayView for actual usage examples.
+
+@section Containers-StridedDimensions-structured-bindings C++17 structured bindings
+
+If @ref Corrade/Containers/StructuredBindings.h is included, the class can be
+used in C++17 structured bindings. While the @cpp get<i>() @ce overloads are
+defined inside @ref StridedDimensions itself, a separate header is used for the
+@m_class{m-doc-external} [std::tuple_size](https://en.cppreference.com/w/cpp/utility/tuple_size)
+and @m_class{m-doc-external} [std::tuple_element](https://en.cppreference.com/w/cpp/utility/tuple_element)
+template specializations, as those may require @cpp #include <utility> @ce on
+some STL implementations. Example:
+
+@snippet Containers-cpp17.cpp StridedDimensions-structured-bindings
+
 @see @ref Size, @ref Size1D, @ref Size2D, @ref Size3D, @ref Size4D,
     @ref Stride, @ref Stride1D, @ref Stride2D, @ref Stride3D, @ref Stride4D
 */
@@ -251,6 +264,25 @@ template<unsigned dimensions, class T> class StridedDimensions {
         template<unsigned newDimensions, class U, unsigned dimensions_> StridedArrayView<newDimensions, U> friend arrayCast(const StridedArrayView<dimensions_, void>&, std::size_t);
         template<unsigned newDimensions, class U, unsigned dimensions_> StridedArrayView<newDimensions, U> friend arrayCast(const StridedArrayView<dimensions_, const void>&, std::size_t);
 
+        #if CORRADE_CXX_STANDARD > 201402
+        /* For C++17 structured bindings, if StructuredBindings.h is included
+           as well. There doesn't seem to be a way to call those directly, and
+           I can't find any practical use of std::tuple_size, tuple_element etc
+           on C++11 and C++14, so this is defined only for newer standards. */
+        template<std::size_t index> constexpr friend const T& get(const StridedDimensions<dimensions, T>& value) {
+            return value._data[index];
+        }
+        template<std::size_t index> CORRADE_CONSTEXPR14 friend T& get(StridedDimensions<dimensions, T>& value) {
+            return value._data[index];
+        }
+        /* This has to be here as otherwise it tries to pass certain cases
+           through the const T& overload, subsequently complaining that
+           const T& can't be bound to T& (?!) */
+        template<std::size_t index> CORRADE_CONSTEXPR14 friend T&& get(StridedDimensions<dimensions, T>&& value) {
+            return Utility::move(value._data[index]);
+        }
+        #endif
+
         template<class U, std::size_t ...sequence> constexpr explicit StridedDimensions(const U* values, Implementation::Sequence<sequence...>) noexcept: _data{T(values[sequence])...} {}
 
         T _data[dimensions];