====== Shared String ======

To minimize memory use, Crossfire uses a shared string mechanism. \\
This is intended to be used for strings whose contents are not expected to change during the server's life. \\
Using shared strings saves memory and improved performance.

Those strings are used like regular ''const char*'', \\
but should not be changed via ''strcpy'', ''snprintf'' or other means \\
because it would affect **all** structures using the shared string. \\
Internally, they use a counter to track at how many places they are used. \\
When it reaches 0, string is freed.

----

===== Shared String Manipulation ==
To alter such a string, the right behaviour is:
  * write new value in a ''char[] new_value'' variable
  * use ''free_string(str)''
  * call ''str = add_string(new_value)''

To manipulate them, the following functions defined in \\ 
[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/common/shstr.c?view=markup|common/shstr.c]]  <- FIXME file location \\
are available:
  * Old: ''const char* add_string(const char *str)''
  * New: ** ''sstring add_string(const char *str)'' **
    * Used to share an existing string. 
    * Returned value is a string with the same contents of ''str'' that can be shared with other objects.
    * Returns return hash_table[ind]->string

  * Old: ''const char* add_refcount(const char *str)'' 
  * New: ** ''sstring add_refcount(sstring str)'' **
    * This will increase the refcount of the string str.
    * String str which *must* have been returned from a previous add_string().
    * :?: Equivalent of ''add_string'' when the string is already a shared string. :?:


  * Old: ''const char* find_string(const char *str)'' 
  * New: ** ''sstring find_string(const char *str)'' **
    * To search if a string is shared or not.
    * Returns pointer to identical string or NULL .


  * Old: ''void free_string(const char *str)''
  * New: ** ''void free_string(sstring str)'' **
    * To decrement the use refcount counter. 
    * *Must* have been returned from a previous add_string().
    * After it's called, ''str'' should not be used anymore.

Because shared strings will return a pointer to a string if it exists, \\
one can see if the strings are equal by comparing the shared string address they point to (ie ''str == str2'') directly.

----

===== SSTRING =====
sstring is defined in //server/include/shstr.h// since at least version 1.11.0 :
<code c>
/**
 * One actual shared string.
 */
typedef struct _shared_string {
    union {
        struct _shared_string **array;
        struct _shared_string *previous;
    } u;
    struct _shared_string *next;
    /* The top bit of "refcount" is used to signify that "u.array" points
     * at the array entry.
     */
    unsigned REFCOUNT_TYPE refcount;
    /* Padding will be unused memory, since we can't know how large
     * the padding when allocating memory. We assume here that
     * sizeof(long) is a good boundary.
     */
    char string[PADDING];
} shared_string;
</code>

----

===== Trivial ==
<code c>
/**
 * @file shstr.c
 * This is a simple shared strings package with a simple interface.
 *
 * Author: Kjetil T. Homme, Oslo 1992.
 */
</code>