SFXOldHashmap

[DEPRECATED] Class which represents a map utilizing a hash table to achieve high performance in search.

#include <SFXOldHashmap.h.hpp>

class SFXOldHashmap;

SFMTYPEDEFCLASS(SFXOldHashmap)

Inheritance diagram

Collaboration diagram

Description

	DEPRECATED
	It is recommended not to use this class since it will be deprecated in SophiaFramework UNIVERSE 6.0. Instead, use the `SFXLinkedHashMap` class.

Each key element of the SFXOldHashmap instance(hashmap) needs to be data not more than 4 byte, the SFXAnsiString instance, or the SFXWideString instance. In order to process data more than 4 byte(such as UInt64 type, Float64 type, and so on) or class instance as a value element of the SFXOldHashmap instance(hashmap), a pointer should be used.

// data more than 4 byte or class instance cannot be a value element of the SFXOldHashmap instance ( hashmap )

// SFXOldHashmap<SFXAnsiString, SInt64> map64;          NG
// SFXOldHashmap<SFXAnsiString, SFXAnsiString> mapstr;  NG

// but a pointer to the data more than 4 byte or class instance can be a value element of the SFXOldHashmap instance ( hashmap )

SFXOldHashmap<SFXAnsiString, SInt64Ptr> map64;             // OK
SFXOldHashmap<<SFXAnsiString, SFXAnsiStringPtr> mapstr; // OK

Change of Specification

	Change of Specification
The size of the hash table will automatically expand by an appropriate prime number when the number of the elements exceeds the threshold set with the `SFXOldHashmap::SetThreshold` function. Therefore the `SFXOldHashmap::SetRatio` and `SFXOldHashmap::SetRatio` functions are invalid. Since the SFXOldHashmap class can save multiple elements into one hashmap table entry, you can specify a number bigger than 100 as threshold value(default value is 80). Specifying threshold value bigger than 100, you can save scarce memory of mobile phone.

The size of the hash table will automatically expand by an appropriate prime number when the number of the elements exceeds the threshold set with the SFXOldHashmap::SetThreshold function.

Therefore the SFXOldHashmap::SetRatio and SFXOldHashmap::SetRatio functions are invalid.

Since the SFXOldHashmap class can save multiple elements into one hashmap table entry, you can specify a number bigger than 100 as threshold value(default value is 80). Specifying threshold value bigger than 100, you can save scarce memory of mobile phone.

Reference

SFXLinkedHashMap | SFXFlatHashMap | Hashmap

Member

Constructor/Destructor
SFXOldHashmap( `Void` ) Constructor of the SFXOldHashmap class.
SFXOldHashmap( `UInt16` threshold , `UInt16` ratio ) Constructor of the SFXOldHashmap class.

Public Functions
`Void`	Clear( `Void` ) Clear the hashmap.
`Bool`	ContainsKey( `KeyType` key ) Check whether or not this hashmap contains the specified key as the key of the pair element.
`Bool`	ContainsValue( `ValueType` value ) Check whether or not this hashmap contains the specified value as the value of the pair element.
static `SFXOldHashmap< K, V > const &`	EmptyInstance( `Void` ) Get the empty hashmap.
`Bool`	Equals( `SFXOldHashmap< K, V > const &` collection ) Check whether or not this hashmap equals the specified hashmap.
`ValueType`	Get( `KeyType` key ) Get the value of the key-value pair with the specified key from this hashmap.
`KeyEnumerator`	GetKeyEnumerator( `Void` ) Get the key enumerator of this hashmap.
`KeyIterator`	GetKeyIterator( `Void` ) Get the key iterator of this hashmap.
`UInt16`	GetRatio( `Void` ) [INVALID] Get the expansion ratio of the hash table size.
`SInt32`	GetSize( `Void` ) Get the size of this hashmap.
`UInt16`	GetThreshold( `Void` ) Get the threshold to expand the hash table size.
`ValueEnumerator`	GetValueEnumerator( `Void` ) Get the value enumerator of this hashmap.
`ValueIterator`	GetValueIterator( `Void` ) Get the value iterator of this hashmap.
`Bool`	IsEmpty( `Void` ) Check whether or not this hashmap is empty.
`SFCError`	Merge( `SFXOldHashmap< K, V > const &` collection ) Merge this hashmap with the specified hashmap.
`Void`	Remove( `KeyType` key ) Remove the key-value pair with the specified key from this hashmap.
`SFCError`	Set( `SFXOldHashmap< K, V > const &` collection ) Set the specified key-value pair or hashmap into this hashmap.
`SFCError`	Set( `KeyType` key , `ValueType` value ) Set the specified key-value pair or hashmap into this hashmap.
`Void`	SetRatio( `UInt16` ratio ) [INVALID] Set the expansion ratio of the hash table size.
`Void`	SetThreshold( `UInt16` threshold ) Set the threshold to expand the hash table size.
`ValueType`	operator[]( `KeyType` key ) Get the value of the key-value pair with the specified key index from this hashmap.

