StringId Class Reference
[Core]

Lightweight type for storing strings for use as ID's. More...

List of all members.

Public Member Functions
	StringId ()
	StringId (const char *idString)
const char *	GetString () const
unsigned int	GetHash () const
	StringId (const StringId &stringId)
const StringId &	operator= (const StringId &stringId)
bool	operator== (const StringId &stringId) const
bool	operator!= (const StringId &stringId) const

---

Detailed Description

Lightweight type for storing strings for use as ID's.

Author:

Mattias Gustavsson

The StringId type is perfect for when you need to identify something by name. When you create a StringId type from a c-style zero-terminated string (const char*), it will calculate a hash-number from all the characters, and use the resulting value as an index into a global array of string id data. This array entry typically holds just the string we're looking for (or is empty in case this is the first time a StringId is requested for that particular string), but sometimes it can hold a list of just a few strings that happen to have the same hash-number. Once the corresonding string have been found (or inserted, if this is its first use) in the table, it is stored in the StringId type.

This initial string matching process involves looping through each character of the string, and (worst case) a handful of string compares), which isn't exactly crazy expensive, but certainly not free, either. All other operations you perform on a StringId is extremely cheap though. Since the string pointer (const char*) stored inside the StringId type is from the shared string id table, we can compare two StringId values by simply comparing two pointers. And we can copy a StringId by simply copying its internal pointer - no extra lookup needed.

So we trade a little bit of overhead at creation (looping through the string once and maybe doing a couple of string compares) for almost free copying and comparison when using it. If you just make sure not to unnecessarily create StringId's, you won't ever find them slowing things down.

There's also a couple of macros, strSwitch and strCase, which you can use to emulate the behaviour of the c-language statements "switch" and "case", to make it more easy to do a bunch of comparisons for a single StringId. The strCase macro is written such that it automatically initializes the specified StringId once on the first time it is run, meaning it will always just do a pointer compare on subsequent runs.

Definition at line 46 of file StringId.h.

---

Constructor & Destructor Documentation

StringId::StringId

(

)

Default constructor. Will initialize the internal string to 0, without doing any lookups. This is a fast operation.

Definition at line 8 of file StringId.cpp.

StringId::StringId

(

const char *

idString

)

Constructor. Looks up the specified string in the shared string table, and calculates the hash value for the string. If it is the empty string (""), the StringId will use a string pointer of 0 instead. This is so that both empty strings and null-strings is treated like the same ID, which is more useful.

Parameters:

idString

The string to use for identifier

Definition at line 17 of file StringId.cpp.

StringId::StringId

(

const StringId &

stringId

)

Copy constructor. Just duplicates the internally stored hash value and string pointer, without doing any lookups.

Parameters:

stringId

StringId to copy

Definition at line 52 of file StringId.cpp.

---

Member Function Documentation

const char * StringId::GetString

(

)

const

Used to retrieve the original, c-style string (const char*) for this StringId.

Returns:

The zero-terminated string for this id

Definition at line 36 of file StringId.cpp.

unsigned int StringId::GetHash

(

)

const

Retrieve the hash-number calculated for the string. This number is primarily for internal use, but can also be useful if you want to store StringId's in your own hash-table, as you could reuse this stored hash-number instead of having to recalculate it yourself. The number is calculated in such a way as to avoid collisions, but collisions WILL happen anyway, so must be dealt with

Returns:

The hash-number for the string

Definition at line 44 of file StringId.cpp.

const StringId & StringId::operator=

(

const StringId &

stringId

)

Assignment operator. Just duplicates the internally stored hash value and string pointer, without doing any lookups.

Parameters:

stringId

StringId to copy

Definition at line 61 of file StringId.cpp.

bool StringId::operator==

(

const StringId &

stringId

)

const

Comparison operation (equality). Internally, this just compares two pointers, with no lookups taking place, so is really fast.

Definition at line 71 of file StringId.cpp.

bool StringId::operator!=

(

const StringId &

stringId

)

const

Comparison operation (inequality). Internally, this just compares two pointers, with no lookups taking place, so is really fast.

Definition at line 79 of file StringId.cpp.