SFXFlatHashMap

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

#include <SFXFlatHashMap.h.hpp>

class SFXFlatHashMap;

SFMTYPEDEFCLASS(SFXFlatHashMap)

Inheritance diagram

Collaboration diagram

Description

SFXFlatHashMap is a hashmap class whose key elements are unorderd.

Each key element of the SFXFlatHashMap 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 the class instance as the value element of the SFXFlatHashMap instance(hashmap), a pointer should be used.

Speed performance of Set/Remove/Clear is superior than those of SFXLinkedHashMap and SFXOldHashmap, because all elements instances are allocated into one hash table in advance. However, if the key is SFXAnsiString class or SFXWideString class, other heaps for string will be allocated by elements.

If the element occupancy rate for the hash table exceeds DEFAULT_THRESHOLD (45) %, the size of the hash table will be automatically expanded.

// data more than 4 byte or class instance cannot be a value element of the SFXFlatHashMap instance ( hashmap )
// SFXFlatHashMap<SFXAnsiString, SInt64> map64;          NG
// SFXFlatHashMap<SFXAnsiString, SFXAnsiString> mapstr;  NG

// but a pointer to the data more than 4 byte or class instance can be a value element of the SFXFlatHashMap instance ( hashmap )
SFXFlatHashMap<SFXAnsiString, SInt64Ptr> map64;             // OK
SFXFlatHashMap<<SFXAnsiString, SFXAnsiStringPtr> mapstr; // OK

Reference

SFXLinkedHashMap | SFXHashmap | SFXAnsiString | SFXWideString | Hashmap

Member

Constructor/Destructor
SFXFlatHashMap( `Void` ) Constructor of the SFXFlatHashMap class.

Public Functions
`Void`	Clear( `Void` ) Clear this 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 `SFXFlatHashMap< K, V > const &`	EmptyInstance( `Void` ) Get the empty hashmap.
`Bool`	Equals( `SFXFlatHashMap< K, V > const &` collection ) Check whether or not this hashmap equals the specified hashmap.
`ValueType`	Get( `KeyType` key , `BoolPtr` found = null ) 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.
`SInt32`	GetSize( `Void` ) Get the size of this hashmap.
`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( `SFXFlatHashMap< 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( `SFXFlatHashMap< 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.
`SFCError`	Swap( `KeyType` destination , `KeyType` source ) Swap the value of two pair elements with the specified keys.
`ValueType`	operator[]( `KeyType` key ) Get the value of the key-value pair with the specified key index from this hashmap.

Types
DefaultEnum Default value of threshold 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.

SFXFlatHashMap::SFXFlatHashMap

Constructor of the SFXFlatHashMap class.

[ public, explicit ]
SFXFlatHashMap(Void);

SFXFlatHashMap::Clear

Clear this 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

SFXFlatHashMap<SFXAnsiString, SInt32> strmap;
 
...

strmap.Clear();   // clear the hashmap

Reference

SFXFlatHashMap::Remove | SFXFlatHashMap::GetSize

SFXFlatHashMap::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

SFXFlatHashMap<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 or not the hashmap contains the keys below
        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

SFXFlatHashMap::ContainsValue

SFXFlatHashMap::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

SFXFlatHashMap<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 or not the hashmap contains the values below
        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

SFXFlatHashMap::ContainsKey

SFXFlatHashMap::EmptyInstance

Get the empty hashmap.

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

Return value

Empty hashmap

Description

This function gets the empty hashmap.

Reference

SFXFlatHashMap::IsEmpty

SFXFlatHashMap::Equals

Check whether or not this hashmap equals the specified hashmap.

[ public, const ]
Bool Equals(
    SFXFlatHashMap< 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.

SFXFlatHashMap::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
    BoolPtr found = null   // whether the key exists (optional)
);

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.

When a key-value pair with the specified key exists, the second parameter "found" is set to true. Otherwise, false.

	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

SFXFlatHashMap<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) {
    
        // display the value of the key-value pair with the specified key in BREW Output Window
        TRACE("%d", strmap.Get("mike"));  // 2
    }
}

Reference

SFXFlatHashMap::operator[] | SFXFlatHashMap::Set

SFXFlatHashMap::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

SFXFlatHashMap::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

SFXFlatHashMap::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).

SFXFlatHashMap::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

SFXFlatHashMap::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

SFXFlatHashMap::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.

SFXFlatHashMap::Merge

Merge this hashmap with the specified hashmap.

[ public ]
SFCError Merge(
    SFXFlatHashMap< 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.

SFXFlatHashMap::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

SFXFlatHashMap::Set | SFXFlatHashMap::Clear

SFXFlatHashMap::Set

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

[ public ]
SFCError Set(
    SFXFlatHashMap< 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

SFXFlatHashMap<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 or not this hashmap contains the key-value pair with the specified key
        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

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

SFXFlatHashMap::Swap

Swap the value of two pair elements with the specified keys.

[ public ]
SFCError Swap(
    KeyType destination   // destination key
    KeyType source        // source key
);

Return value

If succeeds: SFERR_NO_ERROR
If no pair element with the specified key exists: SFERR_INVALID_PARAM

Description

This function swaps the value of two pair elements with the specified keys.

Example

SFXFlatHashMap<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) {

        // swap the values of two pair elements
        if (strmap.Swap("mike", "john") == SFERR_NO_ERROR) {

            // display the value of the pair element with "mike" as the key on BREW Output Window
            TRACE("%d", strmap.Get("mike"));  // 1
        }
    }
}

SFXFlatHashMap::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

SFXFlatHashMap::Get | SFXFlatHashMap::Set

SFXFlatHashMap::DefaultEnum

Default value of threshold to expand the hash table.

enum DefaultEnum {
    DEFAULT_THRESHOLD = 45     // default value of threshold to expand the hash table
};

SFXFlatHashMap::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

SFXFlatHashMap::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);
 SFCError     SetValue                (ValueType type);
        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 iterator for the keys of the pair elements of this hashmap.

This class has the following member functions.

SetValue	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.
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.

Reference

SFXFlatHashMap::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

SFXFlatHashMap::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;
};

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.

Reference