google_hash 0.8.1 → 0.8.2

data/ext/{sparsehash-1.8.1 → sparsehash-2.0.2}/configure.ac

@@ -4,7 +4,7 @@
 # make sure we're interpreted by some minimal autoconf
 AC_PREREQ(2.57)
 
-AC_INIT(sparsehash, 1.8.1, opensource@google.com)
+AC_INIT(sparsehash, 2.0.2, google-sparsehash@googlegroups.com)
 # The argument here is just something that should be in the current directory
 # (for sanity checking)
 AC_CONFIG_SRCDIR(README)
@@ -12,9 +12,9 @@ AM_INIT_AUTOMAKE([dist-zip])
 AM_CONFIG_HEADER(src/config.h)
 
 # Checks for programs.
+AC_PROG_CXX
 AC_PROG_CC
 AC_PROG_CPP
-AC_PROG_CXX
 AM_CONDITIONAL(GCC, test "$GCC" = yes)   # let the Makefile know if we're gcc
 
 # Check whether some low-level functions/files are available
@@ -51,9 +51,8 @@ AC_SUBST(tcmalloc_libs)
 AC_CXX_STL_HASH
 AC_CXX_STL_HASH_FUN
 
-# Find out what namespace 'normal' STL code lives in, and also what namespace
-# the user wants our classes to be defined in
-AC_CXX_STL_NAMESPACE
+# Find out what namespace the user wants our classes to be defined in.
+# TODO(csilvers): change this to default to sparsehash instead.
 AC_DEFINE_GOOGLE_NAMESPACE(google)
 
 # In unix-based systems, hash is always defined as hash<> (in namespace.

data/ext/{sparsehash-1.8.1 → sparsehash-2.0.2}/depcomp

@@ -1,9 +1,10 @@
 #! /bin/sh
 # depcomp - compile a program generating dependencies as side-effects
 
-scriptversion=2005-07-09.11
+scriptversion=2009-04-28.21; # UTC
 
-# Copyright (C) 1999, 2000, 2003, 2004, 2005 Free Software Foundation, Inc.
+# Copyright (C) 1999, 2000, 2003, 2004, 2005, 2006, 2007, 2009 Free
+# Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -16,9 +17,7 @@ scriptversion=2005-07-09.11
 # GNU General Public License for more details.
 
 # You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-# 02110-1301, USA.
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 # As a special exception to the GNU General Public License, if you
 # distribute this file as part of a program that contains a
@@ -86,12 +85,34 @@ if test "$depmode" = dashXmstdout; then
    depmode=dashmstdout
 fi
 
+cygpath_u="cygpath -u -f -"
+if test "$depmode" = msvcmsys; then
+   # This is just like msvisualcpp but w/o cygpath translation.
+   # Just convert the backslash-escaped backslashes to single forward
+   # slashes to satisfy depend.m4
+   cygpath_u="sed s,\\\\\\\\,/,g"
+   depmode=msvisualcpp
+fi
+
 case "$depmode" in
 gcc3)
 ## gcc 3 implements dependency tracking that does exactly what
 ## we want.  Yay!  Note: for some reason libtool 1.4 doesn't like
 ## it if -MD -MP comes after the -MF stuff.  Hmm.
-  "$@" -MT "$object" -MD -MP -MF "$tmpdepfile"
+## Unfortunately, FreeBSD c89 acceptance of flags depends upon
+## the command line argument order; so add the flags where they
+## appear in depend2.am.  Note that the slowdown incurred here
+## affects only configure: in makefiles, %FASTDEP% shortcuts this.
+  for arg
+  do
+    case $arg in
+    -c) set fnord "$@" -MT "$object" -MD -MP -MF "$tmpdepfile" "$arg" ;;
+    *)  set fnord "$@" "$arg" ;;
+    esac
+    shift # fnord
+    shift # $arg
+  done
+  "$@"
   stat=$?
   if test $stat -eq 0; then :
   else
@@ -178,14 +199,14 @@ sgi)
 ' < "$tmpdepfile" \
     | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' | \
     tr '
