From b0dc7d478eceeeae7a755735ccfd878b18fbee66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?=
 <dominik.pantucek@trustica.cz>
Date: Mon, 20 Mar 2023 21:51:42 +0100
Subject: [PATCH] Document the dictionary module.

---
 README.md      | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++
 dictionary.scm |  6 ++--
 2 files changed, 91 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1b3afe0..9c42ba8 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,93 @@ implemented anyway to not require any external dependencies.
 
 ### Dictionary
 
+Simple key/value dictionary with most operations implemented in linear
+time. The dictionary is internally represented as ```assq``` list and
+is best suitable for symbols and numbers as keys.
+
+    (make-dict)
+
+Creates an empty dictionary.
+
+    (dict-has-key? d k)
+
+* ```d``` - the dictionary
+* ```k``` - key to check
+
+Returns ```#t``` (true) if the dictionary ```d``` contains the key
+```k```.
+
+    (dict-ref d k [v])
+
+* ```d``` - the dictionary
+* ```k``` - the key to retrieve
+* ```v``` - optional default value
+
+Retrieves given key ```k``` from the dictionary ```d```.
+
+If the key is not stored in the dictionary an error is raised unless
+an optional value ```v``` is provided which is then returned in that
+case.
+
+    (dict-remove d k)
+
+* ```d``` - the dictionary
+* ```k``` - the key to remove
+
+Removes the key ```k``` from the given dictionary ```d``` raising an
+exception if  the key is not stored in the dictionary.
+
+    (dict-set d k v)
+
+* ```d``` - the dictionary
+* ```k``` - key to (re)set
+* ```v``` - the value to set
+
+If the dictionary ```d``` does not contain the key ```k```, adds the
+value ```v``` into it under the given key. If the key is present, its
+value is then replaced.
+
+    (dict-keys d)
+
+* ```d``` - the dictionary
+
+Returns the list of keys contained in the dictionary ```d```.
+
+    (dict-map proc d)
+
+* ```proc``` - procedure for processing
+* ```d``` - the dictionary
+
+Returns a dictionary created by processing all elements of the
+dictionary ```d``` using the procedure ```proc```.
+
+If the procedure accepts just one argument, only values are passed to
+it. If the procedure accepts two arguments, both the key and value are
+passed to it. In both cases, the procedure must produce only the value.
+
+    (dict-filter pred? d)
+
+* ```pred?``` - predicate procedure
+* ```d``` - the dictionary
+
+Returns a new dictionary created by keeping only the key/value pairs
+from the dictionary ```d``` matching the predicate ```pred?```.
+
+If the procedure accepts just one argument, only values are passed to
+it. If the procedure accepts two arguments, both the key and value are
+passed to it.
+
+    (dict-reduce init proc d)
+
+* ```init``` - arbitrary initial value
+* ```proc``` - procedure for performing the reducing step
+* ```d``` - the dictionary to reduce
+
+Iterates over the key/value pairs of given dictionary ```d```
+initializing the algorithm with the ```init``` value given. In each
+step the procedure ```proc``` is called with three arguments: the
+value accumulated so far, key and value.
+
 ### Listing
 
 This module implements listing a text file with line numbers and
diff --git a/dictionary.scm b/dictionary.scm
index b221df8..4f56bab 100644
--- a/dictionary.scm
+++ b/dictionary.scm
@@ -29,8 +29,10 @@
  dictionary
  (
   make-dict
-  dict-has-key? dict-ref
-  dict-remove dict-set
+  dict-has-key?
+  dict-ref
+  dict-remove
+  dict-set
   dict-keys
   dict-map
   dict-filter