Inheritance diagram for Osp::Base::Collection::HashMap:

Since:: 1.0

The HashMap class contains unique keys and each key maps to one single value. The key and value cannot be a null reference.

For more information on the class features, see HashMap and MultiHashMap.

The following example demonstrates how to create and initialize a HashMap instance and how to use its methods.

    #include <FBase.h>
                                                                                                     
    using namespace Osp::Base;                                                                     
    using namespace Osp::Base::Collection;                                                               

                 
    void                                                                                                   
    MyClass::HashMapSample(void)                                                                       
    {                                                                                                        

        HashMap map;

        // Construct a HashMap instance with default capacity, load factor, hash code provider, and comparer.
        map.Construct();


        String*     pStr0 = new String(L"Zero");                                                                     
        String*     pStr1 = new String(L"One");                                                                     
        String*     pStr2 = new String(L"Two");                                                                     
                                                                                                             
        map.Add(*pStr0, *(new Integer(0))); // map.GetCount() : 1, map : (Zero -> 0)                          
        map.Add(*pStr1, *(new Integer(1))); // map.GetCount() : 2, map : (Zero -> 0), (one -> 1)              
        map.Add(*pStr2, *(new Integer(2))); // map.GetCount() : 3, map : (Zero -> 0), (one -> 1), (Two -> 2)  
                                                                                                              
                                                                                                             
        // Get a value with the specified key (GetValue)     
        String*     pKey = new String(L"Zero");
        Integer*    pValue = static_cast<Integer*> (map.GetValue(*pKey));   // pValue : 0                                                           


        // Remove a value with the specified key (Remove)     
        map.Remove(*pKey, true);

        delete pKey;

                                                                                                             
        // Use enumerator to access elements in the list                                                      
        IMapEnumerator*     pMapEnum = map.GetMapEnumeratorN();                                                                          
        while (pMapEnum->MoveNext() == E_SUCCESS)                                                                                          
        {                                                                                                     
            pKey = static_cast<String*> (pMapEnum->GetKey());                                                                         
            pValue = static_cast<Integer*> (pMapEnum->GetValue());                                                                     
        }                                                                                                     

        delete pMapEnum;
                                 

        // Deallocate all objects
        map.RemoveAll(true);

    }

List of all members.

Public Member Functions
virtual result	Add (const Object &key, const Object &value)
result	Construct (const IMap &map, float loadFactor=0.75)
result	Construct (int capacity, float loadFactor, const IHashCodeProvider &provider, const IComparer &comparer)
result	Construct (int capacity=16, float loadFactor=0.75)
result	Construct (const IMap &map, float loadFactor, const IHashCodeProvider &provider, const IComparer &comparer)
virtual result	ContainsKey (const Object &key, bool &out) const
virtual bool	ContainsValue (const Object &value) const
virtual bool	Equals (const Object &obj) const
virtual int	GetCount (void) const
virtual IEnumerator *	GetEnumeratorN (void) const
virtual IList *	GetKeysN (void) const
virtual IMapEnumerator *	GetMapEnumeratorN (void) const
virtual const Object *	GetValue (const Object &key) const
virtual Object *	GetValue (const Object &key)
virtual IList *	GetValuesN (void) const
	HashMap (void)
virtual result	Remove (const Object &key, bool deallocate=false)
virtual void	RemoveAll (bool deallocate=false)
virtual result	SetValue (const Object &key, const Object &value, bool deallocate=false)
virtual	~HashMap (void)

Constructor & Destructor Documentation

Osp::Base::Collection::HashMap::HashMap ( void )

This is the default constructor for this class.

Since:: 1.0

Remarks:: After creating an instance of the HashMap class, one of the Construct() methods must be called explicitly to initialize this instance.

See also:: Construct()

virtual Osp::Base::Collection::HashMap::~HashMap ( void ) [virtual]

This is the destructor for this class.

Since:: 1.0

Member Function Documentation

virtual result Osp::Base::Collection::HashMap::Add	(	const Object &	key,
		const Object &	value
	)		`[virtual]`

Adds the specified key-value pair to a map.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	key	The key of the value to add
[in]	value	The value to add

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare the keys.
E_OBJ_ALREADY_EXIST	The specified `key` already exists.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: This method performs a shallow copy. It adds only the pointer; not the element itself.

See also:: Remove()

