Documentation for wxHashMap, added deprecation to wxHashTable.

Quoted some unquoted _ here and there.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@13914 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -267,7 +267,8 @@ These are the data structure classes supported by wxWindows.
 \twocolitem{\helpref{wxDateTime}{wxdatetime}}{A class for date/time manipulations}
 \twocolitem{\helpref{wxExpr}{wxexpr}}{A class for flexible I/O}
 \twocolitem{\helpref{wxExprDatabase}{wxexprdatabase}}{A class for flexible I/O}
-\twocolitem{\helpref{wxHashTable}{wxhashtable}}{A simple hash table implementation}
+\twocolitem{\helpref{wxHashMap}{wxhashmap}}{A simple hash map implementation}
+\twocolitem{\helpref{wxHashTable}{wxhashtable}}{A simple hash table implementation (deprecated, use wxHashMap)}
 % \twocolitem{\helpref{wxHashTableLong}{wxhashtablelong}}{A wxHashTable version for storing long data}
 \twocolitem{\helpref{wxList}{wxlist}}{A simple linked list implementation}
 \twocolitem{\helpref{wxLongLong}{wxlonglong}}{A portable 64 bit integer type}

docs/latex/wx/classes.tex

@@ -130,6 +130,7 @@
 \input gridrend.tex
 \input gridtbl.tex
 \input gridsizr.tex
+\input hashmap.tex
 \input hash.tex
 \input helpinst.tex
 \input hprovcnt.tex

docs/latex/wx/gridrend.tex

@@ -37,7 +37,7 @@ This class may be used to format floating point data in a cell.
 
 \helpref{wxGridCellRenderer}{wxgridcellrenderer},\rtfsp
 \helpref{wxGridCellNumberRenderer}{wxgridcellnumberrenderer},\rtfsp
-\helpref{wxGridCellTextRenderer}{wxgridcelltextrenderer},\rtfsp
+\helpref{wxGridCellStringRenderer}{wxgridcellstringrenderer},\rtfsp
 \helpref{wxGridCellBoolRenderer}{wxgridcellboolrenderer}
 
 \latexignore{\rtfignore{\wxheading{Members}}}

docs/latex/wx/hash.tex

@@ -1,5 +1,8 @@
 \section{\class{wxHashTable}}\label{wxhashtable}
 
+{\bf Please note} that this class is retained for backward compatibility
+reasons; you should use \helpref{wxHashMap}{wxhashmap}.
+
 This class provides hash table functionality for wxWindows, and for an
 application if it wishes.  Data can be hashed on an integer or string
 key.

docs/latex/wx/hashmap.tex

