X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6b3d51cc3560dd9629a104bf000668fdc2f75a6b..a3dae7b72cd2d1852398892d514eafd65cd34b64:/docs/latex/wx/hashmap.tex diff --git a/docs/latex/wx/hashmap.tex b/docs/latex/wx/hashmap.tex index 738ad03c29..ebb9c60e6a 100644 --- a/docs/latex/wx/hashmap.tex +++ b/docs/latex/wx/hashmap.tex @@ -1,14 +1,16 @@ \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 ); @@ -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 - // 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 @@ -46,7 +48,7 @@ whose interface is a subset of the interface of STL containers. 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} @@ -54,7 +56,7 @@ and VALUE\_T values. 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} @@ -66,7 +68,7 @@ and VALUE\_T values. \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 @@ -75,7 +77,7 @@ 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} @@ -84,6 +86,38 @@ to {\tt wxString} like this: 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}}} @@ -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::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} @@ -118,60 +154,60 @@ means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}. \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}} @@ -180,33 +216,36 @@ 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. -\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}; +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.