Types
DefaultEnum Default values of threshold and ratio to expand the hash table.
KeyEnumerator Class for managing the key enumerator for the keys of the pair elements of this hashmap.
KeyIterator Class for managing the key iterator for the keys of the pair elements of this hashmap.
ValueEnumerator Class for managing the value enumerator for the values of the pair elements of this hashmap.
ValueIterator Class for managing the value iterator for the values of the pair elements of this hashmap.

SFXOldHashmap::SFXOldHashmap

Constructor of the SFXOldHashmap class.

[ public, explicit ]
SFXOldHashmap(Void);

[ public, explicit ]
SFXOldHashmap(
    UInt16 threshold   // threshold value that expands the hash table
    UInt16 ratio       // expansion ration of the hash table
);

SFXOldHashmap::Clear

Clear the hashmap.

[ public ]
Void Clear(Void);

Description

This function clears this hashmap. All the internal buffer allocated to this hashmap will be released.

After this function is executed, the size of this hashmap will become 0.

If the key is a string(SFXAnsiString / SFXWideString), the string itself will be released automatically.

	Caution
If the type of the key or the value of the pair element is a pointer to a class instance or data bigger than 4 bytes, memory area that the pointer points to will not be released automatically. Before clearing this hashmap, it is necessary to release that area explicitly using the delete statement. Otherwise, memory leakage will occur.

Caution

If the type of the key or the value of the pair element is a pointer to a class instance or data bigger than 4 bytes, memory area that the pointer points to will not be released automatically.

Before clearing this hashmap, it is necessary to release that area explicitly using the delete statement. Otherwise, memory leakage will occur.

	Note
	This function will be called automatically when this hashmap goes out of scope.

Example

SFXOldHashmap<SFXAnsiString, SInt32> strmap;
 
...

strmap.Clear();   // clear the hashmap

Reference

SFXOldHashmap::Remove | SFXOldHashmap::GetSize

SFXOldHashmap::ContainsKey

Check whether or not this hashmap contains the specified key as the key of the pair element.

[ public, const ]
Bool ContainsKey(
    KeyType key   // key to check
);

Return value

If the specified key is contained: true
Otherwise: false

Description

This function checks whether or not this hashmap contains the specified key as the key of the pair element.

	Note
	If the type of the element is a pointer to a class instance or data bigger than 4 bytes, their addresses will be compared with.

Example

SFXOldHashmap<SFXAnsiString, SInt32> strmap;

// set a key-value pair element of (key: "mike", value: 2) into hashmap
if (strmap.Set("mike", 2) == SFERR_NO_ERROR) {

    // set a key-value pair element of (key: "john", value: 1) into hashmap
    if (strmap.Set("john", 1) == SFERR_NO_ERROR) {
    
        // check whether the key element is contained or not
        TRACE("ContainsKey(\"mike\") = %s", (strmap.ContainsKey("mike")) ? ("true") : ("false"));  // containsKey("mike") = true
        TRACE("ContainsKey(\"tom\") = %s", (strmap.ContainsKey("tom")) ? ("true") : ("false"));    // containsKey("tom") = false
    }
}

Reference

SFXOldHashmap::ContainsValue

SFXOldHashmap::ContainsValue

Check whether or not this hashmap contains the specified value as the value of the pair element.

[ public, const ]
Bool ContainsValue(
    ValueType value   // value to check
);

Return value

If the specified value is contained: true
Otherwise: false

Description

This function checks whether or not this hashmap contains the specified value as the value of the pair element.

	Note
	If the type of the element is a pointer to a class instance or data bigger than 4 bytes, their addresses will be compared with.

Example

SFXOldHashmap<SFXAnsiString, SInt32> strmap;

