diff --git a/doc/ChangeLog b/doc/ChangeLog index a3ff0d3ce..b77bed64b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,10 @@ +2001-06-30 Martin Grabmueller + + * preface.texi (Manual Conventions): Added description of + @result{} and @print{}. + + * scheme-data.texi (Hash Table Examples): New subsubsection. + 2001-06-30 Martin Grabmueller * scheme-data.texi (Hash Tables): Added docs for diff --git a/doc/preface.texi b/doc/preface.texi index 3c0ab509b..e69de29bb 100644 --- a/doc/preface.texi +++ b/doc/preface.texi @@ -1,158 +0,0 @@ -@iftex -@page -@unnumbered Preface - -This reference manual documents Guile, GNU's Ubiquitous Intelligent -Language for Extensions. It describes how to use Guile in many useful -and interesting ways. - -This is edition 1.0 of the reference manual, and corresponds to Guile -version @value{VERSION}. -@end iftex - - -@iftex -@section The Guile License -@end iftex - -@ifnottex -@node Guile License -@chapter The Guile License -@end ifnottex - -The license of Guile consists of the GNU GPL plus a special statement -giving blanket permission to link with non-free software. This is the -license statement as found in any individual file that it applies to: - -@quotation -This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 2, or (at your option) any -later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License along -with this software; see the file COPYING. If not, write to the Free -Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA -02111-1307 USA - -As a special exception, the Free Software Foundation gives permission -for additional uses of the text contained in its release of GUILE. - -The exception is that, if you link the GUILE library with other files to -produce an executable, this does not by itself cause the resulting -executable to be covered by the GNU General Public License. Your use of -that executable is in no way restricted on account of linking the GUILE -library code into it. - -This exception does not however invalidate any other reasons why the -executable file might be covered by the GNU General Public License. - -This exception applies only to the code released by the Free Software -Foundation under the name GUILE. If you copy code from other Free -Software Foundation releases into a copy of GUILE, as the General Public -License permits, the exception does not apply to the code that you add -in this way. To avoid misleading anyone as to the status of such -modified files, you must delete this exception notice from them. - -If you write modifications of your own for GUILE, it is your choice -whether to permit this exception to apply to your modifications. If you -do not wish that, delete this exception notice. -@end quotation - - -@iftex -@section Layout of this Manual -@end iftex - -@ifnottex -@node Manual Layout -@chapter Layout of this Manual -@end ifnottex - -This manual is divided into five parts. - -@strong{Part I: Introduction to Guile} provides an overview of what -Guile is and how you can use it. A whirlwind tour shows how Guile can -be used interactively and as a script interpreter, how to link Guile -into your own applications, and how to write modules of interpreted and -compiled code for use with Guile. All of the ideas introduced here are -documented in full by the later parts of the manual. - -@strong{Part II: Guile Scheme} documents the core Scheme language and -features that Guile implements. Although the basis for this is the -Scheme language described in R5RS, this part of the manual does not -assume any prior familiarity with R5RS in particular, or with Scheme in -general. Basic Scheme concepts, standard aspects of the Scheme language -and Guile extensions on top of R5RS are all documented from scratch, and -organized by functionality rather than by the defining standards. - -@strong{Part III: Guile Modules} describes some important modules, -distributed as part of the Guile distribution, that extend the -functionality provided by the Guile Scheme core, most notably: - -@itemize @bullet -@item -the POSIX module, which provides Scheme level procedures for system and -network programming, conforming to the POSIX standard - -@item -the SLIB module, which makes Aubrey Jaffer's portable Scheme library -available for use in Guile. -@end itemize - -@strong{Part IV: Guile Scripting} documents the use of Guile as a script -interpreter, and illustrates this with a series of examples. - -@strong{Part V: Extending Applications Using Guile} explains the options -available for using Guile as a application extension language. At the -simpler end of the scale, an application might use Guile to define some -application-specific primitives in C and then load an application Scheme -file. In this case most of the application code is written on the -Scheme level, and uses the application-specific primitives as an -extension to standard Scheme. At the other end of the scale, an -application might be predominantly written in C --- with its main -control loop implemented in C --- but make occasional forays into Scheme -to, say, read configuration data or run user-defined customization code. -This part of the manual covers the complete range of application -extension options. - -Finally, the appendices explain how to obtain the latest version of -Guile, how to install it, where to find modules to work with Guile, and -how to use the Guile debugger. - - -@iftex -@section Manual Conventions -@end iftex - -@ifnottex -@node Manual Conventions -@chapter Conventions used in this Manual -@end ifnottex - -We use some conventions in this manual. - -@itemize @bullet - -@item -For some procedures, notably type predicates, we use @dfn{iff} to -mean `if and only if'. The construct is usually something like: -`Return @var{val} iff @var{condition}', where @var{val} is usually -`@code{#t}' or `non-@code{#f}'. This typically means that @var{val} -is returned if @var{condition} holds, and that @samp{#f} is returned -otherwise. -@cindex iff - -@c Add other conventions here. - -@end itemize - - -@c Local Variables: -@c TeX-master: "guile.texi" -@c End: diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi index 0aaf527a3..120a2b638 100755 --- a/doc/scheme-data.texi +++ b/doc/scheme-data.texi @@ -4784,6 +4784,98 @@ capitals @subsection Hash Tables @tpindex Hash Tables +@c 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. + +@menu +* Hash Table Examples:: Demonstration of hash table usage. +* Hash Table Reference:: Hash table procedure descriptions. +@end menu + + +@node Hash Table Examples +@subsubsection Hash Table Examples + +@c 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. + +@lisp +(define h (make-hash-table 31)) + +(hashq-create-handle! h 'foo "bar") +@result{} +(foo . "bar") + +(hashq-create-handle! h 'braz "zonk") +@result{} +(braz . "zonk") + +(hashq-create-handle! h 'frob #f) +@result{} +(frob . #f) +@end lisp + +You can get the value for a given key with the procedure +@code{hashq-ref}, 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. + +@lisp +(hashq-ref h 'foo) +@result{} +"bar" + +(hashq-ref h 'frob) +@result{} +#f + +(hashq-ref h 'not-there) +@result{} +#f +@end 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. + +@lisp +(hashq-get-handle h 'foo) +@result{} +(foo . "bar") + +(hashq-get-handle h 'not-there) +@result{} +#f +@end 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. + +@lisp +(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h) +@result{} +3 +@end lisp + +@node Hash Table Reference +@subsubsection 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 @@ The arguments to PROC are "(key value prior-result)" where key 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