Documented wxHashSet.

Corrected documentation for wxHashMap::insert() mentioning
the correct return value.


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

docs/latex/wx/category.tex

@@ -280,6 +280,7 @@ These are the data structure classes supported by wxWidgets.
 %\twocolitem{\helpref{wxExpr}{wxexpr}}{A class for flexible I/O}
 %\twocolitem{\helpref{wxExprDatabase}{wxexprdatabase}}{A class for flexible I/O}
 \twocolitem{\helpref{wxHashMap}{wxhashmap}}{A simple hash map implementation}
+\twocolitem{\helpref{wxHashSet}{wxhashset}}{A simple hash set 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}

docs/latex/wx/classes.tex

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

docs/latex/wx/hashmap.tex

@@ -135,6 +135,8 @@ 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}
@@ -226,9 +228,12 @@ is returned (i.e. hashmap.find( non\_existent\_key ) == hashmap.end()).
 
 \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[]}\label{wxhashmapbracket}
 

docs/latex/wx/hashset.tex

@@ -0,0 +1,223 @@
+\section{\class{wxHashSet}}\label{wxhashset}
+
+This is a simple, type-safe, and reasonably efficient hash set class,
+whose interface is a subset of the interface of STL containers. In
+particular, the interface is modeled after std::set, and the various,
+non standard, std::hash\_map.
+
+\wxheading{Example}
+
+\begin{verbatim}
+    class MyClass { /* ... */ };
+
+    // same, with MyClass* keys (only uses pointer equality!)
+    WX_DECLARE_HASH_SET( MyClass*, wxPointerHash, wxPointerEqual, MySet1 );
+    // same, with int keys
+    WX_DECLARE_HASH_SET( int, wxIntegerHash, wxIntegerEqual, MySet2 );
+    // declare a hash set with string keys
+    WX_DECLARE_HASH_SET( wxString, wxStringHash, wxStringEqual, MySet3 );
+
+    MySet1 h1;
+    MySet2 h1;
+    MySet3 h3;
+
+    // store and retrieve values
+    h1.insert( new MyClass( 1 ) );
+
+    h3.insert( "foo" );
+    h3.insert( "bar" );
+    h3.insert( "baz" );
+
+    int size = h3.size(); // now is three
+    bool has_foo = h3.find( "foo" ) != h3.end();
+
+    h3.insert( "bar" ); // still has size three
+
+    // iterate over all the elements in the class
+    MySet3::iterator it;
+    for( it = h3.begin(); it != h3.end(); ++it )
+    {
+        wxString key = *it;
+        // do something useful with key
+    }
+\end{verbatim}
+
+\wxheading{Declaring new hash set types}
+
+\begin{verbatim}
+    WX_DECLARE_HASH_SET( KEY_T,      // type of the keys
+                         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. 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
+( {\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 a hash set using {\tt int} values like this:
+
+\begin{verbatim}
+    WX_DECLARE_HASH_SET( int,
+                         wxIntegerHash,
+                         wxIntegerEqual,
+                         MySet );
+
+    // 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_SET( MyKey,      // type of the keys
+                         MyKeyHash,  // hasher
+                         MyKeyEqual, // key equality predicate
+                         CLASSNAME); // name of the class
+\end{verbatim}
+
+\latexignore{\rtfignore{\wxheading{Types}}}
+
+In the documentation below you should replace wxHashSet with the name
+you used in the class declaration.
+
+\begin{twocollist}
+\twocolitem{wxHashSet::key\_type}{Type of the hash keys}
+\twocolitem{wxHashSet::mapped\_type}{Type of hash keys}
+\twocolitem{wxHashSet::value\_type}{Type of hash keys}
+\twocolitem{wxHashSet::iterator}{Used to enumerate all the elements in a hash
+set; it is similar to a {\tt value\_type*}}
+\twocolitem{wxHashSet::const\_iterator}{Used to enumerate all the elements
+in a constant hash set; it is similar to a {\tt const value\_type*}}
+\twocolitem{wxHashSet::size\_type}{Used for sizes}
+\twocolitem{wxHashSet::Insert\_Result}{The return value for
+\helpref{insert()}{wxhashsetinsert}}
+\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}
+to access the value of the element pointed to.
+Hash sets provide forward only iterators, this
+means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}.
+
+\wxheading{Include files}
+
+<wx/hashset.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxHashSet::wxHashSet}\label{wxhashsetctor}
+
+\func{}{wxHashSet}{\param{size\_type}{ size = 10}}
+
+The size parameter is just a hint, the table will resize automatically
+to preserve performance.
+
+\func{}{wxHashSet}{\param{const wxHashSet\&}{ set}}
+
+Copy constructor.
+
+\membersection{wxHashSet::begin}\label{wxhashsetbegin}
+
+\constfunc{const\_iterator}{begin}{}
+
+\func{iterator}{begin}{}
+
+Returns an iterator pointing at the first element of the hash set.
+Please remember that hash sets do not guarantee ordering.
+
+\membersection{wxHashSet::clear}\label{wxhashsetclear}
+
+\func{void}{clear}{}
+
+Removes all elements from the hash set.
+
+\membersection{wxHashSet::count}\label{wxhashsetcount}
+
+\constfunc{size\_type}{count}{\param{const key\_type\&}{ key}}
+
+Counts the number of elements with the given key present in the set.
+This function returns only 0 or 1.
+
+\membersection{wxHashSet::empty}\label{wxhashsetempty}
+
+\constfunc{bool}{empty}{}
+
+Returns true if the hash set does not contain any elements, false otherwise.
+
+\membersection{wxHashSet::end}\label{wxhashsetend}
+
+\constfunc{const\_iterator}{end}{}
+
+\func{iterator}{end}{}
+
+Returns an iterator pointing at the one-after-the-last element of the hash set.
+Please remember that hash sets do not guarantee ordering.
+
+\membersection{wxHashSet::erase}\label{wxhashseterase}
+
+\func{size\_type}{erase}{\param{const key\_type\&}{ key}}
+
+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{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{wxHashSet::find}\label{wxhashsetfind}
+
+\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. hashset.find( non\_existent\_key ) == hashset.end()).
+
+\membersection{wxHashSet::insert}\label{wxhashsetinsert}
+
+\func{Insert\_Result}{insert}{\param{const value\_type\&}{ v}}
+
+Inserts the given value in the hash set. 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{wxHashSet::size}\label{wxhashsetsize}
+
+\constfunc{size\_type}{size}{}
+
+Returns the number of elements in the set.
+