@@ -0,0 +1,211 @@
+\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. 
+
+\wxheading{Example}
+
+\begin{verbatim}
+    class MyClass { /* ... */ };
+
+    // declare an 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 );
+    // same, with wxString keys and int values
+    WX_DECLARE_STRING_HASH_MAP( int, MyHash3 );
+    // same, with wxString keys and values
+    WX_DECLARE_STRING_HASH_MAP( wxString, MyHash2 );
+
+    MyHash1 h1;
+    MyHash2 h2;
+
+    // store and retrieve values
+    h1[1] = new MyClass( 1 );
+    h1[10000000] = NULL;
+    h1[50000] = new MyClass( 2 );
+    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
+    MyClass tmp2 = h2["Joe"];
+
+    // iterate over all the elements in the class
+    MyHash2::iterator it;
+    for( it = h2.begin(); it != h2.end(); ++it )
+    {
+        wxString key = it->first, value = it->second;
+        // do something useful with key and value
+    }
+\end{verbatim}
+
+\wxheading{Declaring new hash table types}
+
+\begin{verbatim}
+    WX_DECLARE_STRING_HASH_MAP( VALUE_T,     // type of the values
+                                CLASSNAME ); // name of the class
+\end{verbatim}
+
+Declares an hash map class named CLASSNAME, with {\tt wxString} keys
+and VALUE\_T values.
+
+\begin{verbatim}
+    WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T,     // type of the values
+                                 CLASSNAME ); // name of the class
+\end{verbatim}
+
+Declares an hash map class named CLASSNAME, with {\tt void*} keys
+and VALUE\_T values.
+
+\begin{verbatim}
+    WX_DECLARE_HASH_MAP( KEY_T,      // type of the keys
+                         VALUE_T,    // type of the values
+                         HASH_T,     // hasher
+                         KEY_EQ_T,   // key equality predicate
+                         CLASSNAME); // name of the class
+\end{verbatim}
+
+The HASH\_T and KEY\_EQ\_T are the types
+used for the hashing function and key comparison. wxWindows provides
+three predefined hashing functions: {\tt wxIntegerHash}
+for integer types ( {\tt int}, {\tt long}, {\tt short},
+and their unsigned counterparts ), {\tt wxStringHash} for strings
+( {\tt wxString}, {\tt wxChar*}, {\tt char*} ), and
+{\tt wxPointerHash} for any kind of pointer.
+Similarly three equality predicates:
+{\tt wxIntegerEqual}, {\tt wxStringEqual}, {\tt wxPointerEqual} are provided.
+
+Using this you could declare an hash map mapping {\tt int} values
+to {\tt wxString} like this:
+
+\begin{verbatim}
+    WX_DECLARE_HASH_MAP( int,
+                         wxString,
+                         wxIntegerHash,
+                         wxIntegerEqual,
+                         MyHash );
+\end{verbatim}
+
+\latexignore{\rtfignore{\wxheading{Types}}}
+
+In the documentation below you should replace wxHashMap with the name
+you used in the class declaration.
+
+\begin{twocollist}
+\twocolitem{wxHashMap::key\_type}{Type of the hash keys}
+\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
+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}
+\end{twocollist}
+
+\wxheading{Iterators}
+
+An iterator is similar to a pointer, and so you can use the usual pointer
+operations: {\tt ++it} ( and {\tt it++} ) to move to the next element,
+{\tt *it} to access the element pointed to, {\tt it->first}
+( {\tt it->second} ) to access the key ( value )
+of the element pointed to. Hash maps provide forward only iterators, this
+means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}.
+
+\wxheading{Include files}
+
+<wx/hashmap.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxHashMap::wxHashMap}
+
+\func{}{wxHashMap}{\param{size\_type}{ size = 10}}
+
+The size parameter is just an hint, the table will resize automatically
+to preserve performance.
+
+\func{}{wxHashMap}{\param{const wxHashMap&}{ map}}
+
+Copy constructor.
+
+\membersection{wxHashMap::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 ).
+
+\membersection{wxHashMap::clear}
+
+\func{void}{clear}{}
+
+Removes all elements from the hash map.
+
+\membersection{wxHashMap::count}
+
+\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.
+
+\membersection{wxHashMap::empty}
+
+\constfunc{bool}{empty}{}
+
+TRUE if the hash map does not contain any element, FALSE otherwise.
+
+\membersection{wxHashMap::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 ).
+
+\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 ).
+
+\func{void}{erase}{\param{iterator}{ it}}
+
+\func{void}{erase}{\param{const\_iterator}{ it}}
+
+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}
+
+\func{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() ).
+
+\membersection{wxHashMap::insert}
+
+\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}}
+
+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
+default {\tt value\_type()} is inserted in the table.
+
+\membersection{wxHashMap::size}
+
+\constfunc{size\_type}{size}{}
+
+Returns the numbers of elements in the map.

docs/latex/wx/list.tex

@@ -3,7 +3,7 @@
 wxList classes provide linked list functionality for wxWindows, and for an
 application if it wishes.  Depending on the form of constructor used, a list
 can be keyed on integer or string keys to provide a primitive look-up ability.
-See \helpref{wxHashTable}{wxhashtable}\rtfsp for a faster method of storage
+See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage
 when random access is required.
 
 While wxList class in the previous versions of wxWindows only could contain

docs/latex/wx/radiobox.tex

