added shortcut functions AddSpacer and AddStretchSpacer (plus Prepend and Insert...

[wxWidgets.git] / docs / latex / wx / hashmap.tex

diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex
index 916b4dbe4df92ee588197a69234b5bb90c01fde4..8177e74c8238364a6fb39c29c9097704a2566ea6 100644 (file)
--- a/docs/latex/wx/hashmap.tex
+++ b/docs/latex/wx/hashmap.tex
@@ -1,14 +1,16 @@
 \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. 
+This is a simple, type-safe, and reasonably efficient hash map class,
+whose interface is a subset of the interface of STL containers. In
+particular, the interface is modelled after std::map, and the various,
+non standard, std::hash\_map.
 
 \wxheading{Example}
 
 \begin{verbatim}
     class MyClass { /* ... */ };
 
-    // declare an hash map with string keys and int values
+    // declare a hash map with string keys and int values
     WX_DECLARE_STRING_HASH_MAP( int, MyHash5 );
     // same, with int keys and MyClass* values
     WX_DECLARE_HASH_MAP( int, MyClass*, wxIntegerHash, wxIntegerEqual, MyHash1 );
@@ -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
@@ -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
@@ -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}}}
@@ -135,8 +169,8 @@ Copy constructor.
 
 \func{iterator}{begin}{}
 
-Returns an iterator pointing at the first element of the hash map
-( please remember that hash maps do not guarantee ordering ).
+Returns an iterator pointing at the first element of the hash map.
+Please remember that hash maps do not guarantee ordering.
 
 \membersection{wxHashMap::clear}
 
@@ -155,7 +189,7 @@ This function can actually return 0 or 1.
 
 \constfunc{bool}{empty}{}
 
-TRUE if the hash map does not contain any element, FALSE otherwise.
+Returns true if the hash map does not contain any element, false otherwise.
 
 \membersection{wxHashMap::end}
 
@@ -163,15 +197,15 @@ TRUE if the hash map does not contain any element, FALSE otherwise.
 
 \func{iterator}{end}{}
 
-Returns an iterator pointing at the one-after-the-last element of the hash map
-( please remember that hash maps do not guarantee ordering ).
+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}
 
 \func{size\_type}{erase}{\param{const key\_type\&}{ key}}
 
 Erases the element with the given key, and returns the number of element
-erased ( either 0 or 1 ).
+erased (either 0 or 1).
 
 \func{void}{erase}{\param{iterator}{ it}}
 
@@ -188,7 +222,7 @@ the iterator is no longer valid and must not be used.
 
 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() ).
+is returned (i.e. hashmap.find( non\_existent\_key ) == hashmap.end()).
 
 \membersection{wxHashMap::insert}