-' ' ' >> $depfile
-    echo >> $depfile
+' ' ' >> "$depfile"
+    echo >> "$depfile"
 
     # The second pass generates a dummy entry for each header file.
     tr ' ' '
 ' < "$tmpdepfile" \
    | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' -e 's/$/:/' \
-   >> $depfile
+   >> "$depfile"
   else
     # The sourcefile does not contain any dependencies, so just
     # store a dummy comment line, to avoid errors with the Makefile
@@ -201,34 +222,39 @@ aix)
   # current directory.  Also, the AIX compiler puts `$object:' at the
   # start of each line; $object doesn't have directory information.
   # Version 6 uses the directory in both cases.
-  stripped=`echo "$object" | sed 's/\(.*\)\..*$/\1/'`
-  tmpdepfile="$stripped.u"
+  dir=`echo "$object" | sed -e 's|/[^/]*$|/|'`
+  test "x$dir" = "x$object" && dir=
+  base=`echo "$object" | sed -e 's|^.*/||' -e 's/\.o$//' -e 's/\.lo$//'`
   if test "$libtool" = yes; then
+    tmpdepfile1=$dir$base.u
+    tmpdepfile2=$base.u
+    tmpdepfile3=$dir.libs/$base.u
     "$@" -Wc,-M
   else
+    tmpdepfile1=$dir$base.u
+    tmpdepfile2=$dir$base.u
+    tmpdepfile3=$dir$base.u
     "$@" -M
   fi
   stat=$?
 
-  if test -f "$tmpdepfile"; then :
-  else
-    stripped=`echo "$stripped" | sed 's,^.*/,,'`
-    tmpdepfile="$stripped.u"
-  fi
-
   if test $stat -eq 0; then :
   else
-    rm -f "$tmpdepfile"
+    rm -f "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3"
     exit $stat
   fi
 
+  for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3"
+  do
+    test -f "$tmpdepfile" && break
+  done
   if test -f "$tmpdepfile"; then
-    outname="$stripped.o"
     # Each line is of the form `foo.o: dependent.h'.
     # Do two passes, one to just change these to
     # `$object: dependent.h' and one to simply `dependent.h:'.
-    sed -e "s,^$outname:,$object :," < "$tmpdepfile" > "$depfile"
-    sed -e "s,^$outname: \(.*\)$,\1:," < "$tmpdepfile" >> "$depfile"
+    sed -e "s,^.*\.[a-z]*:,$object:," < "$tmpdepfile" > "$depfile"
+    # That's a tab and a space in the [].
+    sed -e 's,^.*\.[a-z]*:[	 ]*,,' -e 's,$,:,' < "$tmpdepfile" >> "$depfile"
   else
     # The sourcefile does not contain any dependencies, so just
     # store a dummy comment line, to avoid errors with the Makefile
@@ -276,6 +302,51 @@ icc)
   rm -f "$tmpdepfile"
   ;;
 
+hp2)
+  # The "hp" stanza above does not work with aCC (C++) and HP's ia64
+  # compilers, which have integrated preprocessors.  The correct option
+  # to use with these is +Maked; it writes dependencies to a file named
+  # 'foo.d', which lands next to the object file, wherever that
+  # happens to be.
+  # Much of this is similar to the tru64 case; see comments there.
+  dir=`echo "$object" | sed -e 's|/[^/]*$|/|'`
+  test "x$dir" = "x$object" && dir=
+  base=`echo "$object" | sed -e 's|^.*/||' -e 's/\.o$//' -e 's/\.lo$//'`
+  if test "$libtool" = yes; then
+    tmpdepfile1=$dir$base.d
+    tmpdepfile2=$dir.libs/$base.d
+    "$@" -Wc,+Maked
+  else
+    tmpdepfile1=$dir$base.d
+    tmpdepfile2=$dir$base.d
+    "$@" +Maked
+  fi
+  stat=$?
+  if test $stat -eq 0; then :
+  else
+     rm -f "$tmpdepfile1" "$tmpdepfile2"
+     exit $stat
+  fi
+
+  for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2"
+  do
+    test -f "$tmpdepfile" && break
+  done
+  if test -f "$tmpdepfile"; then
+    sed -e "s,^.*\.[a-z]*:,$object:," "$tmpdepfile" > "$depfile"
+    # Add `dependent.h:' lines.
+    sed -ne '2,${
+	       s/^ *//
+	       s/ \\*$//
+	       s/$/:/
+	       p
+	     }' "$tmpdepfile" >> "$depfile"
+  else
+    echo "#dummy" > "$depfile"
+  fi
+  rm -f "$tmpdepfile" "$tmpdepfile2"
+  ;;
+
 tru64)
    # The Tru64 compiler uses -MD to generate dependencies as a side
    # effect.  `cc -MD -o foo.o ...' puts the dependencies into `foo.o.d'.
