feat(std::hash): page for operator()

Author: HOMODELUNA

src/content/docs/cpp/library/utility/hash.mdx

@@ -48,7 +48,7 @@ Defined in header <CppHeader name="vector" />.
   <Decl slot="decl">
     <RevisionBlock since="C++11" noborder>
       ```cpp
-      template< class Key >
+      template<class Key>
       struct hash;
       ```
     </RevisionBlock>
@@ -68,10 +68,10 @@ Given a type `Key`, each specialization `std::hash<Key>` is either _enabled_ or
         -   [Swappable](../named_req/Swappable.html "cpp/named req/Swappable")
 
     -   Given the following values:
-        -   h, an object of type `std::hash<Key>`.
-        -   k1 and k2, objects of type `Key`.
+        -   `h`, an object of type `std::hash<Key>`.
+        -   `k1` and `k2`, objects of type `Key`.
     All following requirements are satisfied:
-        -   If k1 \== k2 is true, h(k1) \== h(k2) is also true.
+        -   If `k1 == k2` is true, `h(k1) == h(k2)` is also true.
         -   Unless `std::hash<Key>` is a [program-defined specialization](../language/type-id.html#Program-defined_type "cpp/language/type"), h(k1) will never throw an exception.
 
 -   Otherwise, `std::hash<Key>` is disabled.
@@ -100,8 +100,8 @@ In other words, they exist, but cannot be used.
 ### Member functions
 | | |
 |---|---|
-|`constuctor` | constructs a hash function object <br/> (public member function)|
-|`operator()` | calculates the hash of the argument <br/> (public member function)|
+|(constuctor) | <Desc kind="public member function">constructs a hash function object </Desc>|
+|[`operator()`](./operator-call/) | <Desc kind="public member function">calculates the hash of the argument </Desc>|
 
 
 ### Standard library specializations
@@ -225,18 +225,6 @@ hash("Hubert", "Farnsworth") =  12922914235676820612 (using MyHash) or
 "Hubert" "Farnsworth"
 ```
 
-```cpp
-// Simple move constructor
-// the expression "arg.member" is lvalue
-A(A&& arg) : member(std::move(arg.member)) {}
- 
-// Simple move assignment operator
-A& operator=(A&& other) {
-  member = std::move(other.member);
-  return *this;
-}
-```
-
 ## Defect reports
 
 The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

src/content/docs/cpp/library/utility/hash/operator-call.mdx

@@ -0,0 +1,83 @@
+---
+title: std::hash::operator()
+cppdoc:
+  revision:
+    since: C++11
+---
+
+import { ParamDoc, ParamDocList } from "@components/param-doc";
+
+Specializations of `std::hash` should define an `operator()` that:
+
+- Takes a single argument key of type `Key`.
+- Returns a value of type `std::size_t` that represents the hash value of key.
+- For two parameters `k1` and `k2` that are equal, `std::hash<Key>()(k1) == std::hash<Key>()(k2)`.
+- For two different parameters `k1` and `k2` that are not equal, the probability that `std::hash<Key>()(k1) == std::hash<Key>()(k2)` should be very small, approaching `1.0 / std::numeric_limits<size_t>::max()`.
+
+
+## Parameters
+<ParamDocList>
+  <ParamDoc name="key">
+    the object to be hashed
+  </ParamDoc>
+</ParamDocList>
+
+## Return value
+A `std::size_t` representing the hash value.
+
+## Exceptions
+Hash functions should not throw exceptions.
+
+## Example
+The following code shows how to specialize the std::hash template for a custom class. The hash function uses Fowler–Noll–Vo hash algorithm.
+
+```cpp
+#include <cstdint>
+#include <functional>
+#include <iostream>
+#include <string>
+ 
+struct Employee
+{
+    std::string name;
+    std::uint64_t ID;
+};
+ 
+namespace std
+{
+    template <>
+    class hash<Employee>
+    {
+    public:
+        std::uint64_t operator()(const Employee& employee) const
+        {
+             // computes the hash of an employee using a variant
+             // of the Fowler-Noll-Vo hash function
+             constexpr std::uint64_t prime{0x100000001B3};
+             std::uint64_t result{0xcbf29ce484222325};
+ 
+             for (std::uint64_t i{}, ie = employee.name.size(); i != ie; ++i)
+                 result = (result * prime) ^ employee.name[i];
+ 
+             return result ^ (employee.ID << 1);
+         }
+    };
+}
+ 
+int main()
+{
+    Employee employee;
+    employee.name = "Zaphod Beeblebrox";
+    employee.ID = 42;
+ 
+    std::hash<Employee> hash_fn;
+    std::cout << hash_fn(employee) << '\n';
+}
+```
+
+Output:
+
+```cpp
+12615575401975788567
+```
+