[funds-cvs] r169 - trunk/funds/src

[abaine at common-lisp.net]

Author: abaine
Date: Sun Aug 19 12:46:27 2007
New Revision: 169

Modified:
   trunk/funds/src/dictionary.lisp
Log:
Documented dictionary.

Modified: trunk/funds/src/dictionary.lisp
==============================================================================
--- trunk/funds/src/dictionary.lisp	(original)
+++ trunk/funds/src/dictionary.lisp	Sun Aug 19 12:46:27 2007
@@ -7,9 +7,14 @@
   tree)
 
 (defun make-dictionary (&key (hash #'sxhash) (test #'eql))
+  "An empty dictionary that hashes occording to the given hash function,
+which defaults to #'sxhash and and tests according to the given test 
+function, which defaults to #'eql."
   (make-dict :hash hash :test test :tree (make-avl-tree)))
 
 (defun dictionary-add (d k v)
+  "A dictionary similar to the given dictionary except that k maps to
+v in the returned dictionary."
   (let* ((h (funcall (dict-hash d) k))
 	 (old-alist (tree-find (dict-tree d) h))
 	 (new-alist (acons k v (remove (assoc k old-alist :test (dict-test d))
@@ -19,6 +24,8 @@
 	       :tree (tree-insert (dict-tree d) h new-alist))))
 
 (defun dictionary-remove (d k)
+  "A dictionary similar to the given dictionary, except that k does
+not map to any value in the returned dictionary."
   (let* ((h (funcall (dict-hash d) k))
 	 (old-alist (tree-find (dict-tree d) h))
 	 (new-alist (remove (assoc k old-alist :test (dict-test d))
@@ -30,6 +37,9 @@
 			 (tree-insert (dict-tree d) h new-alist)))))
 
 (defun dictionary-lookup (d k)
+  "The value associated with the given key in the given dictionary.  A second
+value is returned to indicate whether the key is associated with any value or
+is not found."
   (let ((pair (assoc k 
 		     (tree-find (dict-tree d) (funcall (dict-hash d) k))
 		     :test (dict-test d))))