X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cc81d32f2bf8c159f3b1bf6ddaf62e6d77720209..9c57566224918b8a121d1011aa7baa5b28b334a6:/docs/latex/wx/hashmap.tex

diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex
index 1a48cf60b3..ebb9c60e6a 100644
--- a/docs/latex/wx/hashmap.tex
+++ b/docs/latex/wx/hashmap.tex
@@ -1,7 +1,9 @@
 \section{\class{wxHashMap}}\label{wxhashmap}
 
 This is a simple, type-safe, and reasonably efficient hash map class,
-whose interface is a subset of the interface of STL containers. 
+whose interface is a subset of the interface of STL containers. In
+particular, the interface is modeled after std::map, and the various,
+non-standard, std::hash\_map.
 
 \wxheading{Example}
 
@@ -27,7 +29,7 @@ whose interface is a subset of the interface of STL containers.
     h2["Bill"] = "ABC";
     wxString tmp = h2["Bill"];
     // since element with key "Joe" is not present, this will return
-    // the default value, that is an empty string in the case of wxString
+    // the default value, which is an empty string in the case of wxString
     MyClass tmp2 = h2["Joe"];
 
     // iterate over all the elements in the class
@@ -46,7 +48,7 @@ whose interface is a subset of the interface of STL containers.
                                 CLASSNAME ); // name of the class
 \end{verbatim}
 
-Declares an hash map class named CLASSNAME, with {\tt wxString} keys
+Declares a hash map class named CLASSNAME, with {\tt wxString} keys
 and VALUE\_T values.
 
 \begin{verbatim}
@@ -54,7 +56,7 @@ and VALUE\_T values.
                                  CLASSNAME ); // name of the class
 \end{verbatim}
 
-Declares an hash map class named CLASSNAME, with {\tt void*} keys
+Declares a hash map class named CLASSNAME, with {\tt void*} keys
 and VALUE\_T values.
 
 \begin{verbatim}
@@ -66,7 +68,7 @@ and VALUE\_T values.
 \end{verbatim}
 
 The HASH\_T and KEY\_EQ\_T are the types
-used for the hashing function and key comparison. wxWindows provides
+used for the hashing function and key comparison. wxWidgets provides
 three predefined hashing functions: {\tt wxIntegerHash}
 for integer types ( {\tt int}, {\tt long}, {\tt short},
 and their unsigned counterparts ), {\tt wxStringHash} for strings
@@ -75,7 +77,7 @@ and their unsigned counterparts ), {\tt wxStringHash} for strings
 Similarly three equality predicates:
 {\tt wxIntegerEqual}, {\tt wxStringEqual}, {\tt wxPointerEqual} are provided.
 
-Using this you could declare an hash map mapping {\tt int} values
+Using this you could declare a hash map mapping {\tt int} values
 to {\tt wxString} like this:
 
 \begin{verbatim}
@@ -84,6 +86,38 @@ to {\tt wxString} like this:
                          wxIntegerHash,
                          wxIntegerEqual,
                          MyHash );
+
+    // using an user-defined class for keys
+    class MyKey { /* ... */ };
+
+    // hashing function
+    class MyKeyHash
+    {
+    public:
+        MyKeyHash() { }
+
+        unsigned long operator()( const MyKey& k ) const
+            { /* compute the hash */ }
+
+        MyKeyHash& operator=(const MyKeyHash&) { return *this; }
+    };
+
+    // comparison operator
+    class MyKeyEqual
+    {
+    public:
+        MyKeyEqual() { }
+        bool operator()( const MyKey& a, const MyKey& b ) const
+            { /* compare for equality */ }
+
+        MyKeyEqual& operator=(const MyKeyEqual&) { return *this; }
+    };
+
+    WX_DECLARE_HASH_MAP( MyKey,      // type of the keys
+                         SOME_TYPE,  // any type you like
+                         MyKeyHash,  // hasher
+                         MyKeyEqual, // key equality predicate
+                         CLASSNAME); // name of the class
 \end{verbatim}
 
 \latexignore{\rtfignore{\wxheading{Types}}}
@@ -96,11 +130,13 @@ you used in the class declaration.
 \twocolitem{wxHashMap::mapped\_type}{Type of the values stored in the hash map}
 \twocolitem{wxHashMap::value\_type}{Equivalent to
 {\tt struct \{ key\_type first; mapped\_type second \};} }
