annotate lispref/hash.texi @ 83474:d08a7ef0cb8a

Merged from emacs@sv.gnu.org Patches applied: * emacs@sv.gnu.org/emacs--devo--0--patch-91 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-92 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-93 Merge from gnus--rel--5.10 * emacs@sv.gnu.org/emacs--devo--0--patch-94 Merge from gnus--rel--5.10 * emacs@sv.gnu.org/emacs--devo--0--patch-95 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-96 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-97 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-98 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-99 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-100 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-101 Update from CVS * emacs@sv.gnu.org/emacs--devo--0--patch-102 Merge from erc--emacs--0 * emacs@sv.gnu.org/emacs--devo--0--patch-103 Update from CVS: src/regex.c (extend_range_table_work_area): Fix typo. * emacs@sv.gnu.org/emacs--devo--0--patch-104 Update from CVS * emacs@sv.gnu.org/gnus--rel--5.10--patch-30 Merge from emacs--devo--0 * emacs@sv.gnu.org/gnus--rel--5.10--patch-31 Update from CVS * emacs@sv.gnu.org/gnus--rel--5.10--patch-32 Update from CVS * emacs@sv.gnu.org/gnus--rel--5.10--patch-33 Update from CVS * emacs@sv.gnu.org/gnus--rel--5.10--patch-34 Update from CVS * emacs@sv.gnu.org/gnus--rel--5.10--patch-35 Merge from emacs--devo--0 * emacs@sv.gnu.org/gnus--rel--5.10--patch-36 Update from CVS git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-514
author Karoly Lorentey <lorentey@elte.hu>
date Mon, 20 Feb 2006 16:30:15 +0000
parents 067115a6e738
children c68bfe90878a c5406394f567
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
68648
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
3 @c Copyright (C) 1999, 2002, 2003, 2004, 2005,
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
4 @c 2006 Free Software Foundation, Inc.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Hash Tables, Symbols, Sequences Arrays Vectors, Top
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Hash Tables
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex hash tables
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 A hash table is a very fast kind of lookup table, somewhat like
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 an alist in that it maps keys to corresponding values. It differs
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 from an alist in these ways:
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 @itemize @bullet
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 @item
26710
ed440ffea308 (Hash Tables): Note that alists win for small tables.
Dave Love <fx@gnu.org>
parents: 26303
diff changeset
17 Lookup in a hash table is extremely fast for large tables---in fact, the
ed440ffea308 (Hash Tables): Note that alists win for small tables.
Dave Love <fx@gnu.org>
parents: 26303
diff changeset
18 time required is essentially @emph{independent} of how many elements are
ed440ffea308 (Hash Tables): Note that alists win for small tables.
Dave Love <fx@gnu.org>
parents: 26303
diff changeset
19 stored in the table. For smaller tables (a few tens of elements)
ed440ffea308 (Hash Tables): Note that alists win for small tables.
Dave Love <fx@gnu.org>
parents: 26303
diff changeset
20 alists may still be faster because hash tables have a more-or-less
ed440ffea308 (Hash Tables): Note that alists win for small tables.
Dave Love <fx@gnu.org>
parents: 26303
diff changeset
21 constant overhead.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 @item
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 The correspondences in a hash table are in no particular order.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 @item
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 There is no way to share structure between two hash tables,
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 the way two alists can share a common tail.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @end itemize
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
60446
b26c30e5d770 (Hash Tables): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 60039
diff changeset
31 Emacs Lisp provides a general-purpose hash table data type, along
b26c30e5d770 (Hash Tables): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 60039
diff changeset
32 with a series of functions for operating on them. Hash tables have no
b26c30e5d770 (Hash Tables): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 60039
diff changeset
33 read syntax, and print in hash notation, like this:
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @example
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 (make-hash-table)
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @result{} #<hash-table 'eql nil 0/65 0x83af980>
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @end example
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39
26303
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
40 @noindent
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
41 (The term ``hash notation'' refers to the initial @samp{#}
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
42 character---@pxref{Printed Representation}---and has nothing to do with
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
43 the term ``hash table.'')
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
44
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 Obarrays are also a kind of hash table, but they are a different type
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 of object and are used only for recording interned symbols
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 (@pxref{Creating Symbols}).
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @menu
60039
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
50 * Creating Hash:: Functions to create hash tables.
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
51 * Hash Access:: Reading and writing the hash table contents.
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
52 * Defining Hash:: Defining new comparison methods
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
53 * Other Hash:: Miscellaneous.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 @end menu
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 @node Creating Hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @section Creating Hash Tables
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 The principal function for creating a hash table is
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 @code{make-hash-table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 @tindex make-hash-table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @defun make-hash-table &rest keyword-args
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 This function creates a new hash table according to the specified
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 arguments. The arguments should consist of alternating keywords
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 (particular symbols recognized specially) and values corresponding to
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 them.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 Several keywords make sense in @code{make-hash-table}, but the only two
26182
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
70 that you really need to know about are @code{:test} and @code{:weakness}.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @table @code
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @item :test @var{test}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 This specifies the method of key lookup for this hash table. The
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 default is @code{eql}; @code{eq} and @code{equal} are other
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 alternatives:
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @table @code
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @item eql
53025
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
80 Keys which are numbers are ``the same'' if they are @code{equal}, that
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
81 is, if they are equal in value and either both are integers or both
53037
9958d8677feb *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53025
diff changeset
82 are floating point numbers; otherwise, two distinct objects are never
9958d8677feb *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53025
diff changeset
83 ``the same''.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @item eq
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 Any two distinct Lisp objects are ``different'' as keys.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @item equal
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 Two Lisp objects are ``the same'', as keys, if they are equal
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 according to @code{equal}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @end table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 define additional possibilities for @var{test}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @item :weakness @var{weak}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 The weakness of a hash table specifies whether the presence of a key or
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 value in the hash table preserves it from garbage collection.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 The value, @var{weak}, must be one of @code{nil}, @code{key},
30524
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
101 @code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
54263
41fd82e27495 (Creating Hash): Correct the meaning of t for WEAK in make-hash-table.
Richard M. Stallman <rms@gnu.org>
parents: 54031
diff changeset
102 which is an alias for @code{key-and-value}. If @var{weak} is @code{key}
30524
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
103 then the hash table does not prevent its keys from being collected as
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
104 garbage (if they are not referenced anywhere else); if a particular key
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
105 does get collected, the corresponding association is removed from the
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
106 hash table.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107
30524
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
108 If @var{weak} is @code{value}, then the hash table does not prevent
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
109 values from being collected as garbage (if they are not referenced
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
110 anywhere else); if a particular value does get collected, the
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 corresponding association is removed from the hash table.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
54031
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
113 If @var{weak} is @code{key-and-value} or @code{t}, both the key and
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
114 the value must be live in order to preserve the association. Thus,
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
115 the hash table does not protect either keys or values from garbage
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
116 collection; if either one is collected as garbage, that removes the
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
117 association.
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
118
54031
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
119 If @var{weak} is @code{key-or-value}, either the key or
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
120 the value can preserve the association. Thus, associations are
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
121 removed from the hash table when both their key and value would be
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
122 collected as garbage (if not for references from weak hash tables).
30524
62ed067637af *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26710
diff changeset
123
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 The default for @var{weak} is @code{nil}, so that all keys and values
54031
fcad69b9ff7b (Creating Hash): Correct and clarify doc of WEAK values.
Richard M. Stallman <rms@gnu.org>
parents: 53480
diff changeset
125 referenced in the hash table are preserved from garbage collection.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 @item :size @var{size}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 This specifies a hint for how many associations you plan to store in the
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 hash table. If you know the approximate number, you can make things a
26182
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
130 little more efficient by specifying it this way. If you specify too
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 small a size, the hash table will grow automatically when necessary, but
26303
9b25d0ffe4ec Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26182
diff changeset
132 doing that takes some extra time.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 The default size is 65.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @item :rehash-size @var{rehash-size}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 When you add an association to a hash table and the table is ``full,''
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 it grows automatically. This value specifies how to make the hash table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 larger, at that time.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
141 If @var{rehash-size} is an integer, it should be positive, and the hash
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
142 table grows by adding that much to the nominal size. If
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
143 @var{rehash-size} is a floating point number, it had better be greater
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
144 than 1, and the hash table grows by multiplying the old size by that
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
145 number.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 The default value is 1.5.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @item :rehash-threshold @var{threshold}
60039
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
150 This specifies the criterion for when the hash table is ``full'' (so
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
151 it should be made larger). The value, @var{threshold}, should be a
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
152 positive floating point number, no greater than 1. The hash table is
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
153 ``full'' whenever the actual number of entries exceeds this fraction
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
154 of the nominal size. The default for @var{threshold} is 0.8.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @end table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @tindex makehash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @defun makehash &optional test
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 This is equivalent to @code{make-hash-table}, but with a different style
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 argument list. The argument @var{test} specifies the method
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 of key lookup.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
53025
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
164 This function is obsolete. Use @code{make-hash-table} instead.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 @node Hash Access
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 @section Hash Table Access
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 This section describes the functions for accessing and storing
60039
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
171 associations in a hash table. In general, any Lisp object can be used
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
172 as a hash key, unless the comparison method imposes limits. Any Lisp
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
173 object can also be used as the value.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @tindex gethash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @defun gethash key table &optional default
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 This function looks up @var{key} in @var{table}, and returns its
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 associated @var{value}---or @var{default}, if @var{key} has no
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 association in @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @tindex puthash
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 38786
diff changeset
183 @defun puthash key value table
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 This function enters an association for @var{key} in @var{table}, with
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 value @var{value}. If @var{key} already has an association in
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @var{table}, @var{value} replaces the old associated value.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @tindex remhash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @defun remhash key table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 This function removes the association for @var{key} from @var{table}, if
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 there is one. If @var{key} has no association, @code{remhash} does
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 nothing.
53025
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
194
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
195 @b{Common Lisp note:} In Common Lisp, @code{remhash} returns
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
196 non-@code{nil} if it actually removed an association and @code{nil}
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
197 otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @tindex clrhash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @defun clrhash table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 This function removes all the associations from hash table @var{table},
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 so that it becomes empty. This is also called @dfn{clearing} the hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 table.
53025
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
205
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
206 @b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
207 @var{table}. In Emacs Lisp, it returns @code{nil}.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 @tindex maphash
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54263
diff changeset
211 @defun maphash function table
53480
879f6aa2d2c7 (Hash Access): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53037
diff changeset
212 @anchor{Definition of maphash}
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 This function calls @var{function} once for each of the associations in
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @var{table}. The function @var{function} should accept two
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 arguments---a @var{key} listed in @var{table}, and its associated
60039
d1e57e5b8403 (Hash Tables): Add desc to menu items.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
216 @var{value}. @code{maphash} returns @code{nil}.
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @node Defining Hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @section Defining Hash Comparisons
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @cindex hash code
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 You can define new methods of key lookup by means of
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @code{define-hash-table-test}. In order to use this feature, you need
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 to understand how hash tables work, and what a @dfn{hash code} means.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 You can think of a hash table conceptually as a large array of many
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 slots, each capable of holding one association. To look up a key,
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @code{gethash} first computes an integer, the hash code, from the key.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 It reduces this integer modulo the length of the array, to produce an
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 index in the array. Then it looks in that slot, and if necessary in
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 other nearby slots, to see if it has found the key being sought.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 Thus, to define a new method of key lookup, you need to specify both a
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 function to compute the hash code from a key, and a function to compare
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 two keys directly.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @tindex define-hash-table-test
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @defun define-hash-table-test name test-fn hash-fn
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 This function defines a new hash table test, named @var{name}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 After defining @var{name} in this way, you can use it as the @var{test}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 argument in @code{make-hash-table}. When you do that, the hash table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 a ``hash code'' from a key value.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 The function @var{test-fn} should accept two arguments, two keys, and
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 return non-@code{nil} if they are considered ``the same.''
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 The function @var{hash-fn} should accept one argument, a key, and return
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 an integer that is the ``hash code'' of that key. For good results, the
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 function should use the whole range of integer values for hash codes,
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 including negative integers.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 The specified functions are stored in the property list of @var{name}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 under the property @code{hash-table-test}; the property value's form is
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @code{(@var{test-fn} @var{hash-fn})}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @tindex sxhash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @defun sxhash obj
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 This function returns a hash code for Lisp object @var{obj}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 This is an integer which reflects the contents of @var{obj}
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 and the other Lisp objects it points to.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 If the two objects are not equal, the values returned by @code{sxhash}
53025
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
270 are usually different, but not always; once in a rare while, by luck,
53be3d7fa5da (Creating Hash): Clarify description of `eql'. `makehash' is obsolete.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
271 you will encounter two distinct-looking objects that give the same
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 result from @code{sxhash}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
275 This example creates a hash table whose keys are strings that are
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
276 compared case-insensitively.
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
277
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
278 @example
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
279 (defun case-fold-string= (a b)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
280 (compare-strings a nil nil b nil nil t))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
281
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
282 (defun case-fold-string-hash (a)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
283 (sxhash (upcase a)))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
284
64842
0021965e29a2 (Defining Hash): Delete stray paren in example.
Richard M. Stallman <rms@gnu.org>
parents: 60446
diff changeset
285 (define-hash-table-test 'case-fold
0021965e29a2 (Defining Hash): Delete stray paren in example.
Richard M. Stallman <rms@gnu.org>
parents: 60446
diff changeset
286 'case-fold-string= 'case-fold-string-hash)
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
287
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
288 (make-hash-table :test 'case-fold)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
289 @end example
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
290
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
291 Here is how you could define a hash table test equivalent to the
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
292 predefined test value @code{equal}. The keys can be any Lisp object,
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
293 and equal-looking objects are considered the same key.
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
294
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
295 @example
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
296 (define-hash-table-test 'contents-hash 'equal 'sxhash)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
297
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
298 (make-hash-table :test 'contents-hash)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
299 @end example
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 30524
diff changeset
300
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 @node Other Hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @section Other Hash Table Functions
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 Here are some other functions for working with hash tables.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @tindex hash-table-p
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @defun hash-table-p table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 This returns non-@code{nil} if @var{table} is a hash table object.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @tindex copy-hash-table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @defun copy-hash-table table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 This function creates and returns a copy of @var{table}. Only the table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 itself is copied---the keys and values are shared.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @tindex hash-table-count
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @defun hash-table-count table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 This function returns the actual number of entries in @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321
26182
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
322 @tindex hash-table-test
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
323 @defun hash-table-test table
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
324 This returns the @var{test} value that was given when @var{table} was
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25634
diff changeset
325 created, to specify how to hash and compare keys. See
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @code{make-hash-table} (@pxref{Creating Hash}).
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @tindex hash-table-weakness
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @defun hash-table-weakness table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 This function returns the @var{weak} value that was specified for hash
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 table @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @tindex hash-table-rehash-size
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @defun hash-table-rehash-size table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 This returns the rehash size of @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @tindex hash-table-rehash-threshold
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @defun hash-table-rehash-threshold table
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 This returns the rehash threshold of @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @end defun
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344
26182
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
345 @tindex hash-table-size
3264a26ae355 Fix some typos.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
346 @defun hash-table-size table
25634
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 This returns the current nominal size of @var{table}.
0d3bc0a437c4 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @end defun
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51585
diff changeset
349
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51585
diff changeset
350 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51585
diff changeset
351 arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51585
diff changeset
352 @end ignore