/**
 * @file sstring.h
 *
 * Shared string objects.
 *
 * @author Geoff Davis <geoff@circlemudsquared.org>
 *
 * @par Copyright:
 *   Copyright (C) 2006 Geoff Davis <geoff@circlemudsquared.org><br>
 *                      Greg Buxton <greg@circlemudsquared.org>
 *
 * @par
 *   Copyright (C) 1993, 94 by the Trustees of the Johns Hopkins University<br>
 *   CircleMUD is based on DikuMUD, Copyright (C) 1990, 1991.
 *
 * @par
 *   All rights reserved.  See license.doc for complete information.
 *
 * @ingroup sstring
 * @package cs
 * @version 1.0
 */

#ifndef __SSTRING_H__
#define __SSTRING_H__

#include "base.h"

/**
 * The size of the string table's hash index.
 * @def 1001
 * @ingroup sstring
 */
#define STRING_TABLE_SIZE (1001)

/**
 * An alias for struct _sstring_t.
 * @ingroup sstring
 * @typedef struct _sstring_t
 */
typedef struct _sstring_t sstring_t;

/**
 * The shared string structure.
 * @ingroup sstring
 * @{
 */
struct _sstring_t {
  char          *data;                  /**< The string data.               */
  unsigned long	 hashCode;              /**< The pseudo-unique hash code.   */
  size_t         length;                /**< The length of the string data. */
  sstring_t     *next;                  /**< The next string in hash bucket.*/
  size_t         references;            /**< No. of references to string.   */
};
/** @} */

#ifndef __SSTRING_C__
/**
 * The maximum number of bytes allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_maxRealStringBytes;

/**
 * The maximum number of string objects allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_maxRealStringCount;

/**
 * The maximum number of virtual bytes allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_maxVirtualStringBytes;

/**
 * The maximum number of virtual string objects allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_maxVirtualStringCount;

/**
 * The current number of bytes allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_realStringBytes;

/**
 * The current number of string objects allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_realStringCount;

/**
 * The current number of virtual bytes allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_virtualStringBytes;

/**
 * The current number of virtual string objects allocated.
 * @ingroup sstring
 * @var size_t
 */
extern size_t g_virtualStringCount;

/**
 * The hash table containing the shared string objects.
 * @ingroup sstring
 * @var sstring_t *[STRING_TABLE_SIZE]
 */
extern sstring_t *g_stringTable[STRING_TABLE_SIZE];
#endif /* __SSTRING_C__ */

/**
 * Creates a shared string with one reference.
 * @param format the printf-style format specifier string
 * @return the new shared string, or NULL
 */
char *sstr_create(const char *format, ...);

/**
 * Creates a shared string with one reference.
 * @param str the contents of the shared string to be created   
 * @return the new shared string, or NULL               
 */
char *sstr_createRaw(const char *str);

/**
 * Releases one refrence to a shared string. When no references remain, the
 * shared string is freed.
 * @param str the shared string to which one reference is to be released
 * @return none
 */
void sstr_free(const char *str);

/**
 * Gets the shared string hash entry for a string.
 * @param str the string for which the hash entry is to be gotten
 * @return the shared string entry, or NULL if the string is not shared
 */
sstring_t *sstr_getEntry(const char *str);

/**
 * Gets a hash code suitable for representing the specified string in a hash
 * table. Note: Strings differing in cases will generate unique hash code.
 * @param str the string for which to get a hash code
 * @return the hash code
 */
unsigned long sstr_getHashCode(const char *str);

/**
 * Adds a reference to a shared string.
 * @param str the string to which a reference is to be added
 * @return none
 */
char *sstr_share(const char *str);

#endif /* __SSTRING_H__ */