name: SofList
synopsis:

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

>     #include <SofList.h>

>     SofList();
>     SofList(const SofList& arg);
>     boolean add(long name, long tag, long pos, long size);
>     long first(long name);
>     long last(long name);
>     long getCount();

quick start:

>     SofList list;

>     // setup a simple symbol table
>     //
>     SofSymbolTable table;
>     SysString n1(L"Long");
>     long i1 = table.add(n1);

>     // add a node to the soflist
>     //
>     list.setTable(table);
>     list.add(i1, 0, -1, sizeof(long));
>     list.debug(L"added nodes");

>     long tag = list.prev(i1, 1000);
>     if (tag != 0) {
>       Console::put(L"Error in previous");
>     }

description:
SofList is a binary search tree used to hold indices for Sof files. it is used to keep track of a sorted list of objects. programmers should never use the SofList directly.
a binary search tree is a linked data structure in which each node is an object. each node has keys as well as pointers to its left, right and parent nodes. let x be a node in a binary search tree:

- if y is a node in the left subtree of x, then key[y] <= key[x],
- if y is a node in the right subtree of x, then key[x] <= key[y]

in this SofList, a name and a tag are used as the keys of a node. when comparing two nodes, the names are compared first, if the names are the same, the tags are compared. a good tutorial on heaps can be found at :

T.H. Cormen, C.E. Leiserson and R.L. Rivest, Introduction to Algorithms, McGraw-Hill, New York, New York, USA, pp. 140-149, 1997.

dependencies:

- SysString
- SofNode
- SofSymbolTable

public constants:

- define the class name:

      static const SysString CLASS_NAME = L"SofList";

- define the internal stack constants:

      static const long STACK_SIZE = 2048;

      static const long GROW_SIZE = 1024;

- define the default values for stack:

      static const long DEF_STACK_SIZE = 0;

      static const long DEF_STACK_PTR = 0;

      static const long DEF_STACK_FRAME = 0;

- define a dummy tag for a name not in the soflist:

      static const long NO_TAG = -2147483647;

error codes:

- error code indicating SofList class general error:

      static const long ERR = 10100;

- error code indicating symbol error:

      static const long ERR_SYMB = 10102;

- error code indicating copy error:

      static const long ERR_COPY = 10104;

- error code indicating delete error:

      static const long ERR_DELETE = 10105;

- error code indicating failure to add object to index:

      static const long ERR_ADD = 10106;

- error code indicating object already in index:

      static const long ERR_EXISTS = 10107;

- error code indicating current node not set:

      static const long ERR_CURR = 10108;

protected data:

- the root node of the binary tree:

      SofNode* root_d;

- the current node:

      SofNode* current_d;

- a pointer to the symbol table:

      SofSymbolTable* table_d;

- an internal stack to avoid recursion in the binary tree search:

      SofNode** stack_d;

      long stack_size_d;

      long stack_ptr_d;

      long stack_frame_d;

- debugging parameters

      Integral::DEBUG debug_level_d;

- define a memory manager

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const SysString& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      boolean debug(const unichar* msg) const;

      boolean setDebug(Integral::DEBUG debug_level);

- destructor/constructor(s):

      ~SofList();

      SofList();

      SofList(const SofList& arg);

- assign methods:

      boolean assign(const SofList& arg);

- operator= methods:

      SofList& operator= (const SofList& arg);

- i/o methods:

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

- equality methods:

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

- memory management methods:

      new and delete are omitted because memory for SofList objects is not managed by the MemoryManager class

      boolean clear();

class-specific public methods:

- memory size methods:

      long memSize();

- add object methods:

      boolean add(long name, long tag, long pos, long size);

      boolean addQuick(long name, long tag, long pos, long size);

- remove object methods:

      boolean remove();

- search objects methods:

      boolean find(long name, long tag);

      long first(long name);

      long last(long name);

      long next(long name, long cur_tag);

      long prev(long name, long cur_tag);

- set/get methods:

      boolean setTable(SofSymbolTable& table);

      boolean setPosition(long pos);

      boolean setSize(long size);

      long getName() const;

      long getTag() const;

      long getPosition() const;

      long getSize() const;

      long getNameCount();

      long getCount();

      long getCount(long name);

private methods:

- memory management methods:

      SofNode* newNode();

      boolean deleteNode(SofNode* node);

- add object methods:

      boolean addNode(SofNode* node);

- search objects methods:

      SofNode* findNode(long name, long tag);

      SofNode* findNode(long name);

- compare nodes methods:

      boolean nodeGt(const SofNode* node, long name, long tag) const;

      boolean nodeLt(const SofNode* node, long name, long tag) const;

      boolean nodeGt(const SofNode* node, long name) const;

      boolean nodeLt(const SofNode* node, long name) const;

      boolean nodeGt(const SofNode* node_1, const SofNode* node_2) const;

      boolean nodeLt(const SofNode* node_1, const SofNode* node_2) const;

      boolean nodeEq(const SofNode* node, long name) const;

- count nodes methods:

      long getCount(SofNode* node);

      long getCount(SofNode* node, long name);

- internal stack management methods

      boolean push(SofNode* ptr);

      boolean pop(SofNode*& ptr);

      boolean pushFrame();

      boolean popFrame();

- low-level debugging methods

      boolean display();

      boolean display(SysString& str, SofNode* node);

      boolean displayTree();

      boolean displayTree(SofNode* node, long level);

examples:

- This is a simple example wherein we define nodes. Then these nodes are added to the list of objects and we use search methods to test random access to the data.

      SofList list;

      // setup a simple symbol table
      //
      SofSymbolTable table;

      SysString n1(L"Long");    long i1 = table.add(n1);
      SysString n2(L"Short");   long i2 = table.add(n2);
      SysString n3(L"Float");   long i3 = table.add(n3);
      SysString n4(L"Char");    long i4 = table.add(n4);

      list.add(i1, 0, -1, sizeof(long));
      list.add(i2, 0, -1, sizeof(short));
      list.add(i3, 0, -1, sizeof(float));
      list.add(i4, 0, -1, sizeof(char));

      list.add(i2, 1, -1, sizeof(short));
      list.add(i1, -1, -1, sizeof(long));
      list.add(i4, 3, -1, sizeof(char));
      list.add(i4, 2, -1, sizeof(char));

      long tag = list.first(i4);
      if (tag != 0) {
       Console::put(L"Error in first");
      }

      tag = list.next(i4, tag);
      if (tag != 2) {
       Console::put(L"Error in next");
      }

      tag = list.next(i2, -100);
      if (tag != 0) {
       Console::put(L"Error in next");
      }

      tag = list.prev(i1, 1000);
      if (tag != 0) {
       Console::put(L"Error in first");
      }

notes:

- none