Mercurial > hg > xemacs-beta

comparison man/lispref/hash-tables.texi @ 424:11054d720c21 r21-2-20

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-20
author cvs
date Mon, 13 Aug 2007 11:26:11 +0200
parents 697ef44129c6
children
comparison
equal deleted inserted replaced
423:28d9c139be4c 424:11054d720c21
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{:size} @code{:test} @code{:type} @code{:rehash-size} @code{:rehash-threshold} 75 @defun make-hash-table &key @code{test} @code{size} @code{rehash-size} @code{rehash-threshold} @code{weakness}
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.
80 77
81 Keyword @code{:test} can be @code{eq}, @code{eql} (default) or @code{equal}. 78 Keyword @code{:test} can be @code{eq}, @code{eql} (default) or @code{equal}.
82 Comparison between keys is done using this function. 79 Comparison between keys is done using this function.
83 If speed is important, consider using @code{eq}. 80 If speed is important, consider using @code{eq}.
84 When storing strings in the hash table, you will likely need to use @code{equal}. 81 When storing strings in the hash table, you will likely need to use @code{equal}.
85 82
86 Keyword @code{:type} can be @code{non-weak} (default), @code{weak}, 83 Keyword @code{:size} specifies the number of keys likely to be inserted.
87 @code{key-weak} or @code{value-weak}. 84 This number of entries can be inserted without enlarging the hash table.
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}.
88 94
89 A weak hash table is one whose pointers do not count as GC referents: 95 A weak hash table is one whose pointers do not count as GC referents:
90 for any key-value pair in the hash table, if the only remaining pointer 96 for any key-value pair in the hash table, if the only remaining pointer
91 to either the key or the value is in a weak hash table, then the pair 97 to either the key or the value is in a weak hash table, then the pair
92 will be removed from the hash table, and the key and value collected. 98 will be removed from the hash table, and the key and value collected.
102 A value-weak hash table is similar to a fully-weak hash table except 108 A value-weak hash table is similar to a fully-weak hash table except
103 that a key-value pair will be removed only if the value remains 109 that a key-value pair will be removed only if the value remains
104 unmarked outside of weak hash tables. The pair will remain in the 110 unmarked outside of weak hash tables. The pair will remain in the
105 hash table if the value is pointed to by something other than a weak 111 hash table if the value is pointed to by something other than a weak
106 hash table, even if the key is not. 112 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-test hash-table
126 This function returns the test function of @var{hash-table}.
127 This can be one of @code{eq}, @code{eql} or @code{equal}.
128 @end defun
129
125 @defun hash-table-size hash-table 130 @defun hash-table-size hash-table
126 This function returns the current number of slots in @var{hash-table}, 131 This function returns the current number of slots in @var{hash-table},
127 whether occupied or not. 132 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
136 @defun hash-table-test hash-table
137 This function returns the test function of @var{hash-table}.
138 This can be one of @code{eq}, @code{eql} or @code{equal}.
139 @end defun 133 @end defun
140 134
141 @defun hash-table-rehash-size hash-table 135 @defun hash-table-rehash-size hash-table
142 This function returns the current rehash size of @var{hash-table}. 136 This function returns the current rehash size of @var{hash-table}.
143 This is a float greater than 1.0; the factor by which @var{hash-table} 137 This is a float greater than 1.0; the factor by which @var{hash-table}
148 This function returns the current rehash threshold of @var{hash-table}. 142 This function returns the current rehash threshold of @var{hash-table}.
149 This is a float between 0.0 and 1.0; the maximum @dfn{load factor} of 143 This is a float between 0.0 and 1.0; the maximum @dfn{load factor} of
150 @var{hash-table}, beyond which the @var{hash-table} is enlarged by rehashing. 144 @var{hash-table}, beyond which the @var{hash-table} is enlarged by rehashing.
151 @end defun 145 @end defun
152 146
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
153 @node Working With Hash Tables 152 @node Working With Hash Tables
154 @section Working With Hash Tables 153 @section Working With Hash Tables
155 154
156 @defun puthash key value hash-table 155 @defun puthash key value hash-table
157 This function hashes @var{key} to @var{value} in @var{hash-table}. 156 This function hashes @var{key} to @var{value} in @var{hash-table}.
178 177
179 @var{function} may not modify @var{hash-table}, with the one exception 178 @var{function} may not modify @var{hash-table}, with the one exception
180 that @var{function} may remhash or puthash the entry currently being 179 that @var{function} may remhash or puthash the entry currently being
181 processed by @var{function}. 180 processed by @var{function}.
182 @end defun 181 @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{:type} keyword to 223 Weak hash tables are created by specifying the @code{:weakness} keyword to
224 @code{make-hash-table}. 224 @code{make-hash-table}.