@@ -288,13 +359,13 @@ tru64)
 
    if test "$libtool" = yes; then
       # With Tru64 cc, shared objects can also be used to make a
-      # static library.  This mecanism is used in libtool 1.4 series to
+      # static library.  This mechanism is used in libtool 1.4 series to
       # handle both shared and static libraries in a single compilation.
       # With libtool 1.4, dependencies were output in $dir.libs/$base.lo.d.
       #
       # With libtool 1.5 this exception was removed, and libtool now
       # generates 2 separate objects for the 2 libraries.  These two
-      # compilations output dependencies in in $dir.libs/$base.o.d and
+      # compilations output dependencies in $dir.libs/$base.o.d and
       # in $dir$base.o.d.  We have to check for both files, because
       # one of the two compilations can be disabled.  We should prefer
       # $dir$base.o.d over $dir.libs/$base.o.d because the latter is
@@ -345,7 +416,7 @@ dashmstdout)
 
   # Remove the call to Libtool.
   if test "$libtool" = yes; then
-    while test $1 != '--mode=compile'; do
+    while test "X$1" != 'X--mode=compile'; do
       shift
     done
     shift
@@ -396,32 +467,39 @@ makedepend)
   "$@" || exit $?
   # Remove any Libtool call
   if test "$libtool" = yes; then
-    while test $1 != '--mode=compile'; do
+    while test "X$1" != 'X--mode=compile'; do
       shift
     done
     shift
   fi
   # X makedepend
   shift
-  cleared=no
-  for arg in "$@"; do
+  cleared=no eat=no
+  for arg
+  do
     case $cleared in
     no)
       set ""; shift
       cleared=yes ;;
     esac
+    if test $eat = yes; then
+      eat=no
+      continue
+    fi
     case "$arg" in
     -D*|-I*)
       set fnord "$@" "$arg"; shift ;;
     # Strip any option that makedepend may not understand.  Remove
     # the object too, otherwise makedepend will parse it as a source file.
+    -arch)
+      eat=yes ;;
     -*|$object)
       ;;
     *)
       set fnord "$@" "$arg"; shift ;;
     esac
   done
-  obj_suffix="`echo $object | sed 's/^.*\././'`"
+  obj_suffix=`echo "$object" | sed 's/^.*\././'`
   touch "$tmpdepfile"
   ${MAKEDEPEND-makedepend} -o"$obj_suffix" -f"$tmpdepfile" "$@"
   rm -f "$depfile"
@@ -441,7 +519,7 @@ cpp)
 
   # Remove the call to Libtool.
   if test "$libtool" = yes; then
-    while test $1 != '--mode=compile'; do
+    while test "X$1" != 'X--mode=compile'; do
       shift
     done
     shift
@@ -479,13 +557,27 @@ cpp)
 
 msvisualcpp)
   # Important note: in order to support this mode, a compiler *must*
-  # always write the preprocessed file to stdout, regardless of -o,
-  # because we must use -o when running libtool.
+  # always write the preprocessed file to stdout.
   "$@" || exit $?
+
+  # Remove the call to Libtool.
+  if test "$libtool" = yes; then
+    while test "X$1" != 'X--mode=compile'; do
+      shift
+    done
+    shift
+  fi
+
   IFS=" "
   for arg
   do
     case "$arg" in
+    -o)
+      shift
+      ;;
+    $object)
+      shift
+      ;;
     "-Gm"|"/Gm"|"-Gi"|"/Gi"|"-ZI"|"/ZI")
 	set fnord "$@"
 	shift
@@ -498,16 +590,23 @@ msvisualcpp)
 	;;
     esac
   done
