\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 { /* ... */ };
- // 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 );
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
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}
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}
\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
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}
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}}}
\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}
+\twocolitem{wxHashMap::Insert\_Result}{The return value for
+\helpref{insert()}{wxhashmapinsert}}
\end{twocollist}
\wxheading{Iterators}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxHashMap::wxHashMap}
+\membersection{wxHashMap::wxHashMap}\label{wxhashmapctor}
\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}}
+\func{}{wxHashMap}{\param{const wxHashMap\&}{ map}}
Copy constructor.
-\membersection{wxHashMap::begin}
+\membersection{wxHashMap::begin}\label{wxhashmapbegin}
\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.
-\membersection{wxHashMap::count}
+\membersection{wxHashMap::count}\label{wxhashmapcount}
-\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.
+This function returns only 0 or 1.
-\membersection{wxHashMap::empty}
+\membersection{wxHashMap::empty}\label{wxhashmapempty}
\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}{}
-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}}
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}}
-\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}
+\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.
-\membersection{wxHashMap::size}
+\membersection{wxHashMap::size}\label{wxhashmapsize}
\constfunc{size\_type}{size}{}
-Returns the numbers of elements in the map.
+Returns the number of elements in the map.
projects / wxWidgets.git / blobdiff