Added a couple of wxPerl notes.

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

diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex
index 7216f954f92024ee68c114c412935b1c9112ad1c..5649d907eb25e68ecfd59e28d3d30b2117e3ba31 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 devault 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
@@ -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}}}
@@ -125,7 +159,7 @@ means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}.
 The size parameter is just an hint, the table will resize automatically
 to preserve performance.
 
-\func{}{wxHashMap}{\param{const wxHashMap&}{ map}}
+\func{}{wxHashMap}{\param{const wxHashMap\&}{ map}}
 
 Copy constructor.
 
@@ -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}
 
@@ -146,7 +180,7 @@ Removes all elements from the hash map.
 
 \membersection{wxHashMap::count}
 
-\constfunc{size\_type}{count}{\param{const key\_type&}{ key}}
+\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.
@@ -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}}
+\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}}
 
@@ -182,23 +216,23 @@ the iterator is no longer valid and must not be used.
 
 \membersection{wxHashMap::find}
 
-\func{iterator}{find}{\param{const key\_type&}{ key}}
+\func{iterator}{find}{\param{const key\_type\&}{ key}}
 
-\constfunc{const\_iterator}{find}{\param{const key\_type&}{ key}}
+\constfunc{const\_iterator}{find}{\param{const key\_type\&}{ key}}
 
 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}
 
-\func{void}{insert}{\param{const value\_type&}{ v}}
+\func{void}{insert}{\param{const value\_type\&}{ v}}
 
 Inserts the given value in the hash map.
 
 \membersection{wxHashMap::operator[]}
 
-\func{mapped\_type&}{operator[]}{\param{const key\_type&}{ key}}
+\func{mapped\_type\&}{operator[]}{\param{const key\_type\&}{ key}}
 
 Use it as an array subscript. The only difference is that if the
 given key is not present in the hash map, an element with the
@@ -209,3 +243,4 @@ default {\tt value\_type()} is inserted in the table.
 \constfunc{size\_type}{size}{}
 
 Returns the numbers of elements in the map.
+