/*! Sunrise Data Dictionary Library
 *
 *  @brief a library for hashtable storage of arbitrary data objects
 *  with built-in reference counting and guaranteed order iteration.
 *
 *  revision 1.08 (pre-release)
 *
 *  @file dd_symbol_table.h
 *  symbol lookup table API
 *
 *  @author Benjamin Kowarsch <nospam://com.sunrise-tel/~firstname~>
 *
 *  @note The author's true email address is herewith specifically excluded
 *  from the license of this software.  You are _not permitted_ to make the
 *  author's true email address available to any third party.  You may only
 *  pass on the modified version of the email address as presented above.
 *
 * (C) 2006 Sunrise Telephone Systems Ltd. All rights reserved.
 *
 * @cond LICENSE_TERMS
 *
 * Permission is  hereby granted,  free of charge,  to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction,  including without limitation
 * the rights  to  use, copy, modify, merge, publish, distribute, sublicense,
 * and/or  sell copies of  the Software,  and  to permit persons  to whom the
 * Software is furnished to do so,  subject to the following conditions:
 *
 * The above copyright notice  and  this permission notice  shall be included
 * in all copies or substantial portions of the Software.
 *
 * Under no circumstances is it permitted for any licensee to take credit for
 * the creation of  the Software,  to claim  authorship  or  ownership in the
 * Software  or in any other way  give the impression  that they have created
 * the Software.  Credit to the  true authors  and  copyright holders  of the
 * Software is absolutely mandatory and must be given as follows:
 *
 * Software packages incorporating the Software or substantial portions of it
 * shall display  a copyright notice  for the Software  in the same manner as
 * they  display  any  other copyright notice;  shall  display  an authorship
 * notice  for  the Software  in the  same manner  as they display  any other
 * authorship notice;  and shall display  the license terms or a reference to
 * the license terms of the Software  in the same manner  as they display any
 * other license or license reference.
 *
 * GUI-based or GUI-alike  interactive installers  installing the Software or
 * substantial portions of it, shall display the Software's copyright notice,
 * authorship notice  and  license terms  in  full  during  the  installation
 * process.  Other installers such as shell command driven package installers
 * on Unix systems shall display copyright,  authorship  and  license  in the
 * same  manner  as for  any other software.  Installers shall allow users to
 * install the license file for the Software along with the Software itself.
 *
 * Software  which makes use of  but  does not incorporate,  nor bundle,  nor
 * install the Software  or substantial portions of it,  is  NOT  required to
 * display any copyright, authorship, license terms  or license reference for
 * the Software.  Static linking to the Software constitutes 'incorporating',
 * dynamic linking to the Software constitutes 'making use of' the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED,  INCLUDING  BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE  AND  NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY,  WHETHER IN AN ACTION OF CONTRACT,  TORT OR OTHERWISE,  ARISING
 * FROM,  OUT OF  OR  IN CONNECTION WITH THE SOFTWARE  OR  THE USE  OR  OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 * In countries and territories  where  the  above  no-warranty disclaimer is
 * not permissible by applicable law, the following terms apply:
 *
 * NO PERMISSION TO USE THE SOFTWARE IS GRANTED  AND THE SOFTWARE MUST NOT BE
 * USED AT ALL  IN SUCH COUNTRIES AND TERRITORIES WHERE THE ABOVE NO-WARRANTY
 * DISCLAIMER IS NOT PERMISSIBLE AND INVALIDATED BY APPLICABLE LAW.  HOWEVER,
 * THE COPYRIGHT HOLDERS HEREBY WAIVE THEIR RIGHT TO PURSUE OFFENDERS AS LONG
 * AS THEY OTHERWISE ABIDE BY THE TERMS OF THE LICENSE  AS APPLICABLE FOR USE
 * OF THE SOFTWARE  IN COUNTRIES AND TERRITORIES WHERE THE ABOVE  NO-WARRANTY
 * DISCLAIMER IS PERMITTED BY APPLICABLE LAW. THIS WAIVER DOES NOT CONSTITUTE
 * A LICENSE TO USE THE SOFTWARE IN COUNTRIES AND TERRITORIES WHERE THE ABOVE
 * NO-WARRANTY DISCLAIMER IS  NOT PERMISSIBLE  AND  INVALIDATED BY APPLICABLE
 * LAW.  ANY LIABILITY OF ANY KIND IS CATEGORICALLY RULED OUT AT ALL TIMES.
 *
 * @endcond
 */

#ifndef _DD_SYMBOL_TABLE_H
#define _DD_SYMBOL_TABLE_H

#include "dd_types.h"
#include "dd_status_codes.h"
#include "dd_hash_functions.h"


// --------------------------------------------------------------------------
// Opaque symbol table type
// --------------------------------------------------------------------------
//
// WARNING: Objects of this opaque type should only be accessed through this
// public interface.  DO NOT EVER attempt to bypass the public interface.
//
// The internal data structure of this opaque type is HIDDEN  and  MAY CHANGE
// at  any time  WITHOUT NOTICE.  The meaning of some internal pointer fields
// may change dynamically at runtime.  Accessing this internal data structure
// directly  other than through  the functions in  this  public interface  is
// UNSAFE and may result in an inconsistent program state or a crash.

typedef void *dd_symtable;