-  "$@" -E |
-  sed -n '/^#line [0-9][0-9]* "\([^"]*\)"/ s::echo "`cygpath -u \\"\1\\"`":p' | sort | uniq > "$tmpdepfile"
+  "$@" -E 2>/dev/null |
+  sed -n '/^#line [0-9][0-9]* "\([^"]*\)"/ s::\1:p' | $cygpath_u | sort -u > "$tmpdepfile"
   rm -f "$depfile"
   echo "$object : \\" > "$depfile"
-  . "$tmpdepfile" | sed 's% %\\ %g' | sed -n '/^\(.*\)$/ s::	\1 \\:p' >> "$depfile"
+  sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s::	\1 \\:p' >> "$depfile"
   echo "	" >> "$depfile"
-  . "$tmpdepfile" | sed 's% %\\ %g' | sed -n '/^\(.*\)$/ s::\1\::p' >> "$depfile"
+  sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s::\1\::p' >> "$depfile"
   rm -f "$tmpdepfile"
   ;;
 
+msvcmsys)
+  # This case exists only to let depend.m4 do its work.  It works by
+  # looking at the text of this script.  This case will never be run,
+  # since it is checked for above.
+  exit 1
+  ;;
+
 none)
   exec "$@"
   ;;
@@ -526,5 +625,6 @@ exit 0
 # eval: (add-hook 'write-file-hooks 'time-stamp)
 # time-stamp-start: "scriptversion="
 # time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-end: "$"
+# time-stamp-time-zone: "UTC"
+# time-stamp-end: "; # UTC"
 # End:

data/ext/{sparsehash-1.8.1 → sparsehash-2.0.2}/doc/dense_hash_map.html

@@ -88,7 +88,7 @@ details.)
 
 <pre>
 #include &lt;iostream&gt;
-#include &lt;google/dense_hash_map&gt;
+#include &lt;sparsehash/dense_hash_map&gt;
 
 using google::dense_hash_map;      // namespace where class lives by default
 using std::cout;
@@ -1240,7 +1240,8 @@ key_type&amp; k) </pre>
 
 <TR>
 <TD VAlign=top>
-   <tt>bool write_metadata(FILE *fp)</tt>
+   <tt>template &lt;ValueSerializer, OUTPUT&gt;
+       bool serialize(ValueSerializer serializer, OUTPUT *fp)</tt>
 </TD>
 <TD VAlign=top>
    <tt>dense_hash_map</tt>
@@ -1252,7 +1253,8 @@ key_type&amp; k) </pre>
 
 <TR>
 <TD VAlign=top>
-   <tt>bool read_metadata(FILE *fp)</tt>
+   <tt>template &lt;ValueSerializer, INPUT&gt;
+       bool unserialize(ValueSerializer serializer, INPUT *fp)</tt>
 </TD>
 <TD VAlign=top>
    <tt>dense_hash_map</tt>
@@ -1264,7 +1266,7 @@ key_type&amp; k) </pre>
 
 <TR>
 <TD VAlign=top>
-   <tt>bool write_nopointer_data(FILE *fp)</tt>
+   <tt>NopointerSerializer</tt>
 </TD>
 <TD VAlign=top>
    <tt>dense_hash_map</tt>
@@ -1274,6 +1276,42 @@ key_type&amp; k) </pre>
 </TD>
 </TR>
 
+<TR>
+<TD VAlign=top>
+   <tt>bool write_metadata(FILE *fp)</tt>
+</TD>
+<TD VAlign=top>
+   <tt>dense_hash_map</tt>
+</TD>
+<TD VAlign=top>
+   DEPRECATED.  <A HREF="#new">See below</A>.
+</TD>
+</TR>
+
+<TR>
+<TD VAlign=top>
+   <tt>bool read_metadata(FILE *fp)</tt>
+</TD>
+<TD VAlign=top>
+   <tt>dense_hash_map</tt>
+</TD>
+<TD VAlign=top>
+   DEPRECATED.  <A HREF="#new">See below</A>.
+</TD>
+</TR>
+
+<TR>
+<TD VAlign=top>
+   <tt>bool write_nopointer_data(FILE *fp)</tt>
+</TD>
+<TD VAlign=top>
+   <tt>dense_hash_map</tt>
+</TD>
+<TD VAlign=top>
+   DEPRECATED.  <A HREF="#new">See below</A>.
+</TD>
+</TR>
+
 <TR>
 <TD VAlign=top>
    <tt>bool read_nopointer_data(FILE *fp)</tt>
@@ -1282,7 +1320,7 @@ key_type&amp; k) </pre>
    <tt>dense_hash_map</tt>
 </TD>
 <TD VAlign=top>
-   <A HREF="#new">See below</A>.
+   DEPRECATED.  <A HREF="#new">See below</A>.
 </TD>
 </TR>
 
@@ -1390,12 +1428,35 @@ href="http://www.sgi.com/tech/stl/#3">[3]</A>
 </TD>
 </TR>
 
+<TR>
+<TD VAlign=top>
+   <tt>template &lt;ValueSerializer, OUTPUT&gt;
+       bool serialize(ValueSerializer serializer, OUTPUT *fp)</tt>
+</TD>
+<TD VAlign=top>
+   Emit a serialization of the hash_map to a stream.
+   See <A HREF="#io">below</A>.
+</TD>
+</TR>
+
+<TR>
+<TD VAlign=top>
+   <tt>template &lt;ValueSerializer, INPUT&gt;
+       bool unserialize(ValueSerializer serializer, INPUT *fp)</tt>
+</TD>
+<TD VAlign=top>
+   Read in a serialization of a hash_map from a stream, replacing the
+   existing hash_map contents with the serialized contents.
+   See <A HREF="#io">below</A>.
+</TD>
+</TR>
+
 <TR>
 <TD VAlign=top>
    <tt>bool write_metadata(FILE *fp)</tt>
 </TD>
 <TD VAlign=top>
-   Write hashtable metadata to <tt>fp</tt>.  See <A HREF="#io">below</A>.
+   This function is DEPRECATED.  See <A HREF="#io">below</A>.
 </TD>
 </TR>
 
@@ -1404,7 +1465,7 @@ href="http://www.sgi.com/tech/stl/#3">[3]</A>
    <tt>bool read_metadata(FILE *fp)</tt>
 </TD>
 <TD VAlign=top>
-   Read hashtable metadata from <tt>fp</tt>.  See <A HREF="#io">below</A>.
+   This function is DEPRECATED.  See <A HREF="#io">below</A>.
 </TD>
 </TR>
 
@@ -1413,8 +1474,7 @@ href="http://www.sgi.com/tech/stl/#3">[3]</A>
    <tt>bool write_nopointer_data(FILE *fp)</tt>
 </TD>
 <TD VAlign=top>
-   Write hashtable contents to <tt>fp</tt>.  This is valid only if the
-   hashtable key and value are "plain" data.  See <A HREF="#io">below</A>.
+   This function is DEPRECATED.  See <A HREF="#io">below</A>.
 </TD>
 </TR>
 
@@ -1423,8 +1483,7 @@ href="http://www.sgi.com/tech/stl/#3">[3]</A>
    <tt>bool read_nopointer_data(FILE *fp)</tt>
 </TD>
 <TD VAlign=top>
-   Read hashtable contents to <tt>fp</tt>.  This is valid only if the
-   hashtable key and value are "plain" data.  See <A HREF="#io">below</A>.
+   This function is DEPRECATED.  See <A HREF="#io">below</A>.
 </TD>
 </TR>
 
@@ -1542,69 +1601,125 @@ constructor, there are several workarounds:</p>
 </ul>
 
 
-<h3><A NAME=io>Input/Output</A></h3>
-
-<table border=1 cellpadding=5><tr><td>
-<p><b>IMPORTANT IMPLEMENTATION NOTE:</b> In the current version of
-this code, the input/output routines for <tt>dense_hash_map</tt> have
-<b>not yet been implemented</b>.  This section explains the API, but
-note that all calls to these routines will fail (return
-<tt>false</tt>).  It is a TODO to remedy this situation.</p>
-</td></tr></table>
+<h3><A NAME="io">Input/Output</A></h3>
 
 <p>It is possible to save and restore <tt>dense_hash_map</tt> objects