-\twocolitem{wxHashMap::iterator}{Used to enumerate all the elements in an hash
+\twocolitem{wxHashMap::iterator}{Used to enumerate all the elements in a hash
 map; it is similar to a {\tt value\_type*}}
 \twocolitem{wxHashMap::const\_iterator}{Used to enumerate all the elements
 in a constant hash map; it is similar to a {\tt const value\_type*}}
 \twocolitem{wxHashMap::size\_type}{Used for sizes}
+\twocolitem{wxHashMap::Insert\_Result}{The return value for
+\helpref{insert()}{wxhashmapinsert}}
 \end{twocollist}
 
 \wxheading{Iterators}
@@ -118,18 +154,18 @@ means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxHashMap::wxHashMap}
+\membersection{wxHashMap::wxHashMap}\label{wxhashmapctor}
 
 \func{}{wxHashMap}{\param{size\_type}{ size = 10}}
 
-The size parameter is just an hint, the table will resize automatically
+The size parameter is just a hint, the table will resize automatically
 to preserve performance.
 
 \func{}{wxHashMap}{\param{const wxHashMap\&}{ map}}
 
 Copy constructor.
 
-\membersection{wxHashMap::begin}
+\membersection{wxHashMap::begin}\label{wxhashmapbegin}
 
 \constfunc{const\_iterator}{begin}{}
 
@@ -138,26 +174,26 @@ Copy constructor.
 Returns an iterator pointing at the first element of the hash map.
 Please remember that hash maps do not guarantee ordering.
 
-\membersection{wxHashMap::clear}
+\membersection{wxHashMap::clear}\label{wxhashmapclear}
 
 \func{void}{clear}{}
 
 Removes all elements from the hash map.
 
-\membersection{wxHashMap::count}
+\membersection{wxHashMap::count}\label{wxhashmapcount}
 
 \constfunc{size\_type}{count}{\param{const key\_type\&}{ key}}
 
 Counts the number of elements with the given key present in the map.
-This function can actually return 0 or 1.
+This function returns only 0 or 1.
 
-\membersection{wxHashMap::empty}
+\membersection{wxHashMap::empty}\label{wxhashmapempty}
 
 \constfunc{bool}{empty}{}
 
-Returns true if the hash map does not contain any element, false otherwise.
+Returns true if the hash map does not contain any elements, false otherwise.
 
-\membersection{wxHashMap::end}
+\membersection{wxHashMap::end}\label{wxhashmapend}
 
 \constfunc{const\_iterator}{end}{}
 
@@ -166,11 +202,11 @@ Returns true if the hash map does not contain any element, false otherwise.
 Returns an iterator pointing at the one-after-the-last element of the hash map.
 Please remember that hash maps do not guarantee ordering.
 
-\membersection{wxHashMap::erase}
+\membersection{wxHashMap::erase}\label{wxhashmaperase}
 
 \func{size\_type}{erase}{\param{const key\_type\&}{ key}}
 
-Erases the element with the given key, and returns the number of element
+Erases the element with the given key, and returns the number of elements
 erased (either 0 or 1).
 
 \func{void}{erase}{\param{iterator}{ it}}
@@ -180,7 +216,7 @@ erased (either 0 or 1).
 Erases the element pointed to by the iterator. After the deletion
 the iterator is no longer valid and must not be used.
 
-\membersection{wxHashMap::find}
+\membersection{wxHashMap::find}\label{wxhashmapfind}
 
 \func{iterator}{find}{\param{const key\_type\&}{ key}}
 
@@ -190,23 +226,26 @@ If an element with the given key is present, the functions returns
 an iterator pointing at that element, otherwise an invalid iterator
 is returned (i.e. hashmap.find( non\_existent\_key ) == hashmap.end()).
 
-\membersection{wxHashMap::insert}
+\membersection{wxHashMap::insert}\label{wxhashmapinsert}
 
-\func{void}{insert}{\param{const value\_type\&}{ v}}
+\func{Insert\_Result}{insert}{\param{const value\_type\&}{ v}}
 
-Inserts the given value in the hash map.
+Inserts the given value in the hash map. The return value is
+equivalent to a \texttt{std::pair<wxHashMap::iterator, bool>};
+the iterator points to the inserted element, the boolean value
+is \texttt{true} if \texttt{v} was actually inserted.
 
-\membersection{wxHashMap::operator[]}
+\membersection{wxHashMap::operator[]}\label{wxhashmapbracket}
 
 \func{mapped\_type\&}{operator[]}{\param{const key\_type\&}{ key}}
 
-Use it as an array subscript. The only difference is that if the
+Use the key as an array subscript. The only difference is that if the
 given key is not present in the hash map, an element with the
 default {\tt value\_type()} is inserted in the table.
 
-\membersection{wxHashMap::size}
+\membersection{wxHashMap::size}\label{wxhashmapsize}
 
 \constfunc{size\_type}{size}{}
 
-Returns the numbers of elements in the map.
+Returns the number of elements in the map.
 
