guile/guile-core/doc ChangeLog preface.texi sch...

[Martin Grabmueller]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Martin Grabmueller <address@hidden>     01/06/30 06:45:22

Modified files:
        guile-core/doc : ChangeLog preface.texi scheme-data.texi 

Log message:
        * preface.texi (Manual Conventions): Added description of
        @result{} and @print{}.
        
        * scheme-data.texi (Hash Table Examples): New subsubsection.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.107&tr2=1.108&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/preface.texi.diff?cvsroot=OldCVS&tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/scheme-data.texi.diff?cvsroot=OldCVS&tr1=1.24&tr2=1.25&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.107 
guile/guile-core/doc/ChangeLog:1.108
--- guile/guile-core/doc/ChangeLog:1.107        Fri Jun 29 23:58:04 2001
+++ guile/guile-core/doc/ChangeLog      Sat Jun 30 06:45:22 2001
@@ -1,5 +1,12 @@
 2001-06-30  Martin Grabmueller  <address@hidden>
 
+       * preface.texi (Manual Conventions): Added description of
+       @result{} and @print{}.
+
+       * scheme-data.texi (Hash Table Examples): New subsubsection.
+       
+2001-06-30  Martin Grabmueller  <address@hidden>
+
        * scheme-data.texi (Hash Tables): Added docs for
        `make-hash-table'.
 
Index: guile/guile-core/doc/preface.texi
diff -u guile/guile-core/doc/preface.texi:1.3 
guile/guile-core/doc/preface.texi:1.4
--- guile/guile-core/doc/preface.texi:1.3       Fri May  4 14:01:35 2001
+++ guile/guile-core/doc/preface.texi   Sat Jun 30 06:45:22 2001
@@ -148,6 +148,30 @@
 otherwise.
 @cindex iff
 
address@hidden
+In examples and procedure descriptions and all other places where the
+evaluation of Scheme expression is shown, we use some notation for
+denoting the output and evaluation results of expressions.
+
+The symbol @address@hidden is used to tell which value is returned by
+an evaluation:
+
address@hidden
+(+ 1 2)
address@hidden
+3
address@hidden lisp
+
+Some procedures produce some output besides returning a value.  This
+is denoted by the symbol @address@hidden
+
address@hidden
+(begin (display 1) (newline) 'hooray)
address@hidden 1
address@hidden
+hooray
address@hidden lisp
+
 @c Add other conventions here.
 
 @end itemize
Index: guile/guile-core/doc/scheme-data.texi
diff -u guile/guile-core/doc/scheme-data.texi:1.24 
guile/guile-core/doc/scheme-data.texi:1.25
--- guile/guile-core/doc/scheme-data.texi:1.24  Fri Jun 29 23:58:04 2001
+++ guile/guile-core/doc/scheme-data.texi       Sat Jun 30 06:45:22 2001
@@ -4784,6 +4784,98 @@
 @subsection Hash Tables
 @tpindex Hash Tables
 
address@hidden FIXME::martin: Review me!
+
+Hash tables are dictionaries which offer similar functionality as
+association lists: They provide a mapping from keys to values.  The
+difference is that association lists need time linear in the size of
+elements when searching for entries, whereas hash tables can normally
+search in constant time.  The drawback is that hash tables require a
+little bit more memory, and that you can not use the normal list
+procedures (@pxref{Lists}) for working with them.
+
address@hidden
+* Hash Table Examples::         Demonstration of hash table usage.
+* Hash Table Reference::        Hash table procedure descriptions.
address@hidden menu
+
+
address@hidden Hash Table Examples
address@hidden Hash Table Examples
+
address@hidden FIXME::martin: Review me!
+
+For demonstration purposes, this section gives a few usage examples of
+some hash table procedures, together with some explanation what they do.
+
+First we start by creating a new hash table with 31 slots, and
+populate it with two key/value pairs.
+
address@hidden
+(define h (make-hash-table 31))
+
+(hashq-create-handle! h 'foo "bar")
address@hidden
+(foo . "bar")
+
+(hashq-create-handle! h 'braz "zonk")
address@hidden
+(braz . "zonk")
+
+(hashq-create-handle! h 'frob #f)
address@hidden
+(frob . #f)
address@hidden lisp
+
+You can get the value for a given key with the procedure
address@hidden, but the problem with this procedure is that you
+cannot reliably determine whether a key does exists in the table.  The
+reason is that the procedure returns @code{#f} if the key is not in
+the table, but it will return the same value if the key is in the
+table and just happens to have the value @code{#f}, as you can see in
+the following examples.
+
address@hidden
+(hashq-ref h 'foo)
address@hidden
+"bar"
+
+(hashq-ref h 'frob)
address@hidden
+#f
+
+(hashq-ref h 'not-there)
address@hidden
+#f
address@hidden lisp
+
+Better is to use the procedure @code{hashq-get-handle}, which makes a
+distinction between the two cases.  Just like @code{assq}, this
+procedure returns a key/value-pair on success, and @code{#f} if the
+key is not found.
+
address@hidden
+(hashq-get-handle h 'foo)
address@hidden
+(foo . "bar")
+
+(hashq-get-handle h 'not-there)
address@hidden
+#f
address@hidden lisp
+
+There is no procedure for calculating the number of key/value-pairs in
+a hash table, but @code{hash-fold} can be used for doing exactly that.
+
address@hidden
+(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
address@hidden
+3
address@hidden lisp
+
address@hidden Hash Table Reference
address@hidden Hash Table Reference
+
 Like the association list functions, the hash table functions come
 in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
 The @code{hashq} functions use @code{eq?} to determine whether two
@@ -4991,7 +5083,7 @@
 and value are successive pairs from the hash table TABLE, and
 prior-result is either INIT (for the first application of PROC)
 or the return value of the previous application of PROC.
-For example, @code{(hash-fold acons () tab)} will convert a hash
+For example, @code{(hash-fold acons '() tab)} will convert a hash
 table into an a-list of key-value pairs.
 @end deffn