Implements Osp::Base::Collection::IMap.

result Osp::Base::Collection::HashMap::Construct	(	int	capacity = `16`,
		float	loadFactor = `0.75`
	)

Initializes an instance of an empty HashMap class with the initial capacity and load factor.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	capacity	The initial capacity
[in]	loadFactor	The maximum ratio of elements to buckets

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, the `capacity` or the `loadFactor` is negative.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The GetHashCode() method of key objects is used for hashing and the Equals() method of key objects is used for comparing keys.

See also:: HashMap()

result Osp::Base::Collection::HashMap::Construct	(	const IMap &	map,
		float	loadFactor,
		const IHashCodeProvider &	provider,
		const IComparer &	comparer
	)

Initializes an instance of a HashMap class by copying the elements of a specified map with a specified load factor, hash code provider, and comparer.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	map	The map to copy
[in]	loadFactor	The maximum ratio of elements to buckets If it is `0`, the default load factor(0.75) is used.
[in]	provider	An instance of the IHashCodeProvider derived class that supplies the hash codes for all keys in this map
[in]	comparer	An instance of the IComparer derived class to use when comparing keys

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the `loadFactor` is negative.
E_INVALID_OPERATION	The current state of the instance prohibits the execution of the specified operation, or the `map` is modified during the operation of this method.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: This method performs a shallow copy. It copies only the pointer ; not the element itself.; The instances of hash code provider and comparer will not be deallocated later from this map.

See also:: HashMap()

result Osp::Base::Collection::HashMap::Construct	(	const IMap &	map,
		float	loadFactor = `0.75`
	)

Initializes an instance of a HashMap class by copying the elements of the specified map.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	map	The map to copy
[in]	loadFactor	The maximum ratio of elements to buckets

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the `loadFactor` is negative.
E_INVALID_OPERATION	The current state of the instance prohibits the execution of the specified operation, or the `map` is modified during the operation of this method.
E_OUT_OF_MEMORY	Insufficient memory.

Remarks:: This method performs a shallow copy. It copies only the pointer; not the element itself.

See also:: HashMap()

result Osp::Base::Collection::HashMap::Construct	(	int	capacity,
		float	loadFactor,
		const IHashCodeProvider &	provider,
		const IComparer &	comparer
	)

Initializes an instance of an empty HashMap class with the specified initial capacity, load factor, hash code provider, and comparer.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	capacity	The initial capacity If it is `0`, the default capacity(16) is used.
[in]	loadFactor	The maximum ratio of elements to buckets If it is `0`, the default load factor(0.75) is used.
[in]	provider	An instance of the IHashCodeProvider derived class that supplies the hash codes for all the keys in this map
[in]	comparer	An instance of the IComparer derived class to use when comparing the keys

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the `capacity` or the `loadFactor` is negative.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The instances of hash code provider and comparer will not be deallocated later from this map.

See also:: HashMap()

virtual result Osp::Base::Collection::HashMap::ContainsKey	(	const Object &	key,
		bool &	out
	)		const `[virtual]`

Checks whether the map contains the specified key.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	key	The key to locate
[out]	out	Set to `true` if the map contains the specified key, else `false`

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare the keys.

See also:: ContainsValue()

Implements Osp::Base::Collection::IMap.

virtual bool Osp::Base::Collection::HashMap::ContainsValue ( const Object & value ) const [virtual]

Checks whether the map contains the specified value.

Since:: 1.0

Returns:: true if the map contains the specified value,
else false

Parameters:

[in] value The value to locate

See also:: ContainsKey()

Implements Osp::Base::Collection::IMap.

virtual bool Osp::Base::Collection::HashMap::Equals ( const Object & obj ) const [virtual]

Compares two instances of the HashMap class.

Since:: 1.0

Returns:: true if the two instances match,
else false

Parameters:

[in] obj The object to compare with the current instance

Remarks:: This method returns true if and only if the two instances contain the same number of elements and all the elements contained in each other.

Reimplemented from Osp::Base::Object.

virtual int Osp::Base::Collection::HashMap::GetCount ( void ) const [virtual]

Gets the number of pairs currently stored in the map.

Since:: 1.0

Returns:: The pairs stored in the map

Implements Osp::Base::Collection::ICollection.

virtual IEnumerator* Osp::Base::Collection::HashMap::GetEnumeratorN ( void ) const [virtual]

