Merge changes from emacs-23 branch

[bpt/emacs.git] / doc / lispref / hash.texi

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 3f0297e..0d77cba 100644 (file)
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -1,7 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005,
-@c   2006, 2007  Free Software Foundation, Inc.
+@c Copyright (C) 1999, 2001-2011  Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/hash
 @node Hash Tables, Symbols, Sequences Arrays Vectors, Top
@@ -30,18 +29,13 @@ the way two alists can share a common tail.
 @end itemize
 
   Emacs Lisp provides a general-purpose hash table data type, along
-with a series of functions for operating on them.  Hash tables have no
-read syntax, and print in hash notation, like this:
-
-@example
-(make-hash-table)
-     @result{} #<hash-table 'eql nil 0/65 0x83af980>
-@end example
-
-@noindent
-(The term ``hash notation'' refers to the initial @samp{#}
-character---@pxref{Printed Representation}---and has nothing to do with
-the term ``hash table.'')
+with a series of functions for operating on them.  Hash tables have a
+special printed representation, which consists of @samp{#s} followed
+by a list specifying the hash table properties and contents.
+@xref{Creating Hash}.  (Note that the term ``hash notation'', which
+refers to the initial @samp{#} character used in the printed
+representations of objects with no read representation, has nothing to
+do with the term ``hash table''.  @xref{Printed Representation}.)
 
   Obarrays are also a kind of hash table, but they are a different type
 of object and are used only for recording interned symbols
@@ -50,7 +44,7 @@ of object and are used only for recording interned symbols
 @menu
 * Creating Hash::       Functions to create hash tables.
 * Hash Access::         Reading and writing the hash table contents.
-* Defining Hash::       Defining new comparison methods
+* Defining Hash::       Defining new comparison methods.
 * Other Hash::          Miscellaneous.
 @end menu
 
@@ -164,6 +158,35 @@ of key lookup.
 This function is obsolete. Use @code{make-hash-table} instead.
 @end defun
 
+You can also create a new hash table using the printed representation
+for hash tables.  The Lisp reader can read this printed
+representation, provided each element in the specified hash table has
+a valid read syntax (@pxref{Printed Representation}).  For instance,
+the following specifies a new hash table containing the keys
+@code{key1} and @code{key2} (both symbols) associated with @code{val1}
+(a symbol) and @code{300} (a number) respectively.
+
+@example
+#s(hash-table size 30 data (key1 val1 key2 300))
+@end example
+
+@noindent
+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
+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.),
+described above.
+
+Note that you cannot specify a hash table whose initial contents
+include objects that have no read syntax, such as buffers and frames.
+Such objects may be added to the hash table after it is created.
+
 @node Hash Access
 @section Hash Table Access
 
@@ -331,7 +354,3 @@ This returns the rehash threshold of @var{table}.
 @defun hash-table-size table
 This returns the current nominal size of @var{table}.
 @end defun
-
-@ignore
-   arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
-@end ignore