From 658a557b8b7cc3a1b0c5983a74d67627a92f7ddb Mon Sep 17 00:00:00 2001 From: LordPatate <35635468+LordPatate@users.noreply.github.com> Date: Wed, 29 Apr 2026 16:39:20 +0200 Subject: [PATCH 1/3] (docs) Hashtbl: comparison vs Maps The current introduction mentions multiple differences to chose one or the other but only gives one advantage to Hashtbl. It is not obvious why would one chose Maps over Hashtbl. --- data/tutorials/language/3ds_04_hashtbl.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/data/tutorials/language/3ds_04_hashtbl.md b/data/tutorials/language/3ds_04_hashtbl.md index c0ce14fcb6..1b90b16ffc 100644 --- a/data/tutorials/language/3ds_04_hashtbl.md +++ b/data/tutorials/language/3ds_04_hashtbl.md @@ -19,6 +19,12 @@ logarithmic time complexity (O(log n)), a [`hash table`](https://en.wikipedia.org/wiki/Hash_table) is able to retrieve information at a nearly instantaneous constant time complexity (O(1)). +**Note:** For more details on the differences between Hash Tables and Maps, +try searching for [comparisons of associative array +implementations](https://en.wikipedia.org/wiki/Associative_array#Comparison). +O'Caml Maps use [self-balancing binary search +trees](https://en.wikipedia.org/wiki/Self-balancing_binary_search_tree). + A hash table data structure achieves efficient reads and writes by employing a hashing function that converts the key of a key/value pair into an algorithmically unique "fingerprint" known as a hash. OCaml has a built-in From 586e7ff701103a76b2165d913def364ec834f6fd Mon Sep 17 00:00:00 2001 From: LordPatate <35635468+LordPatate@users.noreply.github.com> Date: Wed, 29 Apr 2026 17:02:23 +0200 Subject: [PATCH 2/3] (docs) Maps: differences vs Hashtbl Discuss a little bit more the differences, especially the advantages over Hashtbl, without going too much into the details. The advantages of Maps were never mentioned, while the main advantage of Hashtbl was present in their own page. Unless the reader dived into the library or did their own research on self-balancing binary search trees, Maps could seem like a "worse" Hash Table; or only exist for the functional interface. --- data/tutorials/language/3ds_02_maps.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/data/tutorials/language/3ds_02_maps.md b/data/tutorials/language/3ds_02_maps.md index c6973e1887..5053467f07 100644 --- a/data/tutorials/language/3ds_02_maps.md +++ b/data/tutorials/language/3ds_02_maps.md @@ -10,7 +10,9 @@ category: "Data Structures" In the most general sense, the [`Map`](/manual/api/Map.html) module lets you create _immutable_ key-value [associative array](https://en.wikipedia.org/wiki/Associative_array) for your types. More concretely, -OCaml's `Map` module is implemented using a binary search tree algorithm to support fast lookups (of O(Log n)). +OCaml's `Map` module is implemented using a [self-balancing binary search tree +algorithm](https://en.wikipedia.org/wiki/Self-balancing_binary_search_tree) +to support fast lookups (of O(Log n)). **Note**: The concept of a `Map` in this tutorial refers to a data structure that stores a set of key-value pairs. It is sometimes called a dictionary or an association table. This @@ -25,6 +27,12 @@ the maps, and a function for comparing them. For a different implementation of an association table in OCaml's Standard Library, see the tutorial on [Hash Tables](/docs/hash-tables). +Maps offer a functional interface that Hash Tables do not +and maintain total ordering of the keys, allowing more operations; +while Hash Tables have better search performance on average. +For more on their differences and the applications of Maps, see the corresponding +paragraph on wikipedia: [applications of balanced binary search +trees](https://en.wikipedia.org/wiki/Self-balancing_binary_search_tree#Applications). ```ocaml # module StringMap = Map.Make(String);; From 40fcdee481a136c46903a3760cf887b5621ffff9 Mon Sep 17 00:00:00 2001 From: LordPatate <35635468+LordPatate@users.noreply.github.com> Date: Tue, 19 May 2026 10:30:56 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Use capitals for standard library module names or tutorial titles Co-authored-by: Cuihtlauac Alvarado --- data/tutorials/language/3ds_02_maps.md | 7 ++++--- data/tutorials/language/3ds_04_hashtbl.md | 6 +++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/data/tutorials/language/3ds_02_maps.md b/data/tutorials/language/3ds_02_maps.md index 5053467f07..765a81c8ba 100644 --- a/data/tutorials/language/3ds_02_maps.md +++ b/data/tutorials/language/3ds_02_maps.md @@ -27,9 +27,10 @@ the maps, and a function for comparing them. For a different implementation of an association table in OCaml's Standard Library, see the tutorial on [Hash Tables](/docs/hash-tables). -Maps offer a functional interface that Hash Tables do not -and maintain total ordering of the keys, allowing more operations; -while Hash Tables have better search performance on average. + +`Map` offers a functional interface that `Hashtbl` does not. +`Map` also maintain total ordering of the keys, allowing more operations; +while hash tables have better search performance on average. For more on their differences and the applications of Maps, see the corresponding paragraph on wikipedia: [applications of balanced binary search trees](https://en.wikipedia.org/wiki/Self-balancing_binary_search_tree#Applications). diff --git a/data/tutorials/language/3ds_04_hashtbl.md b/data/tutorials/language/3ds_04_hashtbl.md index 1b90b16ffc..67e4ab929f 100644 --- a/data/tutorials/language/3ds_04_hashtbl.md +++ b/data/tutorials/language/3ds_04_hashtbl.md @@ -19,10 +19,10 @@ logarithmic time complexity (O(log n)), a [`hash table`](https://en.wikipedia.org/wiki/Hash_table) is able to retrieve information at a nearly instantaneous constant time complexity (O(1)). -**Note:** For more details on the differences between Hash Tables and Maps, -try searching for [comparisons of associative array +**Note:** For more details on the differences between hash tables and associative maps, +see [comparisons of associative array implementations](https://en.wikipedia.org/wiki/Associative_array#Comparison). -O'Caml Maps use [self-balancing binary search +OCaml Maps use [self-balancing binary search trees](https://en.wikipedia.org/wiki/Self-balancing_binary_search_tree). A hash table data structure achieves efficient reads and writes by employing a