Gets an enumerator (an instance of the IMapEnumerator derived class) of this map.

Since:: 1.0

Returns:: An instance of the IMapEnumerator derived class, if successful
else null if an exception occurs

Exceptions:

E_SUCCESS	The method is successful.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: Osp::Base::Collection::IEnumerator, Osp::Base::Collection::IMapEnumerator

Implements Osp::Base::Collection::ICollection.

virtual IList* Osp::Base::Collection::HashMap::GetKeysN ( void ) const [virtual]

Gets a list of all the keys in a map.

Since:: 1.0

Returns:: A pointer to an IList object containing all the keys in the map,
else null if an exception occurs

Exceptions:

E_SUCCESS	The method is successful.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method. The IList stores just the pointers to the elements in the map, not the elements themselves. The specific error code can be accessed using the GetLastResult() method.

See also:: GetValuesN()

Implements Osp::Base::Collection::IMap.

virtual IMapEnumerator* Osp::Base::Collection::HashMap::GetMapEnumeratorN ( void ) const [virtual]

Gets the elements of the map in an instance of the IMapEnumerator derived class.

Since:: 1.0

Returns:: An instance of the IMapEnumerator derived class, if successful
else null if an exception occurs

Exceptions:

E_SUCCESS	The method is successful.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: Osp::Base::Collection::IEnumerator, Osp::Base::Collection::IMapEnumerator

Implements Osp::Base::Collection::IMap.

virtual const Object* Osp::Base::Collection::HashMap::GetValue ( const Object & key ) const [virtual]

Gets the value associated with the specified key.

Since:: 1.0

Returns:: The value associated with the key,
else null if an exception occurs

Parameters:

[in] key The key to locate

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare the keys.
E_OBJ_NOT_FOUND	The specified `key` is not found in the map.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: SetValue()

Implements Osp::Base::Collection::IMap.

virtual Object* Osp::Base::Collection::HashMap::GetValue ( const Object & key ) [virtual]

Gets the value associated with the specified key.

Since:: 1.0

Returns:: The value associated with the key,
else null if an exception occurs

Parameters:

[in] key The key to locate

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare the keys.
E_OBJ_NOT_FOUND	The specified `key` is not found in the map.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: SetValue()

Implements Osp::Base::Collection::IMap.

virtual IList* Osp::Base::Collection::HashMap::GetValuesN ( void ) const [virtual]

Gets all the values in the map.

Since:: 1.0

Returns:: A pointer to an IList object containing all the values in the map,
else null if an exception occurs

Exceptions:

E_SUCCESS	The method is successful.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: The IList stores just the pointers to the elements in the map, not the elements themselves.; The specific error code can be accessed using the GetLastResult() method.

See also:: GetKeysN()

Implements Osp::Base::Collection::IMap.

virtual result Osp::Base::Collection::HashMap::Remove	(	const Object &	key,
		bool	deallocate = `false`
	)		`[virtual]`

Removes the values associated with a specified key.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	key	The key to be removed
[in]	deallocate	Set to `true` to deallocate the object, else `false`

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare keys.
E_OBJ_NOT_FOUND	The specified `key` is not found in the map.

See also:: Add()

Implements Osp::Base::Collection::IMap.

virtual void Osp::Base::Collection::HashMap::RemoveAll ( bool deallocate = false ) [virtual]

Removes all the object pointers in the collection.
If the deallocate param is true, it also removes all of the objects. This method can be called before deleting a collection.

Since:: 1.0

Parameters:

[in] deallocate Set to true to deallocate all the objects,
else false

Implements Osp::Base::Collection::IMap.

virtual result Osp::Base::Collection::HashMap::SetValue	(	const Object &	key,
		const Object &	value,
		bool	deallocate = `false`
	)		`[virtual]`

Replaces the value associated with a specified key by allocating it a new value.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	key	The key whose value is to be replaced
[in]	value	The new value to replace
[in]	deallocate	Set to `true` to deallocate the object, else `false`

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_ARG	A specified input parameter is invalid, or the comparer has failed to compare keys.
E_OBJ_NOT_FOUND	The specified `key` is not found in the map.

Remarks:: To add a new key-value pair, use the Add() method.

See also:: Add(), GetValue()

Implements Osp::Base::Collection::IMap.

The documentation for this class was generated from the following file:

FBaseColHashMap.h

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation