From 8cd74a14cda5b744af89240d2eef7d4b65a636c6 Mon Sep 17 00:00:00 2001 From: Mattia Barbon Date: Wed, 8 Dec 2004 22:33:40 +0000 Subject: [PATCH] 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 | 1 + docs/latex/wx/classes.tex | 1 + docs/latex/wx/hashmap.tex | 9 +- docs/latex/wx/hashset.tex | 223 +++++++++++++++++++++++++++++++++++++ 4 files changed, 232 insertions(+), 2 deletions(-) create mode 100644 docs/latex/wx/hashset.tex diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex index 517185ec06..95ed8acfa7 100644 --- a/docs/latex/wx/category.tex +++ b/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} diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index 19afe1e063..4a7d62a1b9 100644 --- a/docs/latex/wx/classes.tex +++ b/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 diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex index 128035adb1..67427d640b 100644 --- a/docs/latex/wx/hashmap.tex +++ b/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}; +the iterator points to the inserted element, the boolean value +is \texttt{true} if \texttt{v} was actually inserted. \membersection{wxHashMap::operator[]}\label{wxhashmapbracket} diff --git a/docs/latex/wx/hashset.tex b/docs/latex/wx/hashset.tex new file mode 100644 index 0000000000..708fdd1084 --- /dev/null +++ b/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} + + + +\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}; +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. + -- 2.45.2