ezEngine  Milestone 7
ezHashedString Class Reference

This class is optimized to take nearly no memory (sizeof(void*)) and to allow very fast checks whether two strings are identical. More...

#include <HashedString.h>

Classes

struct  HashedData
 

Public Types

typedef ezMap< ezString,
HashedData
StringStorage
 
typedef StringStorage::Iterator HashedType
 

Public Member Functions

 ezHashedString ()
 Initializes this string to the empty string.
 
 ezHashedString (const ezHashedString &rhs)
 Copies the given ezHashedString.
 
 ~ezHashedString ()
 Releases the reference to the internal data. Does NOT deallocate any data, even if this held the last reference to some string.
 
void operator= (const ezHashedString &rhs)
 Copies the given ezHashedString.
 
template<size_t N>
void Assign (const char(&szString)[N])
 Assigning a new string from a string constant is a slow operation, but the hash computation can happen at compile time. More...
 
void Assign (ezHashing::StringWrapper szString)
 Assigning a new string from a non-hashed string is a very slow operation, this should be used rarely. More...
 
bool operator== (const ezHashedString &rhs) const
 Comparing whether two hashed strings are identical is just a pointer comparison. This operation is what ezHashedString is optimized for. More...
 
bool operator!= (const ezHashedString &rhs) const
 
bool operator== (const ezTempHashedString &rhs) const
 Compares this string object to an ezTempHashedString object. This should be used whenever some object needs to be found and the string to compare against is not yet an ezHashedString object.
 
bool operator!= (const ezTempHashedString &rhs) const
 
bool operator< (const ezHashedString &rhs) const
 This operator allows sorting objects by hash value, not by alphabetical order.
 
bool operator< (const ezTempHashedString &rhs) const
 This operator allows sorting objects by hash value, not by alphabetical order.
 
const ezStringGetString () const
 Gives access to the actual string data, so you can do all the typical (read-only) string operations on it.
 
const char * GetData () const
 Gives access to the actual string data, so you can do all the typical (read-only) string operations on it.
 
ezUInt32 GetHash () const
 Returns the hash of the stored string.
 
 operator ezStringView () const
 Returns a string view to this string's data.
 
 operator const char * () const
 Returns a pointer to the internal Utf8 string.
 
template<size_t N>
EZ_FORCE_INLINE void Assign (const char(&szString)[N])
 

Static Public Member Functions

static ezUInt32 ClearUnusedStrings ()
 This will remove all hashed strings from the central storage, that are not referenced anymore. More...
 

Static Private Member Functions

static void InitHashedString ()
 
static HashedType AddHashedString (const char *szString, ezUInt32 uiHash)
 

Private Attributes

HashedType m_Data
 

Detailed Description

This class is optimized to take nearly no memory (sizeof(void*)) and to allow very fast checks whether two strings are identical.

Internally only a reference to the string data is stored. The data itself is stored in a central location, where no duplicates are possible. Thus two identical strings will result in identical ezHashedString objects, which makes equality comparisons very easy (it's a pointer comparison).
Copying ezHashedString objects around and assigning between them is very fast as well.

Assigning from some other string type is rather slow though, as it requires thread synchronization.
You can also get access to the actual string data via GetString().

You should use ezHashedString whenever the size of the encapsulating object is important and when changes to the string itself are rare, but checks for equality might be frequent (e.g. in a system where objects are identified via their name).
At runtime when you need to compare ezHashedString objects with some temporary string object, used ezTempHashedString, as it will only use the string's hash value for comparison, but will not store the actual string anywhere.


Class Documentation

struct ezHashedString::HashedData
Class Members
ezAtomicInteger32 m_iRefCount
ezUInt32 m_uiHash

Member Function Documentation

template<size_t N>
void ezHashedString::Assign ( const char(&)  szString[N])

Assigning a new string from a string constant is a slow operation, but the hash computation can happen at compile time.

If you need to create an object to compare ezHashedString objects against, prefer to use ezTempHashedString. It will only compute the strings hash value, but does not require any thread synchronization.

EZ_FORCE_INLINE void ezHashedString::Assign ( ezHashing::StringWrapper  szString)

Assigning a new string from a non-hashed string is a very slow operation, this should be used rarely.

If you need to create an object to compare ezHashedString objects against, prefer to use ezTempHashedString. It will only compute the strings hash value, but does not require any thread synchronization.

ezUInt32 ezHashedString::ClearUnusedStrings ( )
static

This will remove all hashed strings from the central storage, that are not referenced anymore.

All hashed string values are stored in a central location and ezHashedString just references them. Those strings are then reference counted. Once some string is not referenced anymore, its ref count reaches zero, but it will not be removed from the storage, as it might be reused later again. This function will clean up all unused strings. It should typically not be necessary to call this function at all, unless lots of strings get stored in ezHashedString that are not really used throughout the applications life time.

Returns the number of unused strings that were removed.

bool ezHashedString::operator!= ( const ezHashedString rhs) const
inline
See Also
operator==
bool ezHashedString::operator!= ( const ezTempHashedString rhs) const
inline
See Also
operator==
bool ezHashedString::operator== ( const ezHashedString rhs) const
inline

Comparing whether two hashed strings are identical is just a pointer comparison. This operation is what ezHashedString is optimized for.

Note
Comparing between ezHashedString objects is always error-free, so even if two string had the same hash value, although they are different, this comparison function will not report they are the same.

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