// set a key-value pair element of (key: "mike", value: 2) into the hashmap
if (strmap.Set("mike", 2) == SFERR_NO_ERROR) {

    // set a key-value pair element of (key: "john", value: 1) into the hashmap
    if (strmap.Set("john", 1) == SFERR_NO_ERROR) {
    
        // check whether the value element is contained or not
        TRACE("ContainsValue(2) = %s", (strmap.ContainsValue(2)) ? ("true") : ("false"));  // containsValue(2) = true
        TRACE("ContainsValue(5) = %s", (strmap.ContainsValue(5)) ? ("true") : ("false"));  // containsValue(5) = false
    }
}

Reference

SFXOldHashmap::ContainsKey

SFXOldHashmap::EmptyInstance

Get the empty hashmap.

[ public, static ]
SFXOldHashmap< K, V > const & EmptyInstance(Void);

Return value

Empty hashmap

Description

This function gets the empty hashmap.

Reference

SFXOldHashmap::IsEmpty

SFXOldHashmap::Equals

Check whether or not this hashmap equals the specified hashmap.

[ public, const ]
Bool Equals(
    SFXOldHashmap< K, V > const & collection   // hashmap to compare with
);

Return value

If yes: true
Otherwise: false

Description

This function checks whether or not this hashmap equals the specified hashmap.

	Note
	If the type of the element is a pointer, its address will be compared with.

SFXOldHashmap::Get

Get the value of the key-value pair with the specified key from this hashmap.

[ public, const ]
ValueType Get(
    KeyType key   // key to get the value element
);

-->

Return value

If there is the key-value pair with the specified key in this hashmap, the corresponding value will be returned.

Otherwise, null or 0 will be returned.

Description

This function gets the value of the key-value pair with the specified key from this hashmap.

	Caution
	In case no key-value pair with the specified key exists, no error will occur but this function will return 0 or null.

Example

SFXOldHashmap<SFXAnsiString, SInt32> strmap;

// set a key-value pair element of (key: "mike", value: 2) into the hashmap
if (strmap.Set("mike", 2) == SFERR_NO_ERROR) {

    // set a key-value pair element of (key: "john", value: 1) into the hashmap
    if (strmap.Set("john", 1) == SFERR_NO_ERROR) {
    
        // get the value element to match the specified key
        TRACE("%d", strmap.Get("mike"));  // 2
    }
}

Reference

SFXOldHashmap::operator[] | SFXOldHashmap::Set

SFXOldHashmap::GetKeyEnumerator

Get the key enumerator of this hashmap.

[ public, const ]
KeyEnumerator GetKeyEnumerator(Void);

Return value

Key enumerator of this hashmap.

Description

This function gets the key enumerator of this hashmap.

Reference

SFXOldHashmap::GetKeyIterator

Get the key iterator of this hashmap.

[ public ]
KeyIterator GetKeyIterator(Void);

Return value

Key iterator of this hashmap.

Description

This function gets the key iterator of this hashmap.

Reference

SFXOldHashmap::GetRatio

[INVALID] Get the expansion ratio of the hash table size.

[ public, const ]
UInt16 GetRatio(Void);

Reference

SFXOldHashmap::SetRatio

SFXOldHashmap::GetSize

Get the size of this hashmap.

[ public, const ]
SInt32 GetSize(Void);

Return value

Size of this hashmap

Description

This function gets the size of this hashmap(i.e., the number of the key-value pair elements of this hashmap).

SFXOldHashmap::GetThreshold

Get the threshold to expand the hash table size.

[ public, const ]
UInt16 GetThreshold(Void);

Reference

SFXOldHashmap::SetThreshold

SFXOldHashmap::GetValueEnumerator

Get the value enumerator of this hashmap.

[ public, const ]
ValueEnumerator GetValueEnumerator(Void);

Return value

Value enumerator of this hashmap.

Description

This function gets the value enumerator of this hashmap.

Reference

SFXOldHashmap::GetValueIterator

Get the value iterator of this hashmap.

[ public ]
ValueIterator GetValueIterator(Void);

Return value

Value iterator of this hashmap.

Description

This function gets the value iterator of this hashmap.

Reference

SFXOldHashmap::IsEmpty

Check whether or not this hashmap is empty.

[ public, const ]
Bool IsEmpty(Void);

Return value

