From 301c76646cde41faa7d932ef66394c3d62bc4268 Mon Sep 17 00:00:00 2001
From: Christian Mazakas <christian.mazakas@gmail.com>
Date: Wed, 2 Feb 2022 11:14:05 -0800
Subject: [PATCH] Add Tutorial section to AsciiDoc

---
 doc/hash/tutorial.adoc | 44 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/hash/tutorial.adoc b/doc/hash/tutorial.adoc
index 04841fd..aa165d6 100644
--- a/doc/hash/tutorial.adoc
+++ b/doc/hash/tutorial.adoc
@@ -2,3 +2,47 @@
 = Tutorial
 
 :idprefix: tutorial_
+
+When using a hash index with link:../../../multi_index/index.html[Boost.MultiIndex^], you don't need to do anything to use xref:#ref_hash[boost::hash] as it uses it by default. To find out how to use a user-defined type, read the <<custom,section on extending boost::hash for a custom data type>>.
+
+If your standard library supplies its own implementation of the unordered associative containers and you wish to use xref:#ref_hash[boost::hash], just use an extra template parameter:
+
+[listing,subs="+quotes,+macros"]
+----
+std::unordered_multiset<int, xref:#ref_hash[boost::hash]<int> >
+        set_of_ints;
+
+std::unordered_set<std::pair<int, int>, xref:#ref_hash[boost::hash]<std::pair<int, int> > >
+        set_of_pairs;
+
+std::unordered_map<int, std::string, xref:#ref_hash[boost::hash]<int> > map_int_to_string;
+----
+
+To use xref:#ref_hash[boost::hash] directly, create an instance and call it as a function:
+
+[listing,subs="+quotes,+macros"]
+----
+xref:#ref_header_boostcontainer_hashhash_hpp[++#include <boost/container_hash/hash.hpp>++]
+
+int main()
+{
+    xref:#ref_hash[boost::hash]<std::string> string_hash;
+
+    std::size_t h = string_hash("Hash me");
+}
+----
+
+For an example of generic use, here is a function to generate a vector containing the hashes of the elements of a container:
+
+[listing,subs="+quotes,+macros"]
+----
+template <class Container>
+std::vector<std::size_t> get_hashes(Container const& x)
+{
+    std::vector<std::size_t> hashes;
+    std::transform(x.begin(), x.end(), std::back_inserter(hashes),
+        xref:#ref_hash[boost::hash]<typename Container::value_type>());
+
+    return hashes;
+}
+----