name: Set<class TObject> : public DoubleLinkedList;

synopsis:

g++ [flags ...] file ...

#include <Set.h>

Set(ALLOCATION alloc_d = DEF_ALLOCATION);
boolean insert(TObject* item);
boolean remove();
boolean contains(TObject* item);
const TObject* getPrev() const;

quick start:

// declare a character set and add two characters into it
//
Set<Char> set;
Char item0(L'a');
Char item1(L'b');
set.insert(&item0);
set.insert(&item1);

// insert item0 again
//
set.insert(&item0);

// the length should still be 2, since two items are identical
//
if (set.length() != 2) {
  // error
}

description:

The Set class buolds a collection of unique objects. This class will only hold a single instance of each unique-valued object, so a list class is more appropriate for most cases. There is no new class data (except a memory manager) than the list class. The only difference is the way things are inserted into the set. The insert method will always insert the item in order and return false if it already exists in the set.

The user may choose whether or not the Set is used in USER-allocated or SYSTEM-allocated mode. In the SYSTEM-allocated mode, the Set class is responsible for managing the memory for the objects it contains. This implies that a copy is made each time an object is inserted to the list. In USER-allocation mode the user is responsible for allocation and deletion of the objects that are stored in the Set. in this mode, pointers to the external objects are stored, i.e. a copy is not made. the mode chosen is dependent on the user's need to trade-off speed versus complexity of object management.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Set";

error codes:

general Set class error:
```
static const long ERR = 42200;
```

protected data:

static memory manager:
```
static MemoryManager mgr_d;
```

required public methods:

static methods: diagnose method is moved outside the class header file and defined in the SetDiagnose.h in order to avoid issues with preprocessing of the diagnose code
```
static const String& name();
```
```
static boolean diagnose(Integral::DEBUG debug_level);
```

debug methods:

setDebug is inherited from the DoubleLinkedList class

boolean debug(const unichar* message) const;

destructor/constructor(s):

~Set();

Set(ALLOCATION alloc = DEF_ALLOCATION);

Set(const Set<TObject>& copy_list);

assign methods:

boolean assign(const Set<TObject>& arg);

operator= methods:

Set<TObject>& operator=(const Set<TObject>& arg);

equality methods:

equality methods are inherited from the DoubleLinkedList class

i/o methods: refer to the notes section for an explanation of why there are two read and write methods in this class

sofSize is inherited from the DoubleLinkedList class

boolean read(Sof& sof, long tag);

boolean write(Sof& sof, long tag) const;

boolean read(Sof& sof, long tag, const String& name);

boolean write(Sof& sof, long tag, const String& name) const;

boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param_a = true, boolean nested_a = false);

boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

clear is inherited from the DoubleLinkedList class

class-specific public methods:

overloaded operators and extensions to required methods:
```
const TObject& operator() (long index) const;
```

access methods: note that only the const versions are allowed

const TObject* getFirst() const;

const TObject* getLast() const;

const TObject* getNext() const;

const TObject* getPrev() const;

const TObject* getMark() const;

const TObject* getCurr() const;

insert and remove methods:
```
boolean insert(TObject* item);
```

property methods:

boolean find(const TObject* item);

boolean contains(const TObject* item) const;

private methods:

these List methods are blocked since they would leave the Set in a bad state (i.e., non-sorted) or are not useful to a Set:

boolean sort(Integral::ORDER sort_order = Integral::ASCENDING, SORT_ALGO = DEF_SORT_ALGO);

boolean reverse();

boolean swap(long i, long j);

boolean insertFirst(TObject* item);

boolean insertFirst(Set& item_list);

boolean insertLast(TObject* item);

boolean insertLast(Set<TObject>& item_list);

boolean apply(boolean (TObject::*method)());

boolean apply(boolean (TObject::*method)(), Set<TObject>& arg);

friend classes:

friend class SetDiagnose;

examples:

This example shows the basic operation of a Set:

#include <Set.h>
#include <Char.h>

int main() {

  // local variables
  //
  Set<Long> d;
  Long j;

  // add 10 unique items to the Set    
  //
  for (long i = 0; i< 10; i++) {
    j = i * 3;
    d.insert(&j);
  }

  // see what is on the Set
  //
  d.debug(L"after insertion");
       
  // get the elements and print them
  //
  d.gotoFirst();     
  Long* l = d.getFirst();
  l->debug(L"item from the List");
  
  while((l=d.getNext())!=NULL) {
    d.gotoNext();
    l->debug(L"item from the List");      
  }

  // exit gracefully
  //     
  Integral::exit();
}

This example shows the basic operation of a Set in USER mode. Note that memory is manually allocated before inserting it into the Set and then deleted later.

#include <Set.h>
#include <Char.h>

int main() {

  // local variables
  //
  Set<long> d(USER);
  Long* j;

  // add 10 unique items to the Set    
  //
  for (long i = 0; i< 10; i++) {
    j = new Long(i * 3);
    d.insert(j);
  }

  // see what is on the Set
  //
  d.debug(L"after insertion");

  // get the elements and print them
  //
  d.gotoFirst();     
  Long* l = d.getFirst();
  l->debug(L"item from the List");
  delete l;
  
  while((l=d.getNext())!=NULL) {
    d.gotoNext();
    l->debug(L"item from the List");      
    delete l;
  }

  // exit gracefully
  //     
  Integral::exit();
}

notes:

There are two memory allocation modes for Set as indicated by the protected member data, alloc_d. The default allocation mode is SYSTEM. If alloc_d is set to SYSTEM, the list handles allocation and deletion of the objects. When the user puts an object into the list, a copy of the object is made and inserted into the list via local memory allocation. Note that this requires a call to the copy constructor so the user will experience an efficiency decrease. When the object is removed from the list, it is automatically deleted.
If alloc_d is set to USER, the user is required to handle all memory allocation and deletion. When the user adds an object to the list, the object passed in is stored in the list by pointer reference. When an object is removed, the user is required to accept a pointer to the object.
Unlike other classes, we have two read and write methods in dstr classes. The interface is still the same as that in other classes. The reason behind this is that we can not use "CLASS_NAME" as default argument in the read and write methods here because the data structures build the class name on the fly.