If yes: true
Otherwise: false

Description

This function checks whether or not this hashmap is empty.

Reference

SFXOldHashmap::EmptyInstance

SFXOldHashmap::Merge

Merge this hashmap with the specified hashmap.

[ public ]
SFCError Merge(
    SFXOldHashmap< K, V > const & collection   // hashmap to merge
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function merges this hashmap with the specified this hashmap.

* In case an error occurs during processing, this hashmap will be restored.

SFXOldHashmap::Remove

Remove the key-value pair with the specified key from this hashmap.

[ public ]
Void Remove(
    KeyType key   // key to remove
);

Description

This function removes the key-value pair with the specified key from this hashmap.

If the key is of the SFXAnsiString / SFXWideString type, the string as the key will be released automatically.

	Caution
If the key or the value is a pointer to a class instance or data bigger than 4 bytes, data the pointer points to will not be released automatically. These data need to be released explicitly using the delete statement. Otherwise, memory leakage will occur.

Caution

If the key or the value is a pointer to a class instance or data bigger than 4 bytes, data the pointer points to will not be released automatically.

These data need to be released explicitly using the delete statement. Otherwise, memory leakage will occur.

Reference

SFXOldHashmap::Set | SFXOldHashmap::Clear

SFXOldHashmap::Set

Set the specified key-value pair or hashmap into this hashmap.

[ public ]
SFCError Set(
    SFXOldHashmap< K, V > const & collection   // hashmap to set
);

[ public ]
SFCError Set(
    KeyType key       // key to set
    ValueType value   // value to set
);

-->

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY
If the key is the null string: SFERR_INVALID_PARAM

Description

This function sets the specified key-value pair or hashmap into this hashmap.

* In case an error occurs during processing, this hashmap will be restored.

	Null string
	The null string is the return value of the `SFXAnsiString::EmptyInstance` / `SFXWideString::EmptyInstance` function.

Example

SFXOldHashmap<SFXAnsiString, SInt32> strmap;

// set a key-value pair element of (key: "mike", value: 2) into the hashmap
if (strmap.Set("mike", 2) == SFERR_NO_ERROR) {

    // set a key-value pair element of (key: "john", value: 1) into the hashmap
    if (strmap.Set("john", 1) == SFERR_NO_ERROR) {
    
        // check whether the key element is contained or not
        TRACE("ContainsKey(\"mike\") = %s", (strmap.ContainsKey("mike")) ? ("true") : ("false"));  // containsKey("mike") = true
        TRACE("ContainsKey(\"tom\") = %s", (strmap.ContainsKey("tom")) ? ("true") : ("false"));    // containsKey("tom") = false
    }
}

Reference

SFXOldHashmap::Get | SFXOldHashmap::operator[] | SFXAnsiString::EmptyInstance | SFXWideString::EmptyInstance

SFXOldHashmap::SetRatio

[INVALID] Set the expansion ratio of the hash table size.

[ public ]
Void SetRatio(
    UInt16 ratio   // expansion ratio to set (%)
);

Description

The specification of this function is changed. The size of the hash table will automatically expand by an appropriate prime number when the number of the elements exceeds the threshold set with the SFXOldHashmap::SetThreshold function.

Reference

SFXOldHashmap::GetRatio

SFXOldHashmap::SetThreshold

Set the threshold to expand the hash table size.

[ public ]
Void SetThreshold(
    UInt16 threshold   // threshold ratio to set (%)
);

Description

The hash table size is expanded for efficiency when the number of key elements increases.

The hash table size is automatically expanded when the following condition is satisfied.

(the number of the elements) > (hash table size) * threshold / 100

Default: 80

	Value of Threshold
Since one table entry has multiple elements in SFXOldHashmap when the keys of the hash table collide, SFXOldHashmap can hold more elements than the hash table size. Therefore the threshold set with the SFXOldHashmap::SetThreshold function may be bigger than 100.

Value of Threshold

Since one table entry has multiple elements in SFXOldHashmap when the keys of the hash table collide, SFXOldHashmap can hold more elements than the hash table size.

Therefore the threshold set with the SFXOldHashmap::SetThreshold function may be bigger than 100.

Reference

SFXOldHashmap::GetThreshold

SFXOldHashmap::operator[]

Get the value of the key-value pair with the specified key index from this hashmap.

[ public, const ]
ValueType operator[](
    KeyType key   // index of the element to get
);

Return value

If there is the key-value pair with the specified key index in this hashmap, the corresponding value will be returned.

Otherwise, null or 0 will be returned.

Description

This operator gets the value of the key-value pair with the specified key from this hashmap.

	Caution
	In case no key-value pair with the specified key exists, no error will occur but this operator will return 0 or null.

Reference

SFXOldHashmap::Set

SFXOldHashmap::DefaultEnum

Default values of threshold and ratio to expand the hash table.

enum DefaultEnum {
    DEFAULT_THRESHOLD = 80,     // default value of threshold to expand the hash table
    DEFAULT_RATIO     = 50      // default value of ratio to expand the hash table
};

Reference

SFXOldHashmap::SetThreshold | SFXOldHashmap::GetThreshold | SFXOldHashmap::SetRatio | SFXOldHashmap::GetRatio

SFXOldHashmap::KeyEnumerator

Class for managing the key enumerator for the keys of the pair elements of this hashmap.

[ public ]

SFMTYPEDEFCLASS(KeyEnumerator)
class KeyEnumerator {
    public:
        explicit            KeyEnumerator           (Void);
                            KeyEnumerator           (KeyIteratorConstRef iterator);
        KeyEnumeratorRef    operator=               (KeyIteratorConstRef iterator);
        KeyType             GetNext                 (Void);
        KeyType             GetPrevious             (Void);
        ValueType           GetValue                (Void) const;
        Bool                HasNext                 (Void) const;
        Bool                HasPrevious             (Void) const;
        Bool                IsValid                 (Void) const;
};

Description

This class is for managing the key enumerator for the keys of the pair elements of this hashmap.

This class has the following member functions.

GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the enumerator is valid.

Reference

SFXOldHashmap::KeyIterator

Class for managing the key iterator for the keys of the pair elements of this hashmap.

[ public ]

SFMTYPEDEFCLASS(KeyIterator)
class KeyIterator  {
    public:
        explicit            KeyIterator             (Void);
        KeyType             GetNext                 (Void);
        KeyType             GetPrevious             (Void);
        ValueType           GetValue                (Void) const;
        Bool                HasNext                 (Void) const;
        Bool                HasPrevious             (Void) const;
        Bool                IsValid                 (Void) const;
        Void                Remove                  (Void);
};

Description

This class is for managing the key iterator for the keys of the pair elements of this hashmap.

This class has the following member functions.

GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
GetValue	Get the value element of current iterator. If invalid, return null.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the iterator is valid.
Remove	Remove the element of current iterator.

Reference

SFXOldHashmap::ValueEnumerator

Class for managing the value enumerator for the values of the pair elements of this hashmap.

[ public ]

SFMTYPEDEFCLASS(ValueEnumerator)
class ValueEnumerator  {
    public:
        explicit            ValueEnumerator         (Void);
                            ValueEnumerator         (ValueIteratorConstRef iterator);
        ValueEnumeratorRef  operator=               (ValueIteratorConstRef iterator);
        ValueType           GetNext                 (Void);
        ValueType           GetPrevious             (Void);
        KeyType             GetKey                  (Void) const;
        Bool                HasNext                 (Void) const;
        Bool                HasPrevious             (Void) const;
        Bool                IsValid                 (Void) const;
};

Description

This class is for managing the value enumerator for the values of the pair elements of this hashmap.

This class has the following member functions.

GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the enumerator is valid.

Reference

SFXOldHashmap::ValueIterator

Class for managing the value iterator for the values of the pair elements of this hashmap.

[ public ]

SFMTYPEDEFCLASS(ValueIterator)
class ValueIterator  {
    public:
        explicit            ValueIterator           (Void);
 SFCError     Set                     (ValueType value);
        ValueType           GetNext                 (Void);
        ValueType           GetPrevious             (Void);
        KeyType             GetKey                  (Void) const;
        Bool                HasNext                 (Void) const;
        Bool                HasPrevious             (Void) const;
        Bool                IsValid                 (Void) const;
        Void                Remove                  (Void);
};

Description

This class is for managing the value iterator for the values of the pair elements of this hashmap.

This class has the following member functions.

Set	Set a value to the value element of current iterator.
GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
GetKey	Get the key element of current iterator. If invalid, return null.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the iterator is valid.
Remove	Remove the element of current iterator.

Reference