@@ -198,7 +198,7 @@ Returns the selected string.
 \constfunc{int}{Number}{\void}
 
 {\bf Obsolescence note:} This method is obsolete and was replaced with 
-\helpref{GetCount}{wxradiooboxgetcount}, please use the new method in the new
+\helpref{GetCount}{wxradioboxgetcount}, please use the new method in the new
 code. This method is only available if wxWindows was compiled with 
 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
 future versions.

docs/latex/wx/tguide.tex

@@ -42,7 +42,7 @@ need wxHelp and the \helpref{wxHelpController}{wxhelpcontroller} class to contro
 wxHelp.
 
 GUI applications aren't all graphical wizardry. List and hash table needs are
-catered for by \helpref{wxList}{wxlist}, \helpref{wxStringList}{wxstringlist} and \helpref{wxHashTable}{wxhashtable}.
+catered for by \helpref{wxList}{wxlist}, \helpref{wxStringList}{wxstringlist} and \helpref{wxHashMap}{wxhashmap}.
 You will undoubtedly need some platform-independent \helpref{file functions}{filefunctions},
 and you may find it handy to maintain and search a list of paths using \helpref{wxPathList}{wxpathlist}.
 There's a \helpref{miscellany}{miscellany} of operating system and other functions.

docs/latex/wx/tipwin.tex

@@ -53,7 +53,7 @@ unexpectedly to the caller) it may {\tt NULL} out the pointer pointed to by
 had been already closed and deleted.
 
 
-\membersection{wxTipWindow::SetBoundingRect}{wxtipwindowsetboundingrect}
+\membersection{wxTipWindow::SetBoundingRect}\label{wxtipwindowsetboundingrect}
 
 \func{void}{SetBoundingRect}{\param{const wxRect\& }{rectBound}}
 

docs/latex/wx/tsizer.tex

@@ -44,7 +44,7 @@ There are currently five different kinds of sizers available in wxWindows. Each
 either a certain way to lay out dialog items in a dialog or it fulfils a special task
 such as wrapping a static box around a dialog item (or another sizer). These sizers will
 be discussed one by one in the text below. For more detailed information on how to use sizers
-programmatically, please refer to the section \helpref{Programming with Sizers}{sizersprogramming}.
+programmatically, please refer to the section \helpref{Programming with Sizers}{boxsizerprogramming}.
 
 \subsubsection{Common features}\label{sizerscommonfeatures}
 

docs/latex/wx/txrc.tex

@@ -74,7 +74,7 @@ and then call \verb$wxXmlResource::Get()->Load("myfile.xrc")$ to load the resour
 \item to create a dialog from a resource, create it using the default constructor, and then
 load using for example \verb$wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1")$;
 \item set up event tables as usual but use the \verb$XRCID(str)$ macro to translate from XRC string names
-to a suitable integer identifier, for example \verb$EVT_MENU(XRCID("quit"), MyFrame::OnQuit)$.
+to a suitable integer identifier, for example \verb$EVT\_MENU(XRCID("quit"), MyFrame::OnQuit)$.
 \end{itemize}
 
 To create an XRC file, use one of the following methods.

docs/latex/wx/wxhtml.tex

@@ -15,7 +15,7 @@ class which allows you to use your own virtual file systems.
 wxHtmlWindow supports tag handlers. This means that you can easily
 extend wxHtml library with new, unsupported tags. Not only that,
 you can even use your own application-specific tags!
-See \verb$src/html/m_*.cpp$ files for details.
+See \verb$src/html/m\_*.cpp$ files for details.
 
 There is a generic wxHtmlParser class,
 independent of wxHtmlWindow.

docs/latex/wx/xmlres.tex

@@ -28,8 +28,8 @@ try to use it, you will get link errors.
 \begin{enumerate}
 enum wxXmlResourceFlags
 {
-    wxXRC_USE_LOCALE     = 1,
-    wxXRC_NO_SUBCLASSING = 2
+    wxXRC\_USE\_LOCALE     = 1,
+    wxXRC\_NO\_SUBCLASSING = 2
 };
 \end{enumerate}