+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
@page
@node Compound Data Types
@chapter Compound Data Types
terminate at that point.
@end deffn
+@c C Function scm_cons_star(arg1,rest) used to be documented here,
+@c but it's not really a useful interface, since it expects the
+@c caller to have already consed up all but the first argument
+@c already.
+@c
@deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
-@deffnx {C Function} scm_cons_star (arg1, rest)
Like @code{list}, but the last arg provides the tail of the
constructed list, returning @code{(cons @var{arg1} (cons
@var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
variants.
@rnindex append
-@deffn {Scheme Procedure} append . args
-@deffnx {C Function} scm_append (args)
-Return a list consisting of the elements the lists passed as
-arguments.
+@deffn {Scheme Procedure} append lst1 @dots{} lstN
+@deffnx {Scheme Procedure} append! lst1 @dots{} lstN
+@deffnx {C Function} scm_append (lstlst)
+@deffnx {C Function} scm_append_x (lstlst)
+Return a list comprising all the elements of lists @var{lst1} to
+@var{lstN}.
+
@lisp
(append '(x) '(y)) @result{} (x y)
(append '(a) '(b c d)) @result{} (a b c d)
(append '(a (b)) '((c))) @result{} (a (b) (c))
@end lisp
-The resulting list is always newly allocated, except that it
-shares structure with the last list argument. The last
-argument may actually be any object; an improper list results
-if the last argument is not a proper list.
+
+The last argument @var{lstN} may actually be any object; an improper
+list results if the last argument is not a proper list.
+
@lisp
(append '(a b) '(c . d)) @result{} (a b c . d)
(append '() 'a) @result{} a
@end lisp
-@end deffn
-@deffn {Scheme Procedure} append! . lists
-@deffnx {C Function} scm_append_x (lists)
-A destructive version of @code{append} (@pxref{Pairs and
-lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
-of each list's final pair is changed to point to the head of
-the next list, so no consing is performed. Return a pointer to
-the mutated list.
+@code{append} doesn't modify the given lists, but the return may share
+structure with the final @var{lstN}. @code{append!} modifies the
+given lists to form its return.
+
+For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
+of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst}
+itself is not modified or used in the return.
@end deffn
@rnindex reverse
@deffn {Scheme Procedure} reverse lst
+@deffnx {Scheme Procedure} reverse! lst [newtail]
@deffnx {C Function} scm_reverse (lst)
-Return a new list that contains the elements of @var{lst} but
-in reverse order.
-@end deffn
+@deffnx {C Function} scm_reverse_x (lst, newtail)
+Return a list comprising the elements of @var{lst}, in reverse order.
-@c NJFIXME explain new_tail
-@deffn {Scheme Procedure} reverse! lst [new_tail]
-@deffnx {C Function} scm_reverse_x (lst, new_tail)
-A destructive version of @code{reverse} (@pxref{Pairs and lists,,,r5rs,
-The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
-modified to point to the previous list element. Return a pointer to the
-head of the reversed list.
+@code{reverse} constructs a new list, @code{reverse!} modifies
+@var{lst} in constructing its return.
-Caveat: because the list is modified in place, the tail of the original
-list now becomes its head, and the head of the original list now becomes
-the tail. Therefore, the @var{lst} symbol to which the head of the
-original list was bound now points to the tail. To ensure that the head
-of the modified list is not lost, it is wise to save the return value of
-@code{reverse!}
+For @code{reverse!}, the optional @var{newtail} is appended to to the
+result. @var{newtail} isn't reversed, it simply becomes the list
+tail. For @code{scm_reverse_x}, the @var{newtail} parameter is
+mandatory, but can be @code{SCM_EOL} if no further tail is required.
@end deffn
@node List Modification
@code{equal?}. See also @code{delq1!} and @code{delv1!}.
@end deffn
+@deffn {Scheme Procedure} filter pred lst
+@deffnx {Scheme Procedure} filter! pred lst
+Return a list containing all elements from @var{lst} which satisfy the
+predicate @var{pred}. The elements in the result list have the same
+order as in @var{lst}. The order in which @var{pred} is applied to
+the list elements is not specified.
+
+@code{filter!} is allowed, but not required to modify the structure of
+@end deffn
+
@node List Searching
@subsection List Searching
'l signed long long (integer) l
1.0 float (single precision) s
1/3 double (double precision float) i
+[FIXME: This (1/3) no longer works due to the
+ new support for rational numbers.]
0+i complex (double precision) c
() conventional vector
@end example
@example
(make-uniform-vector 8 #t #f) @result{}
#*00000000
-
-#b(#t #f #t) @result{}
-#*101
@end example
-@deffn {Scheme Procedure} bit-count b bitvector
-@deffnx {C Function} scm_bit_count (b, bitvector)
-Return the number of occurrences of the boolean @var{b} in
-@var{bitvector}.
+@deffn {Scheme Procedure} bit-count bool bitvector
+@deffnx {C Function} scm_bit_count (bool, bitvector)
+Return a count of how many entries in @var{bitvector} are equal to
+@var{bool}. For example,
+
+@example
+(bit-count #f #*000111000) @result{} 6
+@end example
@end deffn
-@deffn {Scheme Procedure} bit-position item v k
-@deffnx {C Function} scm_bit_position (item, v, k)
-Return the minimum index of an occurrence of @var{bool} in
-@var{bv} which is at least @var{k}. If no @var{bool} occurs
-within the specified range @code{#f} is returned.
+@deffn {Scheme Procedure} bit-position bool bitvector start
+@deffnx {C Function} scm_bit_position (bool, bitvector, start)
+Return the index of the first occurrance of @var{bool} in
+@var{bitvector}, starting from @var{start}. If there is no @var{bool}
+entry between @var{start} and the end of @var{bitvector}, then return
+@code{#f}. For example,
+
+@example
+(bit-position #t #*000101 0) @result{} 3
+(bit-position #f #*0001111 3) @result{} #f
+@end example
@end deffn
-@deffn {Scheme Procedure} bit-invert! v
-@deffnx {C Function} scm_bit_invert_x (v)
-Modify @var{bv} by replacing each element with its negation.
+@deffn {Scheme Procedure} bit-invert! bitvector
+@deffnx {C Function} scm_bit_invert_x (bitvector)
+Modify @var{bitvector} by replacing each element with its negation.
@end deffn
-@deffn {Scheme Procedure} bit-set*! v kv obj
-@deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
-If uve is a bit-vector @var{bv} and uve must be of the same
-length. If @var{bool} is @code{#t}, uve is OR'ed into
-@var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
-AND'ed into @var{bv}.
+@deffn {Scheme Procedure} bit-set*! bitvector uvec bool
+@deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool)
+Set entries of @var{bitvector} to @var{bool}, with @var{uvec}
+selecting the entries to change.
+
+If @var{uvec} is a bit vector, then those entries where it has
+@code{#t} are the ones in @var{bitvector} which are set to @var{bool}.
+When @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
+@var{bitvector}. Or when @var{bool} is @code{#f} it can be seen as an
+ANDNOT.
-If uve is a unsigned long integer vector all the elements of uve
-must be between 0 and the @code{length} of @var{bv}. The bits
-of @var{bv} corresponding to the indexes in uve are set to
-@var{bool}. The return value is unspecified.
+@example
+(define bv #*01000010)
+(bit-set*! bv #*10010001 #t)
+bv
+@result{} #*11010011
+@end example
+
+If @var{uvec} is a uniform vector of unsigned long integers, then
+they're indexes into @var{bitvector} which are set to @var{bool}.
+
+@example
+(define bv #*01000010)
+(bit-set*! bv #u(5 2 7) #t)
+bv
+@result{} #*01100111
+@end example
@end deffn
-@deffn {Scheme Procedure} bit-count* v kv obj
-@deffnx {C Function} scm_bit_count_star (v, kv, obj)
-Return
-@lisp
-(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
-@end lisp
-@var{bv} is not modified.
+@deffn {Scheme Procedure} bit-count* bitvector uvec bool
+@deffnx {C Function} scm_bit_count_star (bitvector, uvec, bool)
+Return a count of how many entries in @var{bitvector} are equal to
+@var{bool}, with @var{uvec} selecting the entries to consider.
+
+@var{uvec} is interpreted in the same way as for @code{bit-set*!}
+above. Namely, if @var{uvec} is a bit vector then entries which have
+@code{#t} there are considered in @var{bitvector}. Or if @var{uvec}
+is a uniform vector of unsigned long integers then it's the indexes in
+@var{bitvector} to consider.
+
+For example,
+
+@example
+(bit-count* #*01110111 #*11001101 #t) @result{} 3
+(bit-count* #*01110111 #u(7 0 4) #f) @result{} 2
+@end example
@end deffn
@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
-keys match. The @code{hashv} functions use @code{eqv?}, and the
-@code{hash} functions use @code{equal?}.
+@c FIXME: Describe in broad terms what happens for resizing, and what
+@c the initial size means for this.
+
+Like the association list functions, the hash table functions come in
+several varieties, according to the equality test used for the keys.
+Plain @code{hash-} functions use @code{equal?}, @code{hashq-}
+functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and
+the @code{hashx-} functions use an application supplied test.
+
+A single @code{make-hash-table} creates a hash table suitable for use
+with any set of functions, but it's imperative that just one set is
+then used consistently, or results will be unpredictable.
+
+@sp 1
+Hash tables are implemented as a vector indexed by a hash value formed
+from the key, with an association list of key/value pairs for each
+bucket in case distinct keys hash together. Direct access to the
+pairs in those lists is provided by the @code{-handle-} functions.
+
+When the number of table entries goes above a threshold the vector is
+increased and the entries rehashed, to prevent the bucket lists
+becoming too long and slowing down accesses. When the number of
+entries goes below a threshold the vector is decreased to save space.
+
+@sp 1
+For the @code{hashx-} ``extended'' routines, an application supplies a
+@var{hash} function producing an integer index like @code{hashq} etc
+below, and an @var{assoc} alist search function like @code{assq} etc
+(@pxref{Retrieving Alist Entries}). Here's an example of such
+functions implementing case-insensitive hashing of string keys,
-In each of the functions that follow, the @var{table} argument
-must be a vector. The @var{key} and @var{value} arguments may be
-any Scheme object.
+@example
+(use-modules (srfi srfi-1)
+ (srfi srfi-13))
-@deffn {Scheme Procedure} make-hash-table size
-Create a new hash table of @var{size} slots. Note that the number of
-slots does not limit the size of the table, it just tells how large
-the underlying vector will be. The @var{size} should be similar to
-the expected number of elements which will be added to the table, but
-they need not match. For good performance, it might be a good idea to
-use a prime number as the @var{size}.
-@end deffn
+(define (my-hash str size)
+ (remainder (string-hash-ci str) size))
+(define (my-assoc str alist)
+ (find (lambda (pair) (string-ci=? str (car pair))) alist))
-@deffn {Scheme Procedure} hashq-ref table key [dflt]
-@deffnx {C Function} scm_hashq_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eq?} for equality testing.
-@end deffn
+(define my-table (make-hash-table))
+(hashx-set! my-hash my-assoc my-table "foo" 123)
-@deffn {Scheme Procedure} hashv-ref table key [dflt]
-@deffnx {C Function} scm_hashv_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eqv?} for equality testing.
-@end deffn
+(hashx-ref my-hash my-assoc my-table "FOO")
+@result{} 123
+@end example
-@deffn {Scheme Procedure} hash-ref table key [dflt]
-@deffnx {C Function} scm_hash_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{equal?} for equality testing.
-@end deffn
+In a @code{hashx-} @var{hash} function the aim is to spread keys
+across the vector, so bucket lists don't become long. But the actual
+values are arbitrary as long as they're in the range 0 to
+@math{@var{size}-1}. Helpful functions for forming a hash value, in
+addition to @code{hashq} etc below, include @code{symbol-hash}
+(@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci}
+(@pxref{SRFI-13 Comparison}), and @code{char-set-hash} (@pxref{SRFI-14
+Predicates/Comparison}).
-@deffn {Scheme Procedure} hashq-set! table key val
-@deffnx {C Function} scm_hashq_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eq?} for equality testing.
-@end deffn
+Note that currently, unfortunately, there's no @code{hashx-remove!}
+function, which rather limits the usefulness of the @code{hashx-}
+routines.
-@deffn {Scheme Procedure} hashv-set! table key val
-@deffnx {C Function} scm_hashv_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eqv?} for equality testing.
-@end deffn
+@sp 1
+@deffn {Scheme Procedure} make-hash-table [size]
+Create a new hash table, with an optional minimum vector @var{size}.
-@deffn {Scheme Procedure} hash-set! table key val
-@deffnx {C Function} scm_hash_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{equal?} for equality
-testing.
+When @var{size} is given, the table vector will still grow and shrink
+automatically, as described above, but with @var{size} as a minimum.
+If an application knows roughly how many entries the table will hold
+then it can use @var{size} to avoid rehashing when initial entries are
+added.
@end deffn
-@deffn {Scheme Procedure} hashq-remove! table key
-@deffnx {C Function} scm_hashq_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eq?} for equality tests.
+@deffn {Scheme Procedure} hash-ref table key [dflt]
+@deffnx {Scheme Procedure} hashq-ref table key [dflt]
+@deffnx {Scheme Procedure} hashv-ref table key [dflt]
+@deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt]
+@deffnx {C Function} scm_hash_ref (table, key, dflt)
+@deffnx {C Function} scm_hashq_ref (table, key, dflt)
+@deffnx {C Function} scm_hashv_ref (table, key, dflt)
+@deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
+Lookup @var{key} in the given hash @var{table}, and return the
+associated value. If @var{key} is not found, return @var{dflt}, or
+@code{#f} if @var{dflt} is not given. (For the C functions,
+@var{dflt} must be given.)
@end deffn
-@deffn {Scheme Procedure} hashv-remove! table key
-@deffnx {C Function} scm_hashv_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eqv?} for equality tests.
+@deffn {Scheme Procedure} hash-set! table key val
+@deffnx {Scheme Procedure} hashq-set! table key val
+@deffnx {Scheme Procedure} hashv-set! table key val
+@deffnx {Scheme Procedure} hashx-set! hash assoc table key val
+@deffnx {C Function} scm_hash_set_x (table, key, val)
+@deffnx {C Function} scm_hashq_set_x (table, key, val)
+@deffnx {C Function} scm_hashv_set_x (table, key, val)
+@deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
+Associate @var{val} with @var{key} in the given hash @var{table}. If
+@var{key} is already present then it's associated value is changed.
+If it's not present then a new entry is created.
@end deffn
@deffn {Scheme Procedure} hash-remove! table key
+@deffnx {Scheme Procedure} hashq-remove! table key
+@deffnx {Scheme Procedure} hashv-remove! table key
@deffnx {C Function} scm_hash_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{equal?} for equality tests.
-@end deffn
-
-The standard hash table functions may be too limited for some
-applications. For example, you may want a hash table to store
-strings in a case-insensitive manner, so that references to keys
-named ``foobar'', ``FOOBAR'' and ``FooBaR'' will all yield the
-same item. Guile provides you with @dfn{extended} hash tables
-that permit you to specify a hash function and associator function
-of your choosing. The functions described in the rest of this section
-can be used to implement such custom hash table structures.
-
-If you are unfamiliar with the inner workings of hash tables, then
-this facility will probably be a little too abstract for you to
-use comfortably. If you are interested in learning more, see an
-introductory textbook on data structures or algorithms for an
-explanation of how hash tables are implemented.
-
-@deffn {Scheme Procedure} hashq key size
-@deffnx {C Function} scm_hashq (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eq?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{hashq} may use internal addresses. Thus two calls to
-hashq where the keys are @code{eq?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
-@deffn {Scheme Procedure} hashv key size
-@deffnx {C Function} scm_hashv (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eqv?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{(hashv key)} may use internal addresses. Thus two calls
-to hashv where the keys are @code{eqv?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
+@deffnx {C Function} scm_hashq_remove_x (table, key)
+@deffnx {C Function} scm_hashv_remove_x (table, key)
+Remove any association for @var{key} in the given hash @var{table}.
+If @var{key} is not in @var{table} then nothing is done.
@end deffn
@deffn {Scheme Procedure} hash key size
+@deffnx {Scheme Procedure} hashq key size
+@deffnx {Scheme Procedure} hashv key size
@deffnx {C Function} scm_hash (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{equal?}
-is used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
-@deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
-This behaves the same way as the corresponding @code{ref}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
-By way of illustration, @code{hashq-ref table key} is
-equivalent to @code{hashx-ref hashq assq table key}.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-set! hash assoc table key val
-@deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
-This behaves the same way as the corresponding @code{set!}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
+@deffnx {C Function} scm_hashq (key, size)
+@deffnx {C Function} scm_hashv (key, size)
+Return a hash value for @var{key}. This is a number in the range
+@math{0} to @math{@var{size}-1}, which is suitable for use in a hash
+table of the given @var{size}.
- By way of illustration, @code{hashq-set! table key} is
-equivalent to @code{hashx-set! hashq assq table key}.
-@end deffn
+Note that @code{hashq} and @code{hashv} may use internal addresses of
+objects, so if an object is garbage collected and re-created it can
+have a different hash value, even when the two are notionally
+@code{eq?}. For instance with symbols,
-@deffn {Scheme Procedure} hashq-get-handle table key
-@deffnx {C Function} scm_hashq_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eq?} for equality testing.
-@end deffn
+@example
+(hashq 'something 123) @result{} 19
+(gc)
+(hashq 'something 123) @result{} 62
+@end example
-@deffn {Scheme Procedure} hashv-get-handle table key
-@deffnx {C Function} scm_hashv_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eqv?} for equality testing.
+In normal use this is not a problem, since an object entered into a
+hash table won't be garbage collected until removed. It's only if
+hashing calculations are somehow separated from normal references that
+its lifetime needs to be considered.
@end deffn
@deffn {Scheme Procedure} hash-get-handle table key
+@deffnx {Scheme Procedure} hashq-get-handle table key
+@deffnx {Scheme Procedure} hashv-get-handle table key
+@deffnx {Scheme Procedure} hashx-get-handle hash assoc table key
@deffnx {C Function} scm_hash_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{equal?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-get-handle hash assoc table key
+@deffnx {C Function} scm_hashq_get_handle (table, key)
+@deffnx {C Function} scm_hashv_get_handle (table, key)
@deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
-This behaves the same way as the corresponding
-@code{-get-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
+Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
+given hash @var{table}, or @code{#f} if @var{key} is not in
+@var{table}.
@end deffn
-@deffn {Scheme Procedure} hashq-create-handle! table key init
+@deffn {Scheme Procedure} hash-create-handle! table key init
+@deffnx {Scheme Procedure} hashq-create-handle! table key init
+@deffnx {Scheme Procedure} hashv-create-handle! table key init
+@deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init
+@deffnx {C Function} scm_hash_create_handle_x (table, key, init)
@deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-create-handle! table key init
@deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
+@deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
+Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
+given hash @var{table}. If @var{key} is not in @var{table} then
+create an entry for it with @var{init} as the value, and return that
+pair.
@end deffn
-@deffn {Scheme Procedure} hash-create-handle! table key init
-@deffnx {C Function} scm_hash_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
+@deffn {Scheme Procedure} hash-map proc table
+@deffnx {Scheme Procedure} hash-for-each proc table
+@deffnx {C Function} scm_hash_map (proc, table)
+@deffnx {C Function} scm_hash_for_each (proc, table)
+Apply @var{proc} to the entries in the given hash @var{table}. Each
+call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map}
+returns a list of the results from these calls, @code{hash-for-each}
+discards the results and returns an unspecified value.
-@deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
-@deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
-This behaves the same way as the corresponding
-@code{-create-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
+Calls are made over the table entries in an unspecified order, and for
+@code{hash-map} the order of the values in the returned list is
+unspecified. Results will be unpredictable if @var{table} is modified
+while iterating.
+
+For example the following returns a new alist comprising all the
+entries from @code{mytable}, in no particular order.
+
+@example
+(hash-map cons mytable)
+@end example
@end deffn
@deffn {Scheme Procedure} hash-fold proc init table
@deffnx {C Function} scm_hash_fold (proc, init, table)
-An iterator over hash-table elements.
-Accumulates and returns a result by applying PROC successively.
-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
-table into an a-list of key-value pairs.
+Accumulate a result by applying @var{proc} to the elements of the
+given hash @var{table}. Each call is @code{(@var{proc} @var{key}
+@var{value} @var{prior-result})}, where @var{key} and @var{value} are
+from the @var{table} and @var{prior-result} is the return from the
+previous @var{proc} call. For the first call, @var{prior-result} is
+the given @var{init} value.
+
+Calls are made over the table entries in an unspecified order.
+Results will be unpredictable if @var{table} is modified while
+@code{hash-fold} is running.
+
+For example, the following returns a count of how many keys in
+@code{mytable} are strings.
+
+@example
+(hash-fold (lambda (key value prior)
+ (if (string? key) (1+ prior) prior))
+ 0 mytable)
+@end example
@end deffn
HCoop / bpt / guile.git / blobdiff