Shared String Library

Instructions for Unix and Windows environments.  Assumes that you have access to:

• A compiler: -g++- or Visual Studio
• Standard template library (should come with the compiler)
• (Unix only) The -make- program

Under Unix

In the directory -build_unix- there is a Makefile to build both the library and the test files.  It should be sufficient to type:

cd build_unix
make install

This will compile everything and put the library into -lib- and the test program into -bin-.  If you -make clean- after installing, it will clean up the compiled files but will not uninstall the library and test program.

Note: The ‘make install’ isn’t what you might expect from a make install.  Normally such a process would put the library into e.g.  -/usr/local/lib-.  But since the majority of target users of this library will not have root access, I made the install process go to a more convenient location.

Under Windows

In the directory -build_win32- you will find a Visual Studio 7 project file.  You should be able to open that and select ‘Build | Build Solution’ to compile the library.  This will create files ‘sharedstr_win32.lib’ and ‘test-sharedstr.exe’ in the -debug- subdirectory of -build_win32-.  You should then copy the library wherever you want e.g. into the -lib- directory.

Covers usage and linking of the library.

Using the library in your program

Using the library is fairly simple.  The basic idea behind the library is that shared string templates are defined using a manager wrapper, and then you use this template definition as your shared string.  There is very little for you to do: you only need to call a macro before -typedef-’ing the shared string.

• Step 1.  Declare the manager wrapper in your header file.  Pick a header file that will be visible to every source file that needs the shared string.  For beginning SMAUG programmers, you should pick mud.h.  Include sharedstr.hpp.  Put in the SharedString::DECLARE_MANAGER_WRAPPER macro.  Add a typedef for shared string.  Example usage:

// (in a .h file somewhere)
#include <sharedstr.hpp>

// Declare the wrapper class.
// Feel free to call the wrapper something else, but if you rename it,
// make sure you rename it elsewhere as well.
DECLARE_MANAGER_WRAPPER(HashTableWrapper);

// Define the shared string type.
// Feel free to use a type name other than shared_str
typedef SharedString::SharedString< HashTableWrapper > shared_str;

• Step 2.  Create the manager table and associate it with the wrapper.  Pick a source file in which to define the table.  You’ll need an implementation of the manager to do this; one is provided in sharedstr_hashtable.h.  Define the pointer using your implementation and then call the SharedString::ASSOCIATE_MANAGER_WRAPPER using that pointer.  Example usage:

// (in a .cpp file somewhere)
// (make sure the above .h file is included!)

// Include your manager implementation. Here I use the provided sample
// hash table implementation.
#include <sharedstr_hashtable.h>

// Define the pointer.
SharedString::HashTable * gTable;

// Associate the wrapper class.
ASSOCIATE_MANAGER_WRAPPER(HashTableWrapper, gTable);

• Step 3.  From now on, you can use the shared string.  However, you also need to actually allocate the memory for the string manager.  You should do this somewhere towards the beginning of your program’s execution (or, in any case, before you ever allocate a shared string -- see known issues).  To conclude our example using the hash table implementation of the manager, you would use code like so:

// (at the global scope)
size_t SmaugHash(const char * str)
{
    return strlen(str);
}

// (in your initialization function, before you ever allocate
//  a shared string)
gTable = new SharedString::HashTable(&SmaugHash);

• Step 4.  Congratulations!  You should now be all set to use the shared string manager.

Linking the library into your project

Consult your compiler’s documentation for more detailed information on how to do this.  Here are some brief instructions, but for examples you can look at the makefile or project file for the test code.

• g++:

At the link phase of your compilation, add the following;

-L[dir]/lib -lsharedstr

where [dir] is wherever you put the shared string library.  The -L command tells g++ where to find the library, and -lsharedstr tells g++ to add the sharedstr library (libsharedstr.a).

• Visual Studio:

Under the project properties, go to the link step and add the library you compiled to the ‘input’ box.  Also make sure that the directory it’s in is on the library input path: you can do this in the link step as well, or set it to your global Visual Studio settings under ‘Tools | Options | Projects | VC++ Directories | Library Files’.

To do ...  For a preview, go through this forum post; http://www.gammon.com.au- /forum- /bbshowpost.php?bbsubject_id=5237 That’s where the project was born and initially discussed.  Maybe some of the reasons for my choices will become clear there, but probably not...  :-)

• If you statically initialize shared strings, you must also statically initialize the wrapper.  However, there is, as far as I know, no guaranteed way to force the wrapper to initialize before the shared strings.  In other words, use static initialization of shared strings at your own risk.
• There have been some issues with stricmp not existing on certain systems.  If your system does not provide stricmp, you need to define “SHARED_STR_NO_STRICMP” when compiling the shared string library.

• Many thanks to Raz and Samson from the Gammon Software Solutions forum for their valuable input and suggestions.
• Thanks to Nick Gammon for hosting the forum: it’s a great resource!
• Thumbs up to NaturalDocs (www.naturaldocs.org) for a very clean and nifty documentation solution.