Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remaining h* interface header revision

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56662 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-11-03 14:37:14 +00:00
parent f9bb777f88
commit 9cc56d1fc0
6 changed files with 627 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
interface/wx/hashset.h
View File

@@ -10,31 +10,154 @@
@class 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,
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.
Example:
@code
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
}
@endcode
@section hashset_declaringnew Declaring new hash set types
@code
WX_DECLARE_HASH_SET( KEY_T, // type of the keys
HASH_T, // hasher
KEY_EQ_T, // key equality predicate
CLASSNAME); // name of the class
@endcode
The HASH_T and KEY_EQ_T are the types used for the hashing function and key
comparison. wxWidgets provides three predefined hashing functions:
wxIntegerHash for integer types ( int, long, short, and their unsigned counterparts ),
wxStringHash for strings ( wxString, wxChar*, char* ), and wxPointerHash for
any kind of pointer.
Similarly three equality predicates: wxIntegerEqual, wxStringEqual, wxPointerEqual
are provided. Using this you could declare a hash set using int values like this:
@code
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
@endcode
@section hashset_types Types
In the documentation below you should replace wxHashSet with the name you
used in the class declaration.
- wxHashSet::key_type: Type of the hash keys
- wxHashSet::mapped_type: Type of hash keys
- wxHashSet::value_type: Type of hash keys
- wxHashSet::iterator: Used to enumerate all the elements in a hash set;
it is similar to a value_type*
- wxHashSet::const_iterator: Used to enumerate all the elements in a constant
hash set; it is similar to a const value_type*
- wxHashSet::size_type: Used for sizes
- wxHashSet::Insert_Result: The return value for insert()
@section hashset_iter Iterators
An iterator is similar to a pointer, and so you can use the usual pointer
operations: ++it ( and it++ ) to move to the next element, *it to access the
element pointed to, *it to access the value of the element pointed to.
Hash sets provide forward only iterators, this means that you can't use --it,
it + 3, it1 - it2.
@library{wxbase}
@category{FIXME}
@category{containers}
*/
class wxHashSet
{
public:
//@{
/**
The size parameter is just a hint, the table will resize automatically
to preserve performance.
*/
wxHashSet(size_type size = 10);
/**
Copy constructor.
*/
wxHashSet(size_type size = 10);
wxHashSet(const wxHashSet& set);
//@}
//@{
/**
Returns an iterator pointing at the first element of the hash set.
Please remember that hash sets do not guarantee ordering.
*/
const_iterator begin();
const iterator begin();
const_iterator begin() const;
iterator begin();
//@}
/**
@@ -58,16 +181,21 @@ public:
Returns an iterator pointing at the one-after-the-last element of the hash set.
Please remember that hash sets do not guarantee ordering.
*/
const_iterator end();
const iterator end();
const_iterator end() const;
iterator end();
//@}
/**
Erases the element with the given key, and returns the number of elements
erased (either 0 or 1).
*/
size_type erase(const key_type& key);
//@{
/**
Erases the element pointed to by the iterator. After the deletion
the iterator is no longer valid and must not be used.
*/
size_type erase(const key_type& key);
void erase(iterator it);
void erase(const_iterator it);
//@}
@@ -76,17 +204,21 @@ public:
/**
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()).
is returned; i.e.
@code
hashset.find( non_existent_key ) == hashset.end()
@endcode
*/
iterator find(const key_type& key) const;
const_iterator find(const key_type& key) const;
//@}
/**
Inserts the given value in the hash set. The return value is
equivalent to a @c std::pairwxHashMap::iterator, bool;
the iterator points to the inserted element, the boolean value
is @true if @c v was actually inserted.
Inserts the given value in the hash set.
The return value is equivalent to a
@code std::pair<wxHashMap::iterator, bool> @endcode
The iterator points to the inserted element, the boolean value is @true
if @a v was actually inserted.
*/
Insert_Result insert(const value_type& v);