(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
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
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}
@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
processed by @var{function}.
@end defun
+
@node Weak Hash Tables
@section Weak Hash Tables
@cindex hash table, weak
(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}.
projects / chise / xemacs-chise.git.1 / blobdiff