OGRE  2.0
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Ogre::IdString Struct Reference

Hashed string. More...

#include <OgreIdString.h>

Public Member Functions

 IdString ()
 
 IdString (const char *string)
 
 IdString (const std::string &string)
 
 IdString (uint32 value)
 
std::string getFriendlyText () const
 Returns "[Hash 0x0a0100ef]" strings in Release mode, readable string in debug. More...
 
std::string getReleaseText () const
 Always returns "[Hash 0x0a0100ef]" strings in any mode. More...
 
void OGRE_APPEND_DEBUG_STRING (const char *string)
 
void OGRE_COPY_DEBUG_STRING (const char *string)
 
void OGRE_COPY_DEBUG_STRING (const std::string &string)
 
void OGRE_COPY_DEBUG_STRING (uint32 value)
 
bool operator!= (IdString idString) const
 
IdString operator+ (IdString idString) const
 
void operator+= (IdString idString)
 
bool operator< (IdString idString) const
 
bool operator== (IdString idString) const
 

Public Attributes

char mDebugString [OGRE_DEBUG_STR_SIZE]
 
uint32 mHash
 

Static Public Attributes

static const uint32_t Seed = 0x3A8EFA67
 

Detailed Description

Hashed string.

An IdString is meant to be passed by value rather than by reference since in Release mode it's just an encapsulated integer. The default implementation uses a 32-bit uint. A hash = 0 is the default initialization, and assumed by Ogre to mean an IdString is empty or unspecified.

Note that IdString("") != IdString(0) != IdString() The latter indicates mHash == 0 (the default initialization). While the first one will hash the empty string "", and the second will attempt to hash the number 0, producing up to three possible outputs.
IdStrings convert regular String to hashes AND ARE DESTRUCTIVE. This means that you may no longer recover the real string it was constructed from. When the original data is not available getFriendlyText returns [Hash 0x0a0100ef] (in the example that mHash = 0x0a0100ef)* In non-release modes (NDEBUG is not defined), IdStrings try to maintain a copy of the original string for two purposes:
  1. Easy debugging: Reading "Texture/diffuse.png" is much nicer than "0x0a0100ef"
  2. Hash collision: If Ogre finds two IdStrings are identical but their original strings are not, an assertion will trigger indicating a collision has been found. Note that this isn't foolproof. Note: When IdString( uint32 ) was used to hash an integer, getFriendlyText will return "[Value 0x1234567]"
IdStrings can be concatenated: IdString( "Hello." ) + IdString( " How are you?" ) produc a new IdString, but please note that it may not be the same as doing IdString( "Hello. How are you?" ) depending on the hashing function used (by default, we use MurmurHash3,
See also
OGRE_HASH_FUNC)
Remarks
Hash collision detection isn't foolproof because we keep a fixed string copy of the original string. If the original string is too long, it will be truncated and there is an extremely low possibility that their truncation becomes the same string, and their hashes also become equal, when the original strings were not. i.e. VeryLooooooong/String and UltraaaaaLoong/String could both become "/String" and happen to also hash to the same number.
In practice we truncate to 32 bytes. If your fear this is too little for you and also fear about collisions, increase
Author
Matias N. Goldberg
Version
1.0

Definition at line 94 of file OgreIdString.h.

Constructor & Destructor Documentation

Ogre::IdString::IdString ( )
inline

Definition at line 104 of file OgreIdString.h.

References mDebugString.

Ogre::IdString::IdString ( const char *  string)
inline

Definition at line 111 of file OgreIdString.h.

References mHash, OGRE_COPY_DEBUG_STRING(), OGRE_HASH_FUNC, and Seed.

Ogre::IdString::IdString ( const std::string &  string)
inline

Definition at line 117 of file OgreIdString.h.

References mHash, OGRE_COPY_DEBUG_STRING(), OGRE_HASH_FUNC, and Seed.

Ogre::IdString::IdString ( uint32  value)
inline

Definition at line 123 of file OgreIdString.h.

References mHash, OGRE_COPY_DEBUG_STRING(), OGRE_HASH_FUNC, and Seed.

Member Function Documentation

std::string Ogre::IdString::getFriendlyText ( ) const
inline

Returns "[Hash 0x0a0100ef]" strings in Release mode, readable string in debug.

Definition at line 256 of file OgreIdString.h.

References mDebugString, mHash, and OGRE_HASH_BITS.

std::string Ogre::IdString::getReleaseText ( ) const
inline

Always returns "[Hash 0x0a0100ef]" strings in any mode.

Definition at line 278 of file OgreIdString.h.

References mHash, and OGRE_HASH_BITS.

void Ogre::IdString::OGRE_APPEND_DEBUG_STRING ( const char *  string)
inline

Definition at line 173 of file OgreIdString.h.

References mDebugString, and OGRE_DEBUG_STR_SIZE.

Referenced by operator+=().

void Ogre::IdString::OGRE_COPY_DEBUG_STRING ( const char *  string)
inline

Definition at line 135 of file OgreIdString.h.

References mDebugString, and OGRE_DEBUG_STR_SIZE.

Referenced by IdString().

void Ogre::IdString::OGRE_COPY_DEBUG_STRING ( const std::string &  string)
inline

Definition at line 151 of file OgreIdString.h.

References mDebugString, and OGRE_DEBUG_STR_SIZE.

void Ogre::IdString::OGRE_COPY_DEBUG_STRING ( uint32  value)
inline

Definition at line 167 of file OgreIdString.h.

References mDebugString, and OGRE_DEBUG_STR_SIZE.

bool Ogre::IdString::operator!= ( IdString  idString) const
inline

Definition at line 245 of file OgreIdString.h.

References mDebugString, and mHash.

IdString Ogre::IdString::operator+ ( IdString  idString) const
inline

Definition at line 217 of file OgreIdString.h.

void Ogre::IdString::operator+= ( IdString  idString)
inline

Definition at line 207 of file OgreIdString.h.

References mDebugString, mHash, OGRE_APPEND_DEBUG_STRING(), OGRE_HASH_FUNC, and Seed.

bool Ogre::IdString::operator< ( IdString  idString) const
inline

Definition at line 224 of file OgreIdString.h.

References mDebugString, and mHash.

bool Ogre::IdString::operator== ( IdString  idString) const
inline

Definition at line 235 of file OgreIdString.h.

References mDebugString, and mHash.

Member Data Documentation

uint32 Ogre::IdString::mHash
const uint32_t Ogre::IdString::Seed = 0x3A8EFA67
static

Definition at line 96 of file OgreIdString.h.

Referenced by IdString(), and operator+=().


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