// --------------------------------------------------------------------------
// function:  dd_new_symtable(case_sensitive)
// --------------------------------------------------------------------------
//
// Creates and returns a  new empty symbol table.  The size of the table's
// hashtable  will be set to the  default symbol table size as returned by
// function dd_default_symtable_size().
//
// If flag <case_sensitive> is true,  the new symbol table will use hash
// function dd_hash_string() and all hashes will be  case sensitive.  If
// flag <case_sensitive> is false,  the new symbol table  will use  hash
// function dd_hash_string_toupper() and all hashes will be
// case insensitive.
//
// Returns NULL if the symbol table could not be created.

dd_symtable dd_new_symtable(bool case_sensitive);


// --------------------------------------------------------------------------
// function:  dd_new_symtable_from_symbols(case_sensitive, symbol #1, ...)
// --------------------------------------------------------------------------
//
// Creates and returns a new symbol table initialised with the symbols passed
// in the argument list.  The symbols must be strings and the list of symbols
// must be terminated with an empty C string ("\0") or NULL.  The size of the
// symbol table's hashtable will be set to  the default symbol table size  as
// returned by function dd_default_symtable_size().
//
// If flag <case_sensitive> is true,  the new symbol table will use hash
// function dd_hash_string() and all hashes will be  case sensitive.  If
// flag <case_sensitive> is false,  the new symbol table  will use  hash
// function dd_hash_string_toupper() and all hashes will be
// case insensitive.
//
// Returns NULL if the symbol table could not be created.

dd_symtable dd_new_symtable_from_symbols(bool case_sensitive, const char *symbol, ...);


// --------------------------------------------------------------------------
// function:  dd_add_symbol(symtable, symbol)
// --------------------------------------------------------------------------
//
// Adds the symbol <symbol> to symbol table <symtable>.
//
// Symbols are added to the symbol table by value and they must not be empty
// strings nor NULL.

dd_status dd_add_symbol(dd_symtable symtable, const char *symbol);


// --------------------------------------------------------------------------
// function:  dd_stored_hash_for_symbol(symtable, symbol, retain)
// --------------------------------------------------------------------------
//
// Returns  the  hash  value  stored  for symbol <symbol>  in  symbol  table
// <symtable>.  If retain flag <retain> is set,  the symbol's retain counter
// will be incremented and it will need to be released explicitly.
//
// Returns 0 if symbol <symbol> is not present in symbol table <symtable>.

cardinal dd_stored_hash_for_symbol(dd_symtable symtable, const char *symbol, bool retain);


// --------------------------------------------------------------------------
// function:  dd_symbol_for_hash(symtable, hash, retain)
// --------------------------------------------------------------------------
//
// Returns  a pointer to symbol <symbol>  for hash value <hash>  if <symbol>
// is stored in symbol table <symtable>.  If retain flag <retain> is set, the
// symbol's retain counter  will  be  incremented  and  it will  need  to  be
// released explicitly.
//
// Returns a pointer to an empty C string ("\0") if no symbol is stored  for
// hash value <hash>  in symbol table <symtable>.  Returns  NULL  if  symbol
// table <symtable> is NULL.

const char* dd_symbol_for_hash(dd_symtable symtable, cardinal hash, bool retain);


// --------------------------------------------------------------------------
// function:  dd_release_symbol_for_hash(symtable, hash)
// --------------------------------------------------------------------------
//
// Decrements the retain counter of the symbol stored for hash value <hash>
// in symbol table <symtable>, thereby releases a previous retain operation.

dd_status dd_release_symbol_for_hash(dd_symtable symtable, cardinal hash);


// --------------------------------------------------------------------------
// function:  dd_remove_symbol_for_hash(symtable, hash)
// --------------------------------------------------------------------------
//
// Requests removal of the symbol stored for hash value <hash>  from symbol
// table <symtable>  and marks it as removed.  Once marked as removed,  the
// symbol will no longer be returned by symbol table lookups.  The symbol
// will only be physically removed when its retain counter reaches 0.

dd_status dd_remove_symbol_for_hash(dd_symtable symtable, cardinal hash);


// --------------------------------------------------------------------------
// function:  dd_hashtable_size_of_symtable(symtable)
// --------------------------------------------------------------------------
//
// Returns the hashtable size of symbol table <symtable>.  Returns -1 if symbol
// table <symtable> is NULL.

int dd_hashtable_size_of_symtable(dd_symtable symtable);


// --------------------------------------------------------------------------
// function:  dd_hashtable_load_of_symtable(symtable)
// --------------------------------------------------------------------------
//
// Returns the hashtable load factor of symbol table <symtable>.  Returns -1
// if symbol table <symtable> is NULL.

int dd_hashtable_load_of_symtable(dd_symtable symtable);


// --------------------------------------------------------------------------
// function:  dd_symbol_count(symtable)
// --------------------------------------------------------------------------
//
// Returns the number of symbols stored in symbol table <symtable>.  Returns
// 0 if symbol table <symtable> is empty, returns -1 if <symtable> is NULL.

int dd_symbol_count(dd_symtable symtable);


// --------------------------------------------------------------------------
// function:  dd_retain_count_for_symbol(symtable, symbol)
// --------------------------------------------------------------------------
//
// Returns the retain counter of symbol <symbol> in symbol table <symtable>.
// Returns -1 if <symbol> is not present or if <symtable> is NULL.

int dd_retain_count_for_symbol(dd_symtable symtable, const char *symbol);


// --------------------------------------------------------------------------
// function:  dd_dispose_symtable(symtable)
// --------------------------------------------------------------------------
//
// Disposes of symbol table <symtable> and all symbols stored in it.

void dd_dispose_symtable(dd_symtable symtable);


#endif

// END OF FILE