X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Flispref%2Fhash-tables.texi;h=570207230114d0e63c16aaf52d82226249f0206a;hb=682b150413bbb86eadb481299953bc42c8faca92;hp=ddf239b21da173c923e7a8ea3e41361013d3df86;hpb=77dcef404dc78635f6ffa8f71a803d2bc7cc8921;p=chise%2Fxemacs-chise.git- diff --git a/man/lispref/hash-tables.texi b/man/lispref/hash-tables.texi index ddf239b..5702072 100644 --- a/man/lispref/hash-tables.texi +++ b/man/lispref/hash-tables.texi @@ -72,26 +72,34 @@ The structure syntax accepts the same keywords as @code{make-hash-table} (without the @code{:} character), as well as the additional keyword @code{data}, which specifies the initial hash table contents. -@defun make-hash-table &key @code{:size} @code{:test} @code{:type} @code{:rehash-size} @code{:rehash-threshold} +@defun make-hash-table &key @code{test} @code{size} @code{rehash-size} @code{rehash-threshold} @code{weakness} This function returns a new empty hash table object. -Keyword @code{:size} specifies the number of keys likely to be inserted. -This number of entries can be inserted without enlarging the hash table. - Keyword @code{:test} can be @code{eq}, @code{eql} (default) or @code{equal}. Comparison between keys is done using this function. If speed is important, consider using @code{eq}. When storing strings in the hash table, you will likely need to use @code{equal}. -Keyword @code{:type} can be @code{non-weak} (default), @code{weak}, -@code{key-weak} or @code{value-weak}. +Keyword @code{:size} specifies the number of keys likely to be inserted. +This number of entries can be inserted without enlarging the hash table. -A weak hash table is one whose pointers do not count as GC referents: -for any key-value pair in the hash table, if the only remaining pointer -to either the key or the value is in a weak hash table, then the pair -will be removed from the hash table, and the key and value collected. -A non-weak hash table (or any other pointer) would prevent the object -from being collected. +Keyword @code{:rehash-size} must be a float greater than 1.0, and specifies +the factor by which to increase the size of the hash table when enlarging. + +Keyword @code{:rehash-threshold} must be a float between 0.0 and 1.0, +and specifies the load factor of the hash table which triggers enlarging. + +Non-standard keyword @code{:weakness} can be @code{nil} (default), +@code{t}, @code{key-and-value}, @code{key}, @code{value} or +@code{key-or-value}. @code{t} is an alias for @code{key-and-value}. + +A key-and-value-weak hash table, also known as a fully-weak or simply +as a weak hash table, is one whose pointers do not count as GC +referents: for any key-value pair in the hash table, if the only +remaining pointer to either the key or the value is in a weak hash +table, then the pair will be removed from the hash table, and the key +and value collected. A non-weak hash table (or any other pointer) +would prevent the object from being collected. A key-weak hash table is similar to a fully-weak hash table except that a key-value pair will be removed only if the key remains unmarked @@ -105,11 +113,11 @@ unmarked outside of weak hash tables. The pair will remain in the hash table if the value is pointed to by something other than a weak hash table, even if the key is not. -Keyword @code{:rehash-size} must be a float greater than 1.0, and specifies -the factor by which to increase the size of the hash table when enlarging. - -Keyword @code{:rehash-threshold} must be a float between 0.0 and 1.0, -and specifies the load factor of the hash table which triggers enlarging. +A key-or-value-weak hash table is similar to a fully-weak hash table except +that a key-value pair will be removed only if the value and the key remain +unmarked outside of weak hash tables. The pair will remain in the +hash table if the value or key are pointed to by something other than a weak +hash table, even if the other is not. @end defun @defun copy-hash-table hash-table @@ -122,22 +130,16 @@ copied. This function returns the number of entries in @var{hash-table}. @end defun -@defun hash-table-size hash-table -This function returns the current number of slots in @var{hash-table}, -whether occupied or not. -@end defun - -@defun hash-table-type hash-table -This function returns the type of @var{hash-table}. -This can be one of @code{non-weak}, @code{weak}, @code{key-weak} or -@code{value-weak}. -@end defun - @defun hash-table-test hash-table This function returns the test function of @var{hash-table}. This can be one of @code{eq}, @code{eql} or @code{equal}. @end defun +@defun hash-table-size hash-table +This function returns the current number of slots in @var{hash-table}, +whether occupied or not. +@end defun + @defun hash-table-rehash-size hash-table This function returns the current rehash size of @var{hash-table}. This is a float greater than 1.0; the factor by which @var{hash-table} @@ -150,6 +152,11 @@ This is a float between 0.0 and 1.0; the maximum @dfn{load factor} of @var{hash-table}, beyond which the @var{hash-table} is enlarged by rehashing. @end defun +@defun hash-table-weakness hash-table +This function returns the weakness of @var{hash-table}. +This can be one of @code{nil}, @code{t}, @code{key} or @code{value}. +@end defun + @node Working With Hash Tables @section Working With Hash Tables @@ -181,6 +188,7 @@ that @var{function} may remhash or puthash the entry currently being processed by @var{function}. @end defun + @node Weak Hash Tables @section Weak Hash Tables @cindex hash table, weak @@ -204,21 +212,25 @@ remaining around forever, long past their actual period of use. (Otherwise, you'd have to explicitly map over the hash table every so often and remove unnecessary elements.) -There are three types of weak hash tables: +There are four types of weak hash tables: @table @asis -@item fully weak hash tables -In these hash tables, a pair disappears if either the key or the value -is unreferenced outside of the table. +@item key-and-value-weak hash tables +In these hash tables, also known as fully weak or simply as weak hash +tables, a pair disappears if either the key or the value is unreferenced +outside of the table. @item key-weak hash tables In these hash tables, a pair disappears if the key is unreferenced outside of the table, regardless of how the value is referenced. @item value-weak hash tables In these hash tables, a pair disappears if the value is unreferenced outside of the table, regardless of how the key is referenced. +@item key-or-value-weak hash tables +In these hash tables, a pair disappears if both the key and the value +are unreferenced outside of the table. @end table Also see @ref{Weak Lists}. -Weak hash tables are created by specifying the @code{:type} keyword to +Weak hash tables are created by specifying the @code{:weakness} keyword to @code{make-hash-table}.