Mark GetMinSize() as virtual and explain why.

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

diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex
index bcf6f2f87e8df5b694657d9dad072f9d6417ecaa..ebb9c60e6a3c55b0593afdb78f946271ecab99a5 100644 (file)
--- a/docs/latex/wx/hashmap.tex
+++ b/docs/latex/wx/hashmap.tex
@@ -1,14 +1,16 @@
 \section{\class{wxHashMap}}\label{wxhashmap}
 
 \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 modeled after std::map, and the various,
+non-standard, std::hash\_map.

 
 \wxheading{Example}
 
 \begin{verbatim}
     class MyClass { /* ... */ };
 
 
 \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 );
     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
     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
     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}
 
                                 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}
 and VALUE\_T values.
 
 \begin{verbatim}


@@ -54,7 +56,7 @@ and VALUE\_T values.
                                  CLASSNAME ); // name of the class
 \end{verbatim}
 
                                  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}
 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
 \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
 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.
 
 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}
 to {\tt wxString} like this:
 
 \begin{verbatim}


@@ -84,6 +86,38 @@ to {\tt wxString} like this:
                          wxIntegerHash,
                          wxIntegerEqual,
                          MyHash );
                          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}}}
 \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::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}
 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}
 \end{twocollist}
 
 \wxheading{Iterators}


@@ -118,60 +154,60 @@ means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxHashMap::wxHashMap}
+\membersection{wxHashMap::wxHashMap}\label{wxhashmapctor}

 
 \func{}{wxHashMap}{\param{size\_type}{ size = 10}}
 
 
 \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.
 
 to preserve performance.
 
 \func{}{wxHashMap}{\param{const wxHashMap\&}{ map}}
 
 Copy constructor.
 

-\membersection{wxHashMap::begin}
+\membersection{wxHashMap::begin}\label{wxhashmapbegin}

 
 \constfunc{const\_iterator}{begin}{}
 
 \func{iterator}{begin}{}
 
 
 \constfunc{const\_iterator}{begin}{}
 
 \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}
+\membersection{wxHashMap::clear}\label{wxhashmapclear}

 
 \func{void}{clear}{}
 
 Removes all elements from the hash map.
 
 
 \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.
 
 \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}{}
 
 
 \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 elements, false otherwise.

 
 

-\membersection{wxHashMap::end}
+\membersection{wxHashMap::end}\label{wxhashmapend}

 
 \constfunc{const\_iterator}{end}{}
 
 \func{iterator}{end}{}
 
 
 \constfunc{const\_iterator}{end}{}
 
 \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}
+\membersection{wxHashMap::erase}\label{wxhashmaperase}

 
 \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 ).
+Erases the element with the given key, and returns the number of elements
+erased (either 0 or 1).

 
 \func{void}{erase}{\param{iterator}{ it}}
 
 
 \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.
 
 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}}
 
 
 \func{iterator}{find}{\param{const key\_type\&}{ key}}
 


@@ -188,25 +224,28 @@ 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
 
 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}
+\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}}
 
 
 \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.
 
 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}{}
 
 
 \constfunc{size\_type}{size}{}
 

-Returns the numbers of elements in the map.
+Returns the number of elements in the map.