-to disk.  Storage takes place in two steps.  The first writes the
-hashtable metadata.  The second writes the actual data.</p>
-
-<p>To write a hashtable to disk, first call <tt>write_metadata()</tt>
-on an open file pointer.  This saves the hashtable information in a
-byte-order-independent format.</p>
-
-<p>After the metadata has been written to disk, you must write the
-actual data stored in the hash-map to disk.  If both the key and data
-are "simple" enough, you can do this by calling
-<tt>write_nopointer_data()</tt>.  "Simple" data is data that can be
-safely copied to disk via <tt>fwrite()</tt>.  Native C data types fall
-into this category, as do structs of native C data types.  Pointers
-and STL objects do not.</p>
-
-<p>Note that <tt>write_nopointer_data()</tt> does not do any endian
+to an arbitrary stream (such as a disk file) using the
+<tt>serialize()</tt> and <tt>unserialize()</tt> methods.</p>
+
+<p>Each of these methods takes two arguments: a <i>serializer</i>,
+which says how to write hashtable items to disk, and a <i>stream</i>,
+which can be a C++ stream (<tt>istream</tt> or its subclasses for
+input, <tt>ostream</tt> or its subclasses for output), a
+<tt>FILE*</tt>, or a user-defined type (as described below).</p>
+
+<p>The <it>serializer</i> is a functor that takes a stream and a
+single hashtable element (a <tt>value_type</tt>, which is a pair of
+the key and data) and copies the hashtable element to the stream (for
+<tt>serialize()</tt>) or fills the hashtable element contents from the
+stream (for <tt>unserialize()</tt>), and returns true on success or
+false on error.  The copy-in and copy-out functions can be provided in
+a single functor.  Here is a sample serializer that read/writes a hashtable
+element for an int-to-string hash_map to a <tt>FILE*</tt>:</p>
+
+<pre>
+struct StringToIntSerializer {
+  bool operator()(FILE* fp, const std::pair&lt;const int, std::string&gt;&amp; value) const {
+    // Write the key.  We ignore endianness for this example.
+    if (fwrite(&amp;value.first, sizeof(value.first), 1, fp) != 1)
+      return false;
+    // Write the value.
+    assert(value.second.length() &lt;= 255);   // we only support writing small strings
+    const unsigned char size = value.second.length();
+    if (fwrite(&amp;size, 1, 1, fp) != 1)
+      return false;
+    if (fwrite(value.second.data(), size, 1, fp) != 1)
+      return false;
+    return true;
+  }
+  bool operator()(FILE* fp, std::pair&lt;const int, std::string&gt;* value) const {
+    // Read the key.  Note the need for const_cast to get around
+    // the fact hash_map keys are always const.
+    if (fread(const_cast&lt;int*&gt;(&amp;value-&gt;first), sizeof(value-&gt;first), 1, fp) != 1)
+      return false;
+    // Read the value.
+    unsigned char size;    // all strings are &lt;= 255 chars long
+    if (fread(&amp;size, 1, 1, fp) != 1)
+      return false;
+    char* buf = new char[size];
+    if (fread(buf, size, 1, fp) != 1) {
+      delete[] buf;
+      return false;
+    }
+    value-&gt;second.assign(buf, size);
+    delete[] buf;
+    return true;
+  }
+};
+</pre>
+
+<p>Here is the functor being used in code (error checking omitted):</p>
+<pre>
+   dense_hash_map&lt;string, int&gt; mymap = CreateMap();
+   FILE* fp = fopen("hashtable.data", "w");
+   mymap.serialize(StringToIntSerializer(), fp);
+   fclose(fp);
+
+   dense_hash_map&lt;string, int&gt; mymap2;
+   FILE* fp_in = fopen("hashtable.data", "r");
+   mymap2.unserialize(StringToIntSerializer(), fp_in);
+   fclose(fp_in);
+   assert(mymap == mymap2);
+</pre>
+
+<p>Note that this example serializer can only serialize to a FILE*.
+If you want to also be able to use this serializer with C++ streams,
+you will need to write two more overloads of <tt>operator()</tt>'s,
+one that reads from an <tt>istream</tt>, and one that writes to an
+<tt>ostream</tt>.  Likewise if you want to support serializing to a
+custom class.</p>
+
+<p>If both the key and data are "simple" enough, you can use the
+pre-supplied functor <tt>NopointerSerializer</tt>.  This copies the
+hashtable data using the equivalent of a <tt>memcpy<></tt>.  Native C
+data types can be serialized this way, as can structs of native C data
+types.  Pointers and STL objects cannot.</p>
+
+<p>Note that <tt>NopointerSerializer()</tt> does not do any endian
 conversion.  Thus, it is only appropriate when you intend to read the
 data on the same endian architecture as you write the data.</p>
 
