[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master d2c3a983146 20/20: Hash-table documentation updates (bug#68244)
From: |
Mattias Engdegård |
Subject: |
master d2c3a983146 20/20: Hash-table documentation updates (bug#68244) |
Date: |
Sat, 13 Jan 2024 14:54:03 -0500 (EST) |
branch: master
commit d2c3a983146b7c0fb0f8b855268effb695d0bbf5
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>
Hash-table documentation updates (bug#68244)
* doc/lispref/hash.texi (Creating Hash, Other Hash):
Manual updates for make-hash-table, hash-table-rehash-size and
hash-table-rehash-threshold.
* doc/lispref/objects.texi (Hash Table Type): Update example.
* src/fns.c (Fhash_table_rehash_size, Fhash_table_rehash_threshold):
Update doc strings.
* etc/NEWS: Announce changes.
---
doc/lispref/hash.texi | 47 ++++++++---------------------------------------
doc/lispref/objects.texi | 3 +--
etc/NEWS | 15 +++++++++++++++
lisp/emacs-lisp/comp.el | 2 +-
src/fns.c | 16 ++++++++--------
5 files changed, 33 insertions(+), 50 deletions(-)
diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index aeaeab27fc0..3d3fe3e3be2 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -121,32 +121,10 @@ referenced in the hash table are preserved from garbage
collection.
@item :size @var{size}
This specifies a hint for how many associations you plan to store in the
hash table. If you know the approximate number, you can make things a
-little more efficient by specifying it this way. If you specify too
-small a size, the hash table will grow automatically when necessary, but
-doing that takes some extra time.
-
-The default size is 65.
-
-@item :rehash-size @var{rehash-size}
-When you add an association to a hash table and the table is full,
-it grows automatically. This value specifies how to make the hash table
-larger, at that time.
-
-If @var{rehash-size} is an integer, it should be positive, and the hash
-table grows by adding approximately that much to the nominal size. If
-@var{rehash-size} is floating point, it had better be greater
-than 1, and the hash table grows by multiplying the old size by
-approximately that number.
-
-The default value is 1.5.
-
-@item :rehash-threshold @var{threshold}
-This specifies the criterion for when the hash table is full (so
-it should be made larger). The value, @var{threshold}, should be a
-positive floating-point number, no greater than 1. The hash table is
-full whenever the actual number of entries exceeds the nominal size
-multiplied by an approximation to this value. The default for
-@var{threshold} is 0.8125.
+little more efficient by specifying it this way but since the hash
+table memory is managed automatically, the gain in speed is rarely
+significant.
+
@end table
@end defun
@@ -159,7 +137,7 @@ the following specifies a hash table containing the keys
(a symbol) and @code{300} (a number) respectively.
@example
-#s(hash-table size 30 data (key1 val1 key2 300))
+#s(hash-table data (key1 val1 key2 300))
@end example
Note, however, that when using this in Emacs Lisp code, it's
@@ -172,12 +150,11 @@ The printed representation for a hash table consists of
@samp{#s}
followed by a list beginning with @samp{hash-table}. The rest of the
list should consist of zero or more property-value pairs specifying
the hash table's properties and initial contents. The properties and
-values are read literally. Valid property names are @code{size},
-@code{test}, @code{weakness}, @code{rehash-size},
-@code{rehash-threshold}, and @code{data}. The @code{data} property
+values are read literally. Valid property names are @code{test},
+@code{weakness} and @code{data}. The @code{data} property
should be a list of key-value pairs for the initial contents; the
other properties have the same meanings as the matching
-@code{make-hash-table} keywords (@code{:size}, @code{:test}, etc.),
+@code{make-hash-table} keywords (@code{:test} and @code{:weakness}),
described above.
Note that you cannot specify a hash table whose initial contents
@@ -377,14 +354,6 @@ This function returns the @var{weak} value that was
specified for hash
table @var{table}.
@end defun
-@defun hash-table-rehash-size table
-This returns the rehash size of @var{table}.
-@end defun
-
-@defun hash-table-rehash-threshold table
-This returns the rehash threshold of @var{table}.
-@end defun
-
@defun hash-table-size table
This returns the current allocation size of @var{table}. Since hash table
allocation is managed automatically, this is rarely of interest.
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 111beb5e5b0..07ceb0d7a98 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1373,8 +1373,7 @@ and contents, like this:
@example
(make-hash-table)
- @result{} #s(hash-table size 65 test eql rehash-size 1.5
- rehash-threshold 0.8125 data ())
+ @result{} #s(hash-table)
@end example
@noindent
diff --git a/etc/NEWS b/etc/NEWS
index 5cf3e821627..da0253e97dc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1806,6 +1806,21 @@ The former macro returns non-nil if a variable has a
connection-local
binding. The latter macro returns the connection-local value of a
variable if any, or its current value.
+** Hash tables
+
++++
+*** ':rehash-size' and ':rehash-threshold' args no longer have any effect.
+These keyword arguments are now ignored by 'make-hash-table'. Emacs
+manages the memory for all hash table objects in the same way.
+The functions 'hash-table-rehash-size' and 'hash-table-rehash-threshold'
+remain for compatibility but now always return the old default values.
+
++++
+*** The printed representation has been shrunk and simplified.
+The 'test' parameter is omitted if it is 'eql' (the default), as is
+'data' if empty. 'rehash-size', 'rehash-threshold' and 'size' are
+always omitted, and ignored if present when the object is read back in.
+
* Changes in Emacs 30.1 on Non-Free Operating Systems
diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el
index 260bd2f1acb..8441b228898 100644
--- a/lisp/emacs-lisp/comp.el
+++ b/lisp/emacs-lisp/comp.el
@@ -1134,7 +1134,7 @@ Return value is the fall-through block name."
(defun comp-jump-table-optimizable (jmp-table)
"Return t if JMP-TABLE can be optimized out."
;; Identify LAP sequences like:
- ;; (byte-constant #s(hash-table size 3 test eq rehash-size 1.5
rehash-threshold 0.8125 purecopy t data (created 126 deleted 126 changed 126))
. 24)
+ ;; (byte-constant #s(hash-table test eq purecopy t data (created 126 deleted
126 changed 126)) . 24)
;; (byte-switch)
;; (TAG 126 . 10)
(let ((targets (hash-table-values jmp-table)))
diff --git a/src/fns.c b/src/fns.c
index 70288590e24..2905c3f1b86 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5495,25 +5495,25 @@ DEFUN ("hash-table-count", Fhash_table_count,
Shash_table_count, 1, 1, 0,
DEFUN ("hash-table-rehash-size", Fhash_table_rehash_size,
Shash_table_rehash_size, 1, 1, 0,
- doc: /* Return the current rehash size of TABLE. */)
+ doc: /* Return the rehash size of TABLE.
+This function is for compatibility only; it returns a nominal value
+without current significance. */)
(Lisp_Object table)
{
CHECK_HASH_TABLE (table);
- /* Nominal factor by which to increase the size of a hash table.
- No longer used; this is for compatibility. */
- return make_float (1.5);
+ return make_float (1.5); /* The old default rehash-size value. */
}
DEFUN ("hash-table-rehash-threshold", Fhash_table_rehash_threshold,
Shash_table_rehash_threshold, 1, 1, 0,
- doc: /* Return the current rehash threshold of TABLE. */)
+ doc: /* Return the rehash threshold of TABLE.
+This function is for compatibility only; it returns a nominal value
+without current significance. */)
(Lisp_Object table)
{
CHECK_HASH_TABLE (table);
- /* Nominal threshold for when to resize a hash table.
- No longer used; this is for compatibility. */
- return make_float (0.8125);
+ return make_float (0.8125); /* The old default rehash-threshold value. */
}
- master updated (76904626b36 -> d2c3a983146), Mattias Engdegård, 2024/01/13
- master 4ba6954e695 01/20: * src/print.c (print_object): Don't print hash table test if `eql`., Mattias Engdegård, 2024/01/13
- master 49fd4d120de 07/20: Allow zero hash table size, Mattias Engdegård, 2024/01/13
- master c3d0cc50faf 05/20: Remove rehash-threshold and rehash-size struct members, Mattias Engdegård, 2024/01/13
- master a3ae5653cfe 09/20: Store hash values as integers instead of Lisp_Object, Mattias Engdegård, 2024/01/13
- master ed06de52a53 14/20: Faster hash table growth, starting at zero size, Mattias Engdegård, 2024/01/13
- master fa5c07fc87d 08/20: Use non-Lisp allocation for internal hash-table vectors, Mattias Engdegård, 2024/01/13
- master 7ad5d427730 16/20: Don't dump Qunbound, Mattias Engdegård, 2024/01/13
- master d2c3a983146 20/20: Hash-table documentation updates (bug#68244),
Mattias Engdegård <=
- master a09619f2598 02/20: * src/print.c (print_object): Don't print empty hash-table data, Mattias Engdegård, 2024/01/13
- master 3f9c81a87f7 03/20: Don't print or read the hash table size parameter, Mattias Engdegård, 2024/01/13
- master d3cefd3e983 06/20: Leaner hash table dumping and thawing, Mattias Engdegård, 2024/01/13
- master 519c7ca7356 19/20: Don't pretend that hash-table-size is useful, Mattias Engdegård, 2024/01/13
- master 3b00255a4c7 10/20: Inlined and specialised hash table look-up, Mattias Engdegård, 2024/01/13
- master 1998039f7a8 18/20: Change hash_hash_t to uint32_t, Mattias Engdegård, 2024/01/13
- master 7d93a0147a1 12/20: Share hash table test structs, Mattias Engdegård, 2024/01/13
- master 47502c55b0c 13/20: ; Reorder struct Lisp_Hash_Table and struct hash_table_test, Mattias Engdegård, 2024/01/13
- master c6bdc1ea1dc 04/20: Represent hash table weakness as an enum internally, Mattias Engdegård, 2024/01/13
- master 68f8bc31114 15/20: Change hash_idx_t to int32_t on all platforms, Mattias Engdegård, 2024/01/13