From 30e40dd034da5d1396d05e09fc4c89f01f959512 Mon Sep 17 00:00:00 2001 From: Carl Sorensen Date: Sat, 19 Dec 2009 22:35:33 -0700 Subject: [PATCH] Doc -- Extending, Scheme tutorial -- add hash-table section --- Documentation/extending/scheme-tutorial.itely | 43 +++++++++++++++++-- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely index f8405b7193..7d97220a5d 100644 --- a/Documentation/extending/scheme-tutorial.itely +++ b/Documentation/extending/scheme-tutorial.itely @@ -255,8 +255,6 @@ Abelson, see @unnumberedsubsubsec Lists -TODO -- write about lists - A very common Scheme data structure is the @emph{list}. Formally, a list is defined as either the empty list (represented as @code{'()}, or a pair whose @code{cdr} is a list. @@ -311,10 +309,49 @@ Alists are widely used in LilyPond to store properties and other data. @unnumberedsubsubsec Hash tables +A data structure that is used occasionally in LilyPond. A hash table +is similar to an array, but the indexes to the array can be any type +of Scheme value, not just integers. + +Hash tables are more efficient than alists if there is a lot of data +to store and the data changes very infrequently. +The syntax to create hash tables is a bit complex, but you +can see examples of it in the LilyPond source. -TODO -- write about hash tables +@lisp +guile> (define h (make-hash-table 10)) +guile> h +# +guile> (hashq-set! h 'key1 "val1") +"val1" +guile> (hashq-set! h 'key2 "val2") +"val2" +guile> (hashq-set! h 3 "val3") +"val3" +@end lisp +Values are retrieved from hash tables with @code{hashq-ref}. + +@lisp +guile> (hashq-ref h 3) +"val3" +guile> (hashq-ref h 'key2) +"val2" +guile> +@end lisp + +Keys and values are retrieved as a pair with @code{hashq-get-handle}. +This is a preferred way, because it will return @code{#f} if a key is +not found. + +@lisp +guile> (hashq-get-handle h 'key1) +(key1 . "val1") +guile> (hashq-get-handle h 'frob) +#f +guile> +@end lisp @node Calculations in Scheme @subsection Calculations in Scheme -- 2.39.5