stringTable.h

Public Functions

_getStringTable()

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _STRINGTABLE_H_
 25#define _STRINGTABLE_H_
 26
 27#ifndef _PLATFORM_H_
 28#include "platform/platform.h"
 29#endif
 30#ifndef _DATACHUNKER_H_
 31#include "core/dataChunker.h"
 32#endif
 33
 34
 35//--------------------------------------
 36/// A global table for the hashing and tracking of strings.
 37///
 38/// Only one _StringTable is ever instantiated in Torque. It is accessible via the
 39/// global variable StringTable.
 40///
 41/// StringTable is used to manage strings in Torque. It performs the following tasks:
 42///      - Ensures that only one pointer is ever used for a given string (through
 43///        insert()).
 44///      - Allows the lookup of a string in the table.
 45///
 46/// @code
 47/// // Adding a string to the StringTable.
 48/// StringTableEntry mRoot;
 49/// mRoot = StringTable->insert(root);
 50///
 51/// // Looking up a string in the StringTable.
 52/// StringTableEntry stName = StringTable->lookupn(name, len);
 53///
 54/// // Comparing two strings in the StringTable (see below).
 55/// if(mRoot == stName) Con::printf("These strings are equal!");
 56/// @endcode
 57///
 58/// <b>But why is this useful, you ask?</b> Because every string that's run through the
 59/// StringTable is stored once and only once, every string has one and only one
 60/// pointer mapped to it. As a pointer is an integer value (usually an unsigned int),
 61/// so we can do several neat things:
 62///      - StringTableEntrys can be compared directly for equality, instead of using
 63///        the time-consuming String::compare() or dStricmp() function.
 64///      - For things like object names, we can avoid storing multiple copies of the
 65///        string containing the name. The StringTable ensures that we only ever store
 66///        one copy.
 67///      - When we're doing lookups by name (for instances, of resources), we can determine
 68///        if the object is even registered in the system by looking up its name in the
 69///        StringTable. Then, we can use the pointer as a hash key.
 70///
 71///  The scripting engine and the resource manager are the primary users of the
 72///  StringTable.
 73///
 74/// @note Be aware that the StringTable NEVER DEALLOCATES memory, so be careful when you
 75///       add strings to it. If you carelessly add many strings, you will end up wasting
 76///       space.
 77class _StringTable
 78{
 79private:
 80   /// @name Implementation details
 81   /// @{
 82
 83   /// This is internal to the _StringTable class.
 84   struct Node
 85   {
 86      char *val;
 87      Node *next;
 88   };
 89
 90   Node**      buckets;
 91   U32         numBuckets;
 92   U32         itemCount;
 93   DataChunker mempool;
 94
 95   StringTableEntry _EmptyString;
 96
 97  protected:
 98   static const U32 csm_stInitSize;
 99
100   _StringTable();
101   ~_StringTable();
102
103   /// @}
104  public:
105
106   /// Initialize StringTable.
107   ///
108   /// This is called at program start to initialize the StringTable global.
109   static void create();
110
111   /// Destroy the StringTable
112   ///
113   /// This is called at program end to destroy the StringTable global.
114   static void destroy();
115
116   /// Get a pointer from the string table, adding the string to the table
117   /// if it was not already present.
118   ///
119   /// @param  string   String to check in the table (and add).
120   /// @param  caseSens Determines whether case matters.
121   StringTableEntry insert(const char *string, bool caseSens = false);
122
123   /// Get a pointer from the string table, adding the string to the table
124   /// if it was not already present.
125   ///
126   /// @param  string   String to check in the table (and add).
127   /// @param  len      Length of the string in bytes.
128   /// @param  caseSens Determines whether case matters.
129   StringTableEntry insertn(const char *string, S32 len, bool caseSens = false);
130
131   /// Get a pointer from the string table, NOT adding the string to the table
132   /// if it was not already present.
133   ///
134   /// @param  string   String to check in the table (but not add).
135   /// @param  caseSens Determines whether case matters.
136   StringTableEntry lookup(const char *string, bool caseSens = false);
137
138   /// Get a pointer from the string table, NOT adding the string to the table
139   /// if it was not already present.
140   ///
141   /// @param  string   String to check in the table (but not add).
142   /// @param  len      Length of string in bytes.
143   /// @param  caseSens Determines whether case matters.
144   StringTableEntry lookupn(const char *string, S32 len, bool caseSens = false);
145
146
147   /// Resize the StringTable to be able to hold newSize items. This
148   /// is called automatically by the StringTable when the table is
149   /// full past a certain threshhold.
150   ///
151   /// @param newSize   Number of new items to allocate space for.
152   void             resize(const U32 newSize);
153
154   /// Hash a string into a U32.
155   static U32 hashString(const char* in_pString);
156
157   /// Hash a string of given length into a U32.
158   static U32 hashStringn(const char* in_pString, S32 len);
159
160   /// Represents a zero length string.
161   StringTableEntry EmptyString() const { return _EmptyString; }
162};
163
164
165extern _StringTable *_gStringTable;
166
167inline _StringTable* _getStringTable()
168{
169   if(_gStringTable == NULL)
170      _StringTable::create();
171   return _gStringTable;
172}
173
174#define StringTable _getStringTable()
175
176#endif //_STRINGTABLE_H_
177
178