Update copyright notices for 2013.

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

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 96b6631..753e718 100644 (file)
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -1,10 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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, 2008  Free Software Foundation, Inc.
+@c Copyright (C) 1999, 2001-2013 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @c See the file elisp.texi for copying conditions.

-@setfilename ../../info/hash
-@node Hash Tables, Symbols, Sequences Arrays Vectors, Top
+@node Hash Tables

 @chapter Hash Tables
 @cindex hash tables
 @cindex lookup tables
 @chapter Hash Tables
 @cindex hash tables
 @cindex lookup tables


@@ -30,18 +28,13 @@ the way two alists can share a common tail.
 @end itemize
 
   Emacs Lisp provides a general-purpose hash table data type, along
 @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
 
   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 +43,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.
 @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
 
 * Other Hash::          Miscellaneous.
 @end menu
 


@@ -81,13 +74,13 @@ alternatives:
 Keys which are numbers are ``the same'' if they are @code{equal}, that
 is, if they are equal in value and either both are integers or both
 are floating point numbers; otherwise, two distinct objects are never
 Keys which are numbers are ``the same'' if they are @code{equal}, that
 is, if they are equal in value and either both are integers or both
 are floating point numbers; otherwise, two distinct objects are never

-``the same.''
+``the same''.

 
 @item eq
 Any two distinct Lisp objects are ``different'' as keys.
 
 @item equal
 
 @item eq
 Any two distinct Lisp objects are ``different'' as keys.
 
 @item equal

-Two Lisp objects are ``the same,'' as keys, if they are equal
+Two Lisp objects are ``the same'', as keys, if they are equal

 according to @code{equal}.
 @end table
 
 according to @code{equal}.
 @end table
 


@@ -135,7 +128,7 @@ doing that takes some extra time.
 The default size is 65.
 
 @item :rehash-size @var{rehash-size}
 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,''
+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.
 
 it grows automatically.  This value specifies how to make the hash table
 larger, at that time.
 


@@ -164,6 +157,35 @@ of key lookup.
 This function is obsolete. Use @code{make-hash-table} instead.
 @end defun
 
 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
 
 @node Hash Access
 @section Hash Table Access
 


@@ -240,7 +262,7 @@ will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
 a ``hash code'' from a key value.
 
 The function @var{test-fn} should accept two arguments, two keys, and
 a ``hash code'' from a key value.
 
 The function @var{test-fn} should accept two arguments, two keys, and

-return non-@code{nil} if they are considered ``the same.''
+return non-@code{nil} if they are considered ``the same''.

 
 The function @var{hash-fn} should accept one argument, a key, and return
 an integer that is the ``hash code'' of that key.  For good results, the
 
 The function @var{hash-fn} should accept one argument, a key, and return
 an integer that is the ``hash code'' of that key.  For good results, the


@@ -331,7 +353,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
 @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