Containers: std::hash specialization for [Mutable]String[View].

It never ceases to amaze me how bloated the STL headers are. Here I am
shaving #include dependencies to go from 3k to 2kLOC, and then you
casually include <functional> and suddenly you're almost 30kLOC heavier.

Author: mosra

src/Corrade/Containers/CMakeLists.txt

@@ -61,6 +61,7 @@ set(CorradeContainers_HEADERS
     StridedArrayViewStl.h
     String.h
     StringStl.h
+    StringStlHash.h
     StringStlView.h
     StringView.h
     Triple.h

src/Corrade/Containers/String.h

@@ -241,6 +241,13 @@ mitigate the conversion impact, it's recommended to convert
 @ref std::string_view instances to @ref BasicStringView "StringView" instead
 where possible.
 
+Finally, the @ref Corrade/Containers/StringStlHash.h header provides a
+@ref std::hash specialization for @ref String, making it usable in
+@ref std::unordered_map and @ref std::unordered_set. It's *also* separate, due
+to dependency on @cpp #include <functional> @ce which is among the heaviest STL
+headers in existence, and which is only really needed when you deal with
+unordered containers.
+
 @experimental
 */
 class CORRADE_UTILITY_EXPORT String {

src/Corrade/Containers/StringStl.h

@@ -32,10 +32,10 @@
 
 Including this header allows you to convert a
 @ref Corrade::Containers::String / @ref Corrade::Containers::StringView from
-and to @ref std::string. A separate
-@ref Corrade/Containers/StringStlView.h header provides compatibility with
-@ref std::string_view from C++17. See
-@ref Containers-String-stl "String STL compatibility" and
+and to @ref std::string. A separate @ref Corrade/Containers/StringStlView.h
+header provides compatibility with @ref std::string_view from C++17,
+@ref Corrade/Containers/StringStlHash.h then provides a @ref std::hash
+specialization. See @ref Containers-String-stl "String STL compatibility" and
 @ref Containers-BasicStringView-stl "StringView STL compatibility" for more
 information.
 */

src/Corrade/Containers/StringStlHash.h

@@ -0,0 +1,83 @@
+#ifndef Corrade_Containers_StringStlHash_h
+#define Corrade_Containers_StringStlHash_h
+/*
+    This file is part of Corrade.
+
+    Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
+                2017, 2018, 2019, 2020, 2021, 2022
+              Vladimír Vondruš <[email protected]>
+
+    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 STL @ref std::hash compatibility for @ref Corrade::Containers::String and @ref Corrade::Containers::BasicStringView "StringView"
+@m_since_latest
+
+Including this header adds a @ref std::hash specialization for
+@ref Corrade::Containers::String / @ref Corrade::Containers::BasicStringView "StringView",
+making them usable in @ref std::unordered_map and @ref std::unordered_set. See
+@ref Containers-String-stl "String STL compatibility" and
+@ref Containers-BasicStringView-stl "StringView STL compatibility" for more
+information.
+*/
+
+/* Alone, <functional> is relatively big (9kLOC on GCC 11 -std=c++11), but when
+   combined with <unordered_map> (12k) it results in just 13k, so it's not like
+   we'd gain anything by trying to find a forward declaration. On libc++ 11
+   it's 22k for <functional> (!!) and 36k (!!!) for <unordered_map> either
+   alone or together with <functional>. So even though the numbers are QUITE
+   HORRENDOUS, a forward declaration wouldn't help there either. On GCC 11 and
+   -std=c++20 the size goes up to 30k as well. Haha.
+
+   Compared to these, I don't feel like bothering to optimize my side of the
+   include chain, even though the MurmurHash2 include could potentially get
+   deinlined. */
+#include <functional>
+
+#include "Corrade/Containers/String.h"
+#include "Corrade/Containers/StringView.h"
+#include "Corrade/Utility/MurmurHash2.h"
+
+/* Listing these namespaces doesn't add anything to the docs, so don't */
+#ifndef DOXYGEN_GENERATING_OUTPUT
+namespace std {
+
+template<> struct hash<Corrade::Containers::StringView> {
+    std::size_t operator()(Corrade::Containers::StringView key) const {
+        const Corrade::Utility::MurmurHash2 hash;
+        const Corrade::Utility::HashDigest<sizeof(std::size_t)> digest = hash(key.data(), key.size());
+        return *reinterpret_cast<const std::size_t*>(digest.byteArray());
+    }
+};
+
+template<> struct hash<Corrade::Containers::MutableStringView>: hash<Corrade::Containers::StringView> {};
+
+template<> struct hash<Corrade::Containers::String> {
+    std::size_t operator()(const Corrade::Containers::String& key) const {
+        const Corrade::Utility::MurmurHash2 hash;
+        const Corrade::Utility::HashDigest<sizeof(std::size_t)> digest = hash(key.data(), key.size());
+        return *reinterpret_cast<const std::size_t*>(digest.byteArray());
+    }
+};
+
+}
+#endif
+
+#endif

src/Corrade/Containers/StringStlView.h

@@ -34,7 +34,8 @@ Including this header allows you to convert a
 @ref Corrade::Containers::String / @ref Corrade::Containers::StringView from
 and to a C++17 @ref std::string_view. A separate
 @ref Corrade/Containers/StringStl.h header provides compatibility with
-@ref std::string. See
+@ref std::string, @ref Corrade/Containers/StringStlHash.h then provides a
+@ref std::hash specialization. See
 @ref Containers-String-stl "String STL compatibility" and
 @ref Containers-BasicStringView-stl "StringView STL compatibility" for more
 information.

src/Corrade/Containers/StringView.h

@@ -259,6 +259,13 @@ no possibility to create a @ref MutableStringView out of it. Because
 neither @ref StringViewFlag::NullTerminated nor @ref StringViewFlag::Global is
 set in a @ref StringView converted from it.
 
+Finally, the @ref Corrade/Containers/StringStlHash.h header provides a
+@ref std::hash specialization for @ref StringView / @ref MutableStringView,
+making it usable in @ref std::unordered_map and @ref std::unordered_set. It's
+* *also* separate, due to dependency on @cpp #include <functional> @ce which is
+among the heaviest STL headers in existence, and which is only really needed
+when you deal with unordered containers.
+
 @experimental
 */
 /* All member functions are const because the view doesn't own the data */

src/Corrade/Containers/Test/StringStlTest.cpp

@@ -24,8 +24,12 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#include <unordered_map>
+
 #include "Corrade/Containers/StringStl.h"
+#include "Corrade/Containers/StringStlHash.h"
 #include "Corrade/TestSuite/Tester.h"
+#include "Corrade/TestSuite/Compare/Numeric.h"
 #include "Corrade/Utility/DebugStl.h"
 
 namespace Corrade { namespace Containers { namespace Test { namespace {
@@ -46,6 +50,8 @@ struct StringStlTest: TestSuite::Tester {
     void convertViewFromStlStringEmpty();
     void convertMutableViewFromStlString();
     void convertMutableViewFromStlStringEmpty();
+
+    template<class T> void hash();
 };
 
 StringStlTest::StringStlTest() {
@@ -61,7 +67,11 @@ StringStlTest::StringStlTest() {
               &StringStlTest::convertViewFromStlString,
               &StringStlTest::convertViewFromStlStringEmpty,
               &StringStlTest::convertMutableViewFromStlString,
-              &StringStlTest::convertMutableViewFromStlStringEmpty});
+              &StringStlTest::convertMutableViewFromStlStringEmpty,
+
+              &StringStlTest::hash<StringView>,
+              &StringStlTest::hash<MutableStringView>,
+              &StringStlTest::hash<String>});
 }
 
 using namespace Literals;
@@ -147,6 +157,41 @@ void StringStlTest::convertMutableViewFromStlStringEmpty() {
     CORRADE_COMPARE(b.data(), static_cast<const void*>(a.data()));
 }
 
+template<class> struct NameTraits;
+template<> struct NameTraits<StringView> {
+    static const char* name() { return "StringView"; }
+};
+template<> struct NameTraits<MutableStringView> {
+    static const char* name() { return "MutableStringView"; }
+};
+template<> struct NameTraits<String> {
+    static const char* name() { return "String"; }
+};
+
+template<class T> void StringStlTest::hash() {
+    setTestCaseTemplateName(NameTraits<T>::name());
+
+    char hello[] = "hello";
+    char olleh[] = "olleh";
+
+    std::unordered_map<T, int> map;
+    map.emplace(hello, 3);
+    map.emplace(olleh, 7);
+    CORRADE_COMPARE(map[hello], 3);
+    CORRADE_COMPARE(map[olleh], 7);
+
+    /* Verify the hash function is non-trivial */
+    CORRADE_COMPARE_AS(std::hash<T>{}(hello), std::hash<T>{}({}),
+        TestSuite::Compare::NotEqual);
+    CORRADE_COMPARE_AS(std::hash<T>{}(olleh), std::hash<T>{}({}),
+        TestSuite::Compare::NotEqual);
+    CORRADE_COMPARE_AS(std::hash<T>{}(hello), std::hash<T>{}(olleh),
+        TestSuite::Compare::NotEqual);
+
+    /* And also non-random and not depending on the data pointer */
+    CORRADE_COMPARE(std::hash<T>{}(hello), std::hash<Containers::StringView>{}("hello!"_s.exceptSuffix(1)));
+}
+
 }}}}
 
 CORRADE_TEST_MAIN(Corrade::Containers::Test::StringStlTest)