-<p>If you cannot use <tt>write_nopointer_data()</tt> for any reason,
-you can write the data yourself by iterating over the
-<tt>dense_hash_map</tt> with a <tt>const_iterator</tt> and writing
-the key and data in any manner you wish.</p>
-
-<p>To read the hashtable information from disk, first you must create
-a <tt>dense_hash_map</tt> object.  Then open a file pointer to point
-to the saved hashtable, and call <tt>read_metadata()</tt>.  If you
-saved the data via <tt>write_nopointer_data()</tt>, you can follow the
-<tt>read_metadata()</tt> call with a call to
-<tt>read_nopointer_data()</tt>.  This is all that is needed.</p>
-
-<p>If you saved the data through a custom write routine, you must call
-a custom read routine to read in the data.  To do this, iterate over
-the <tt>dense_hash_map</tt> with an <tt>iterator</tt>; this operation
-is sensical because the metadata has already been set up.  For each
-iterator item, you can read the key and value from disk, and set it
-appropriately.  You will need to do a <tt>const_cast</tt> on the
-iterator, since <tt>it-&gt;first</tt> is always <tt>const</tt>.  You
-will also need to use placement-new if the key or value is a C++
-object.  The code might look like this:</p>
+<p>If you wish to serialize to your own stream type, you can do so by
+creating an object which supports two methods:</p>
 <pre>
-   for (dense_hash_map&lt;int*, ComplicatedClass&gt;::iterator it = ht.begin();
-        it != ht.end(); ++it) {
-       // The key is stored in the dense_hash_map as a pointer
-       const_cast&lt;int*&gt;(it-&gt;first) = new int;
-       fread(const_cast&lt;int*&gt;(it-&gt;first), sizeof(int), 1, fp);
-       // The value is a complicated C++ class that takes an int to construct
-       int ctor_arg;
-       fread(&ctor_arg, sizeof(int), 1, fp);
-       new (&it-&gt;second) ComplicatedClass(ctor_arg);  // "placement new"
-   }
+   bool Write(const void* data, size_t length);
+   bool Read(void* data, size_t length);
 </pre>
+<p><tt>Write()</tt> writes <tt>length</tt> bytes of <tt>data</tt> to a
+stream (presumably a stream owned by the object), while
+<tt>Read()</tt> reads <tt>data</tt> bytes from the stream into
+<tt>data</tt>.  Both return true on success or false on error.</p>
+
+<p>To unserialize a hashtable from a stream, you wil typically create
+a new <tt>dense_hash_map</tt> object, then call <tt>unserialize()</tt>
+on it.  <tt>unserialize()</tt> destroys the old contents of the
+object.  You must pass in the appropriate <tt>ValueSerializer</tt> for
+the data being read in.</p>
+
+<p>Both <tt>serialize()</tt> and <tt>unserialize()</tt> return
+<tt>true</tt> on success, or <tt>false</tt> if there was an error
+streaming the data.</p>
+
+<p>Note that <tt>serialize()</tt> is not a const method, since it
+purges deleted elements before serializing.  It is not safe to
+serialize from two threads at once, without synchronization.</p>
+
+<p>NOTE: older versions of <tt>dense_hash_map</tt> provided a
+different API, consisting of <tt>read_metadata()</tt>,
+<tt>read_nopointer_data()</tt>, <tt>write_metadata()</tt>,
+<tt>write_nopointer_data()</tt>.  These methods were never implemented
+and always did nothing but return <tt>false</tt>.  You should
+exclusively use the new API for serialization.</p>
 
 
 <h3><A NAME=iter>Validity of Iterators</A></h3>