2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: hashset.h
|
2008-03-10 11:24:38 -04:00
|
|
|
// Purpose: interface of wxHashSet
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
|
|
|
// RCS-ID: $Id$
|
2010-07-13 09:29:13 -04:00
|
|
|
// Licence: wxWindows licence
|
2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
/**
|
|
|
|
@class wxHashSet
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This is a simple, type-safe, and reasonably efficient hash set class,
|
2008-11-03 09:37:14 -05:00
|
|
|
whose interface is a subset of the interface of STL containers.
|
2010-12-03 07:39:34 -05:00
|
|
|
|
|
|
|
The interface is similar to std::tr1::hash_set or std::set classes but
|
|
|
|
notice that, unlike std::set, the contents of a hash set is not sorted.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-11-03 09:37:14 -05:00
|
|
|
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.
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
2008-11-03 09:37:14 -05:00
|
|
|
@category{containers}
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-08 09:43:31 -05:00
|
|
|
class wxHashSet
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
2008-11-03 09:37:14 -05:00
|
|
|
The size parameter is just a hint, the table will resize automatically
|
|
|
|
to preserve performance.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
wxHashSet(size_type size = 10);
|
2008-11-03 09:37:14 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Copy constructor.
|
|
|
|
*/
|
2008-03-08 09:43:31 -05:00
|
|
|
wxHashSet(const wxHashSet& set);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
Returns an iterator pointing at the first element of the hash set.
|
|
|
|
Please remember that hash sets do not guarantee ordering.
|
|
|
|
*/
|
2008-11-03 09:37:14 -05:00
|
|
|
const_iterator begin() const;
|
|
|
|
iterator begin();
|
2008-03-08 08:52:38 -05:00
|
|
|
//@}
|
|
|
|
|
|
|
|
/**
|
|
|
|
Removes all elements from the hash set.
|
|
|
|
*/
|
|
|
|
void clear();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Counts the number of elements with the given key present in the set.
|
|
|
|
This function returns only 0 or 1.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
size_type count(const key_type& key) const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the hash set does not contain any elements, @false otherwise.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool empty() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
Returns an iterator pointing at the one-after-the-last element of the hash set.
|
|
|
|
Please remember that hash sets do not guarantee ordering.
|
|
|
|
*/
|
2008-11-03 09:37:14 -05:00
|
|
|
const_iterator end() const;
|
|
|
|
iterator end();
|
2008-03-08 08:52:38 -05:00
|
|
|
//@}
|
|
|
|
|
2008-11-03 09:37:14 -05:00
|
|
|
/**
|
|
|
|
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);
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
Erases the element pointed to by the iterator. After the deletion
|
|
|
|
the iterator is no longer valid and must not be used.
|
|
|
|
*/
|
2008-03-08 09:43:31 -05:00
|
|
|
void erase(iterator it);
|
|
|
|
void erase(const_iterator it);
|
2008-03-08 08:52:38 -05:00
|
|
|
//@}
|
|
|
|
|
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
If an element with the given key is present, the functions returns
|
|
|
|
an iterator pointing at that element, otherwise an invalid iterator
|
2008-11-03 09:37:14 -05:00
|
|
|
is returned; i.e.
|
|
|
|
@code
|
|
|
|
hashset.find( non_existent_key ) == hashset.end()
|
|
|
|
@endcode
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
iterator find(const key_type& key) const;
|
|
|
|
const_iterator find(const key_type& key) const;
|
2008-03-08 08:52:38 -05:00
|
|
|
//@}
|
|
|
|
|
|
|
|
/**
|
2008-11-03 09:37:14 -05:00
|
|
|
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.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
Insert_Result insert(const value_type& v);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the number of elements in the set.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
size_type size() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
2008-03-10 11:24:38 -04:00
|
|
|
|