_StringTable

A global table for the hashing and tracking of strings.

Classes:

class

_StringTable::Node

This is internal to the _StringTable class.

Implementation details

_StringTable()

~_StringTable()

Node **

buckets

U32

numBuckets

U32

itemCount

DataChunker

mempool

StringTableEntry

_EmptyString

const U32

csm_stInitSize

Public Static Functions

void

create()

Initialize StringTable.

void

destroy()

Destroy the StringTable.

U32

hashString(const char * in_pString)

Hash a string into a U32.

U32

hashStringn(const char * in_pString, S32 len)

Hash a string of given length into a U32.

Public Functions

StringTableEntry

EmptyString()

Represents a zero length string.

StringTableEntry

insert(const char * string, bool caseSens)

Get a pointer from the string table, adding the string to the table if it was not already present.

StringTableEntry

insertn(const char * string, S32 len, bool caseSens)

Get a pointer from the string table, adding the string to the table if it was not already present.

StringTableEntry

lookup(const char * string, bool caseSens)

Get a pointer from the string table, NOT adding the string to the table if it was not already present.

StringTableEntry

lookupn(const char * string, S32 len, bool caseSens)

Get a pointer from the string table, NOT adding the string to the table if it was not already present.

void

resize(const U32 newSize)

Resize the StringTable to be able to hold newSize items.

Detailed Description

A global table for the hashing and tracking of strings.

Only one _StringTable is ever instantiated in Torque. It is accessible via the global variable StringTable.

StringTable is used to manage strings in Torque. It performs the following tasks:

Ensures that only one pointer is ever used for a given string (through insert()).
Allows the lookup of a string in the table.

// Adding a string to the StringTable.
StringTableEntry mRoot;
mRoot = StringTable->insert(root);

// Looking up a string in the StringTable.
StringTableEntry stName = StringTable->lookupn(name, len);

// Comparing two strings in the StringTable (see below).
if(mRoot == stName) Con::printf("These strings are equal!");

But why is this useful, you ask? Because every string that's run through the StringTable is stored once and only once, every string has one and only one pointer mapped to it. As a pointer is an integer value (usually an unsigned int), so we can do several neat things:

StringTableEntrys can be compared directly for equality, instead of using the time-consuming String::compare() or dStricmp() function.
For things like object names, we can avoid storing multiple copies of the string containing the name. The StringTable ensures that we only ever store one copy.
When we're doing lookups by name (for instances, of resources), we can determine if the object is even registered in the system by looking up its name in the StringTable. Then, we can use the pointer as a hash key.

The scripting engine and the resource manager are the primary users of the StringTable.

note:
Be aware that the StringTable NEVER DEALLOCATES memory, so be careful when you add strings to it. If you carelessly add many strings, you will end up wasting space.

Implementation details

_StringTable()

~_StringTable()

Node ** buckets

U32 numBuckets

U32 itemCount

DataChunker mempool

StringTableEntry _EmptyString

const U32 csm_stInitSize

Public Static Functions

create()

Initialize StringTable.

This is called at program start to initialize the StringTable global.

destroy()

Destroy the StringTable.

This is called at program end to destroy the StringTable global.

hashString(const char * in_pString)

Hash a string into a U32.

hashStringn(const char * in_pString, S32 len)

Hash a string of given length into a U32.

Public Functions

EmptyString()

Represents a zero length string.

insert(const char * string, bool caseSens)

Get a pointer from the string table, adding the string to the table if it was not already present.

Parameters:

string	String to check in the table (and add).
caseSens	Determines whether case matters.

insertn(const char * string, S32 len, bool caseSens)

Get a pointer from the string table, adding the string to the table if it was not already present.

Parameters:

string	String to check in the table (and add).
len	Length of the string in bytes.
caseSens	Determines whether case matters.

lookup(const char * string, bool caseSens)

Get a pointer from the string table, NOT adding the string to the table if it was not already present.

Parameters:

string	String to check in the table (but not add).
caseSens	Determines whether case matters.

lookupn(const char * string, S32 len, bool caseSens)

Get a pointer from the string table, NOT adding the string to the table if it was not already present.

Parameters:

string	String to check in the table (but not add).
len	Length of string in bytes.
caseSens	Determines whether case matters.

resize(const U32 newSize)

Resize the StringTable to be able to hold newSize items.

This is called automatically by the StringTable when the table is full past a certain threshhold.

Parameters:

newSize

Number of new items to allocate space for.