Symtree API
===========

st_instance_ptr create_symtree()

  Creates a new instance of a symbol tree containing no
  symbols. You should never use a NULL pointer to an
  instance of a symbol tree. Always use create_symtree
  or load_st to get an instance of a symbol tree.

  May return NULL if it could not obtain resources. An
  error message will be printed to stderr


int destroy_symtree(st_instance_ptr tree)

   Frees all memory used by a symbol tree. Don't forget
   to set your pointer to NULL after using this function.


st_accessor_ptr create_st_accessor(st_instance_ptr tree)

  Some functions need an accessor to keep track of what they 
  are doing. This function will create an initialized 
  accessor to a symbol tree. You can create multiple accessors
  if you are performing multiple operations in an interspersed
  fashion.

  May return NULL if it could not get the appropriate
  resources or you gave it a NULL pointer. An error message 
  will be printed to stderr.


int reset_st_accessor(st_accessor_ptr accessor)

  Reset accessor state. Resets accessor so that a new
  symbol can be scanned. Functions that require an
  accessor will automatically call this function.


int destroy_st_accessor(st_accessor_ptr accessor)

  Frees all memory used by an accessor. Use this function
  when you are done with an accessor.


int add_null_sym(st_instance_ptr tree) 

  If you want a null symbol in your set, use this function.

  It will return __NO_ST_INSTANCE if you give it a NULL pointer.


int add_sym(st_instance_ptr tree, char* sym)

  Add a symbol contained in a string to the tree. The string
  must be null terminated. If there are any elements in the
  string that are not allowed to be in a symbol, it will 
  return __NON_ALPHA_ERROR. It may also return a 
  __PREVIOUS_ERROR if an internal error occurs. This should
  not happen if you are using Symtree correctly and you have
  the neccessary resources available.

  Error messages are printed to stderr for errors that are NOT
  related to bad input.

  Feeding this function an empty string will add a null
  symbol to the tree.


int stream_add_sym(st_accessor_ptr accessor, char letter)

  Allows you to add symbols element by element. When a 
  non-symbol element is encountered, it is treated as 
  delimiter, and adds the symbol to the tree. If two 
  delimiting elements are encountered in a row, it will
  not add the null symbol. 

  When you have finished feeding input, if you are unsure 
  if the last symbol has been added (last element may
  not have been a delimiter) you can use mark_sym to be sure
  the last symbol was added.

  May return errors if it cannot obtain needed resources. An
  error message will be printed to standard error.

  You must give a valid accessor.


int mark_sym(st_accessor_ptr accessor)

  Marks current input to stream_add_sym as a symbol.
  This will not add null symbols.

  st_accessor_ptr must not be NULL.


int del_null_sym(st_instance_ptr tree)

  Deletes the null symbol from a tree, if it is there. Use this
  to safely make sure there is no null symbol in a tree. 
                                                                                                                             
  It will return __NO_ST_INSTANCE if you give it a NULL pointer. 


int del_sym(st_instance_ptr tree, char* sym)
 
  Remove symbol contained in string from the tree. The string
  must be null terminated. If there are any elements in the
  string that are not allowed to be in a symbol, it will
  return __NON_ALPHA_ERROR. If it cannot find the symbol,
  it will return __NOT_A_SYM.  It may also return a 
  __PREVIOUS_ERROR if an internal error occurs. This should
  not happen if you are using Symtree correctly and you have
  the neccessary resources available.
 
  Error messages are printed to stderr for errors that are NOT
  related to bad input (error codes are returned).
 
  Feeding this function an empty string will remove the null
  symbol from the tree.


int stream_del_sym(st_accessor_ptr accessor, char letter)

  Allows you to remove symbols by feeding one element at a time. 
  When a non-symbol element is encountered, it is treated as
  a delimiter, and removes the symbol to the tree. If two
  delimiting elements are encountered in a row, it will
  not remove the null symbol.
                                                                                                                             
  When you have finished feeding input, if you are unsure
  if the last symbol has been removed (last element may
  not have been a delimiter) you can use del_target to be sure
  the last symbol was removed.
                                                                                                                             
  May return errors if it cannot obtain needed resources. An
  error message will be printed to standard error.
                                                                                                                             
  You must give a valid accessor.  


int del_target(st_accessor_ptr accessor)

  Removes current input to stream_del_sym. 
  This will not remove null symbols.
  Use to make sure the last symbol in a 
  stream was removed when unsure if last
  element was a delimiter.
                                                                                                                             
  st_accessor_ptr must not be NULL.


int sym_search(st_instance_ptr tree, char* sym)

  Check if a symbol exists in the tree. The string 
  containing the symbol must be null terminated. If the 
  string contains any non-symbol elements, it will return
  __NON_ALPHA_ERROR. A __PREVIOUS_ERROR may be returned
  if it could not get the required resources (the function
  that generated the error will print an error message to
  stderr). 


int stream_sym_state(st_accessor_ptr accessor, char letter)

  Allows you to check existence of a symbol by feeding
  it one element at a time. Will return status of:
	__NOT_A_SYM - elements fed are not part of any symbol
	__START_OF_SYM - elements fed do begin one or more 
		symbols
	__END_OF_SYM - when delimiting element feed, this is 
		returned if all previous elements feed are
		a compete symbol.

  When a delimiting character is fed, the state associated
  with the accessor is reset so the next symbol can be found.

  Every delimiting element (except the first delimiting element
  following a non-delimiting element) is treated as a null 
  symbol.  

  You must give this function a valid accessor.

  
int st_add_by_scan(st_instance_ptr tree, FILE* file)

  Scans a text file and adds symbols found to symbol tree.
  Delimiting elements (or characters) seperate symbols.
  Symbols will not be added more than once, as Symtree acts
  like a set. 

  The text file can be a list, or any text file you wish to
  compile a list of symbols (or words) from.

  Will return a __PREVIOUS_ERROR if an internal error occurs.
  An error message will be printed to stderr. This should not 
  occur if you use Symtree correctly and you have enough 
  resources available. 


int st_del_by_scan(st_instance_ptr tree, FILE* file)

  Scans a text file and removes symbols found from the 
  symbol tree. Delimiting elements (or characters) seperate 
  symbols.

  The text file can be a list, or any text file you which 
  wish to have all it's symbols (or words) removed from a
  symbol tree.

  Will return a __PREVIOUS_ERROR if an internal error occurs.
  An error message will be printed to stderr. This should not
  occur if you use Symtree correctly and you have enough 
  resources available.


int dump_st_text(st_instance_ptr tree, FILE* file)

  Dump the symbols contained in a symbol tree in sorted order
  to a text file. 

  Will return errors if given a null pointer to an instance of
  a symbol tree or it could not get the needed resources. Will
  print error message to stderr.


int dump_st(st_instance_ptr tree, FILE* file)

  Dump the structure of the symbol tree in a binary format.

  Will return errors if the given tree instance pointer is
  null or resources could not be obtained.


st_instance_ptr load_st(FILE* file)

  Load a symbol tree created with dump_st. Will create
  a new instance of a symbol tree and return pointer to it.

  Do not use an st_instance_ptr that is pointing to an 
  instance of a tree as it will result in a memory leak
  (unless you have another st_instance_ptr pointing to that
  tree or you use destroy_symtree).

  Will return NULL if an intenral error is encountered. An 
  error message will be printed to stderr. This should 
  not happen if you have the appropriate resources.


See error_codes