name: SofSymbolTable

synopsis:

g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_io.a

#include <SofSymbolTable.h>

SofSymbolTable();
long add(const SysString& name);
boolean remove(long number);
long getIndex(const SysString& name) const;

quick start:

SofSymbolTable table0;
SysString n1(L"Long")
table0.add(n1);
table0.remove(n1);

SysString bad_name(L"oscar had");
if (table0.checkName(bad_name)) {
  return Error::handle(name(), L"checkName", Error::TEST, __FILE__, __LINE__);
}

description:

SofSymbolTable is a class used to keep track of a symbol table for Sof's use. the symbol table is an array of SysStrings which are the symbol names. Programmers should never use the SofSymbolTable class directly, the HashTable class provided in the DSTR library is much safer and more user friendly.

dependencies:

SysString

public constants:

define the class name:

static const SysString CLASS_NAME = L"SofSymbolTable";

define the maximum length of a symbol:
```
static const long MAX_SYM_LENGTH = 64;
```
define the size to grow the symbol array by each time:
```
static const long GROW_SIZE = 256;
```

define invalid characters within symbol names:

static const SysString INVALID_CHARS = L" {}=\\;\"'/`:#";

define constants for efficiency measure:

static const long MAX_WASTED_SPACE = 1024;

define a dummy index for a non-exist symbol in the table:
```
static const long NO_SYMB = -1;
```

error codes:

error code indicating SofSymbolTable class general error:
```
static const long ERR = 10200;
```
error code indicating failure to add a symbol into the symbol table:
```
static const long ERR_ADD = 10201;
```
error code indicating failure to add a symbol into the symbol table:
```
static const long ERR_NOTFND = 10202;
```
error code indicating no transform vector:
```
static const long ERR_NOVEC = 10203;
```
error code indicating symbol index out of range:
```
static const long ERR_SYMB = 10204;
```

protected data:

an array of string symbols:
```
SysString* table_d;
```
number of references to symbols:
```
long* ref_count_d;
```
current length of the symbol table (some entries may be empty):
```
long table_size_d;
```
number of non-empty entries in the symbol table:
```
long num_syms_d;
```
capacity of the symbol table, it can be grown dynamically:
```
long table_capacity_d;
```
parameters used to transform between tables:
```
long* transform_d;
```
```
long transform_size_d;
```
debugging parameters:
```
Integral::DEBUG debug_level_d;
```

required public methods:

static methods:

static const SysString& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

boolean setDebug(Integral::DEBUG debug_level);

boolean debug(const unichar* msg) const;

destructor/constructor(s):

~SofSymbolTable();

SofSymbolTable();

SofSymbolTable(const SofSymbolTable& arg);

assign methods:

boolean assign(const SofSymbolTable& arg);

operator= methods:

SofSymbolTable& operator=(const SofSymbolTable& arg);

i/o methods:

these methods are omitted because SofSymbolTable can not write itself to an sof file

equality methods:

these methods are omitted because they are not useful for SofSymbolTable objects

memory management methods : new and delete are omitted because memory for SofSymbolTable objects, memory is not managed by the MemoryManager the clear method does not accept FREE mode, so the user is forced to use the destructor for handling the SofSymbolTable. Sof files could easily be corrupted if the memory of SofSymbolTable is improperly freed
```
boolean clear(Integral::CMODE ctype_a = Integral::DEF_CMODE);
```

class-specific public methods:

assign methods:

boolean assignCompact(const SofSymbolTable& arg);

memory size methods:
```
long memSize() const;
```

symbol retrieval methods:

long getIndex(const SysString& name) const;

boolean getSymbol(SysString& name, long num) const;

long getRefCount(const SysString& name) const;

long getRefCount(long index) const;

long getCount() const;

symbol entry manipulation methods:

long add(const SysString& name);

long add(long index, long refs, const SysString& name);

boolean remove(const SysString& name);

boolean remove(long number);

logical testing methods:

boolean checkName(const SysString& name) const;

boolean isEfficient() const;

convert methods: these methods get the index of a symbol in this table given its index in the old table
```
long convert(const SofSymbolTable& old, long index) const;
```
```
long convert(long index) const;
```

transform methods:

boolean transformInit(const SofSymbolTable& old);

boolean transformDelete();

private methods:

add new symbol methods:
```
long addNew(const SysString& name);
```
grow table capacity methods:
```
boolean growCapacity();
```
release memory methods
```
boolean freeMem();
```

examples:

This is a simple example showing how the SofSymbolTable and entries to the tables are declared. Methods like "add" and "remove" allow the user to deal with the table for required entries.

SofSymbolTable table0;
SofSymbolTable table1(table0);

SysString n1(L"Long");
SysString n2(L"Short");       
SysString n3(L"Float");
SysString n4(L"Long");

// add symbols into table
//
table0.add(n1);
table0.add(n2);
table0.add(n3);
table0.add(n4);

// check the entry
//
SysString symbol;
if (!table0.getSymbol(symbol, 0) || symbol.ne(n1)) {
  Console::put(L"Error in add/getSymbol");
}
       
long i = table0.getIndex(n1);       
if (i == SofSymbolTable::NO_SYMB) {
  return Error::handle(name(), L"getEntry", Error::TEST, __FILE__, __LINE__);
}

// remove a symbol
//      
table0.remove(n1);

notes:

none