Mercurial > hg > xemacs-beta

comparison man/lispref/hash-tables.texi @ 412:697ef44129c6 r21-2-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-14
author cvs
date Mon, 13 Aug 2007 11:20:41 +0200
parents 74fd4e045ea6
children 11054d720c21
comparison
equal deleted inserted replaced
411:12e008d41344 412:697ef44129c6
70 70
71 The structure syntax accepts the same keywords as @code{make-hash-table} 71 The structure syntax accepts the same keywords as @code{make-hash-table}
72 (without the @code{:} character), as well as the additional keyword 72 (without the @code{:} character), as well as the additional keyword
73 @code{data}, which specifies the initial hash table contents. 73 @code{data}, which specifies the initial hash table contents.
74 74
75 @defun make-hash-table &key @code{test} @code{size} @code{rehash-size} @code{rehash-threshold} @code{weakness} 75 @defun make-hash-table &key @code{:size} @code{:test} @code{:type} @code{:rehash-size} @code{:rehash-threshold}
76 This function returns a new empty hash table object. 76 This function returns a new empty hash table object.
77
78 Keyword @code{:size} specifies the number of keys likely to be inserted.
79 This number of entries can be inserted without enlarging the hash table.
77 80
78 Keyword @code{:test} can be @code{eq}, @code{eql} (default) or @code{equal}. 81 Keyword @code{:test} can be @code{eq}, @code{eql} (default) or @code{equal}.
79 Comparison between keys is done using this function. 82 Comparison between keys is done using this function.
80 If speed is important, consider using @code{eq}. 83 If speed is important, consider using @code{eq}.
81 When storing strings in the hash table, you will likely need to use @code{equal}. 84 When storing strings in the hash table, you will likely need to use @code{equal}.
82 85
83 Keyword @code{:size} specifies the number of keys likely to be inserted. 86 Keyword @code{:type} can be @code{non-weak} (default), @code{weak},
84 This number of entries can be inserted without enlarging the hash table. 87 @code{key-weak} or @code{value-weak}.
85
86 Keyword @code{:rehash-size} must be a float greater than 1.0, and specifies
87 the factor by which to increase the size of the hash table when enlarging.
88
89 Keyword @code{:rehash-threshold} must be a float between 0.0 and 1.0,
90 and specifies the load factor of the hash table which triggers enlarging.
91
92 Keyword @code{:weakness} can be @code{nil} (default), @code{t},
93 @code{key} or @code{value}.
94 88
95 A weak hash table is one whose pointers do not count as GC referents: 89 A weak hash table is one whose pointers do not count as GC referents:
96 for any key-value pair in the hash table, if the only remaining pointer 90 for any key-value pair in the hash table, if the only remaining pointer
97 to either the key or the value is in a weak hash table, then the pair 91 to either the key or the value is in a weak hash table, then the pair
98 will be removed from the hash table, and the key and value collected. 92 will be removed from the hash table, and the key and value collected.
108 A value-weak hash table is similar to a fully-weak hash table except 102 A value-weak hash table is similar to a fully-weak hash table except
109 that a key-value pair will be removed only if the value remains 103 that a key-value pair will be removed only if the value remains
110 unmarked outside of weak hash tables. The pair will remain in the 104 unmarked outside of weak hash tables. The pair will remain in the
111 hash table if the value is pointed to by something other than a weak 105 hash table if the value is pointed to by something other than a weak
112 hash table, even if the key is not. 106 hash table, even if the key is not.
107
108 Keyword @code{:rehash-size} must be a float greater than 1.0, and specifies
109 the factor by which to increase the size of the hash table when enlarging.
110
111 Keyword @code{:rehash-threshold} must be a float between 0.0 and 1.0,
112 and specifies the load factor of the hash table which triggers enlarging.
113 @end defun 113 @end defun
114 114
115 @defun copy-hash-table hash-table 115 @defun copy-hash-table hash-table
116 This function returns a new hash table which contains the same keys and 116 This function returns a new hash table which contains the same keys and
117 values as @var{hash-table}. The keys and values will not themselves be 117 values as @var{hash-table}. The keys and values will not themselves be
120 120
121 @defun hash-table-count hash-table 121 @defun hash-table-count hash-table
122 This function returns the number of entries in @var{hash-table}. 122 This function returns the number of entries in @var{hash-table}.
123 @end defun 123 @end defun
124 124
125 @defun hash-table-size hash-table
126 This function returns the current number of slots in @var{hash-table},
127 whether occupied or not.
128 @end defun
129
130 @defun hash-table-type hash-table
131 This function returns the type of @var{hash-table}.
132 This can be one of @code{non-weak}, @code{weak}, @code{key-weak} or
133 @code{value-weak}.
134 @end defun
135
125 @defun hash-table-test hash-table 136 @defun hash-table-test hash-table
126 This function returns the test function of @var{hash-table}. 137 This function returns the test function of @var{hash-table}.
127 This can be one of @code{eq}, @code{eql} or @code{equal}. 138 This can be one of @code{eq}, @code{eql} or @code{equal}.
128 @end defun
129
130 @defun hash-table-size hash-table
131 This function returns the current number of slots in @var{hash-table},
132 whether occupied or not.
133 @end defun 139 @end defun
134 140
135 @defun hash-table-rehash-size hash-table 141 @defun hash-table-rehash-size hash-table
136 This function returns the current rehash size of @var{hash-table}. 142 This function returns the current rehash size of @var{hash-table}.
137 This is a float greater than 1.0; the factor by which @var{hash-table} 143 This is a float greater than 1.0; the factor by which @var{hash-table}
142 This function returns the current rehash threshold of @var{hash-table}. 148 This function returns the current rehash threshold of @var{hash-table}.
143 This is a float between 0.0 and 1.0; the maximum @dfn{load factor} of 149 This is a float between 0.0 and 1.0; the maximum @dfn{load factor} of
144 @var{hash-table}, beyond which the @var{hash-table} is enlarged by rehashing. 150 @var{hash-table}, beyond which the @var{hash-table} is enlarged by rehashing.
145 @end defun 151 @end defun
146 152
147 @defun hash-table-weakness hash-table
148 This function returns the weakness of @var{hash-table}.
149 This can be one of @code{nil}, @code{t}, @code{key} or @code{value}.
150 @end defun
151
152 @node Working With Hash Tables 153 @node Working With Hash Tables
153 @section Working With Hash Tables 154 @section Working With Hash Tables
154 155
155 @defun puthash key value hash-table 156 @defun puthash key value hash-table
156 This function hashes @var{key} to @var{value} in @var{hash-table}. 157 This function hashes @var{key} to @var{value} in @var{hash-table}.
177 178
178 @var{function} may not modify @var{hash-table}, with the one exception 179 @var{function} may not modify @var{hash-table}, with the one exception
179 that @var{function} may remhash or puthash the entry currently being 180 that @var{function} may remhash or puthash the entry currently being
180 processed by @var{function}. 181 processed by @var{function}.
181 @end defun 182 @end defun
182
183 183
184 @node Weak Hash Tables 184 @node Weak Hash Tables
185 @section Weak Hash Tables 185 @section Weak Hash Tables
186 @cindex hash table, weak 186 @cindex hash table, weak
187 @cindex weak hash table 187 @cindex weak hash table
218 of the table, regardless of how the key is referenced. 218 of the table, regardless of how the key is referenced.
219 @end table 219 @end table
220 220
221 Also see @ref{Weak Lists}. 221 Also see @ref{Weak Lists}.
222 222
223 Weak hash tables are created by specifying the @code{:weakness} keyword to 223 Weak hash tables are created by specifying the @code{:type} keyword to
224 @code{make-hash-table}. 224 @code{make-hash-table}.