<?php $isip_window_title = "ISIP Homepage"; ?>
<?php include("/data/isip/www/templates/documentation/header/header.html"); ?>

<!--#set var="isip_page_title" value="Set" -->
<?php include("/data/isip/www/templates/documentation/body/index_class.html"); ?>
<?php include("/data/isip/www/templates/documentation/body/bar.html"); ?>

<a name="name">
<b>name: <a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h">Set&lt;class TObject&gt </a>: public <a href = "../DoubleLinkedList/">DoubleLinkedList;</a></b>
<br><br>

<a name="synopsis">
<b>synopsis:</b>
<br><br>

<blockquote>
<pre>
g++ [flags ...] file ...

#include &lt;Set.h&gt;

Set(ALLOCATION alloc_d = DEF_ALLOCATION);
boolean insert(TObject* item);
boolean remove();
boolean contains(TObject* item);
const TObject* getPrev() const;
</pre>
</blockquote>

<a name="quick_start">
<b>quick start:</b>
<br><br>

<blockquote>
<pre>
// declare a character set and add two characters into it
//
Set&lt;Char&gt; 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
}

</pre>
</blockquote>

<a name="description"> 
<b>description:</b>
<br><br>

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.

<br><br>

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.

<br><br>

<a name="dependencies">
<b>dependencies:</b>
<br><br>
<ul>
  <li> <a href="../Set/DoubleLinkedNode.h"> DoubleLinkedNode </a>
  <li> <a href="../../math/scalar/String/"> String </a>
  <li> <a href="../../math/scalar/Char/"> Char </a>
  <li> <a href="../../system/Console/"> Console </a>
</ul>

<a name="constants">
<b>public constants:</b>
<br><br>

<ul>
  <li> define the class name:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&constant=CLASS_NAME">static const String CLASS_NAME = L"Set";</a></pre>
</ul>
<a name="error">
<b>error codes:</b>
<br><br>

<ul>
  <li> general Set class error:
       
       <pre><a href="/perl/ifc_document.pl?err=00042200">static const long ERR = 42200;</a></pre>
</ul>

<a name="protected">
<b>protected data:</b>
<br><br>

<ul>

  <li> static memory manager:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&static=mgr_d">static MemoryManager mgr_d;</a></pre>       
</ul>

<a name="public">
<b>required public methods:</b>
<br><br>

<ul>  
  <li> 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
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=name">static const String& name();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/SetDiagnose.h&method=diagnose">static boolean diagnose(Integral::DEBUG debug_level);</a></pre>
       
  <li> debug methods:

       <pre>setDebug is inherited from the DoubleLinkedList class</pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=debug">boolean debug(const unichar* message) const;</a></pre>
       
  <li> destructor/constructor(s):
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=destructor">~Set();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=default+constructor">Set(ALLOCATION alloc = DEF_ALLOCATION);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=copy+constructor">Set(const Set&lt;TObject&gt;& copy_list);</a></pre>

  <li> assign methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=assign&instance=0">boolean assign(const Set&lt;TObject&gt;& arg);</a></pre>

  <li> operator= methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=operator%3D">Set&lt;TObject&gt;& operator=(const Set&lt;TObject&gt;& arg);</a></pre>

  <li> equality methods:
       
       <pre>equality methods are inherited from the DoubleLinkedList class</pre>
       
  <li> i/o methods: refer to the <a href = "./index.html#notes">notes</a>
       section for an explanation of why there are two read and write
       methods in this class

       <pre>sofSize is inherited from the DoubleLinkedList class</pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=read&instance=0">boolean read(Sof& sof, long tag);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=write&instance=0">boolean write(Sof& sof, long tag) const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=read&instance=1">boolean read(Sof& sof, long tag, const String& name);</a></pre>              
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=write&instance=1">boolean write(Sof& sof, long tag, const String& name) const;</a></pre>       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=readData">boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param_a = true, boolean nested_a = false);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=writeData">boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;</a></pre>

  <li> memory management methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=new">static void* operator new(size_t size);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=new\[\]">static void* operator new[](size_t size);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=delete">static void operator delete(void* ptr);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=delete\[\]">static void operator delete[](void* ptr);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=setGrowSize">static boolean setGrowSize(long grow_size);</a></pre>
       <pre>clear is inherited from the DoubleLinkedList class</pre>
</ul>

<a name="specific">
<b>class-specific public methods:</b>
<br><br>

<ul>
  <li> overloaded operators and extensions to required methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=operator()&instance=0">const TObject& operator() (long index) const;</a></pre>
       
  <li> access methods: note that only the const versions are allowed
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getFirst&instance=0">const TObject* getFirst() const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getLast&instance=0">const TObject* getLast() const;</a></pre>
        <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getNext&instance=0">const TObject* getNext() const;</a></pre>
        <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getPrev&instance=0">const TObject* getPrev() const;</a></pre>
        <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getMark&instance=0">const TObject* getMark() const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=getCurr&instance=0">const TObject* getCurr() const;</a></pre>

  <li> insert and remove methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=insert&instance=0">boolean insert(TObject* item);</a></pre>

  <li> property methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=find">boolean find(const TObject* item);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/Set.h&method=contains">boolean contains(const TObject* item) const;</a></pre>
</ul>

<a name="private">
<b>private methods:</b>
<br><br>

<ul>

  <li> 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:

       <pre>boolean sort(Integral::ORDER sort_order = Integral::ASCENDING, SORT_ALGO = DEF_SORT_ALGO);</pre>
       <pre>boolean reverse();</pre>
       <pre>boolean swap(long i, long j);</pre>
       <pre>boolean insertFirst(TObject* item);</pre>
       <pre>boolean insertFirst(Set<TObject>& item_list);</pre>
       <pre>boolean insertLast(TObject* item);</pre>
       <pre>boolean insertLast(Set&lt;TObject&gt;& item_list);</pre>
       <pre>boolean apply(boolean (TObject::*method)());</pre>
       <pre>boolean apply(boolean (TObject::*method)(), Set&lt;TObject&gt;& arg);</pre>
  
</ul>

<a name="friend">
<b>friend classes:</b>
<br><br>

<ul>
  <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/Set/SetDiagnose.h">friend class SetDiagnose;</a></pre>
</ul>

<a name="examples">
<b>examples:</b>
<br><br>

<ul>


  <li> This example shows the basic operation of a Set:

       <pre>
#include &lt;Set.h&gt;
#include &lt;Char.h&gt;

int main() {

  // local variables
  //
  Set&lt;Long&gt; d;
  Long j;

  // add 10 unique items to the Set    
  //
  for (long i = 0; i&lt; 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-&gt;debug(L"item from the List");
  
  while((l=d.getNext())!=NULL) {
    d.gotoNext();
    l-&gt;debug(L"item from the List");      
  }

  // exit gracefully
  //     
  Integral::exit();
}</pre>

  <li> 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.

       <pre>
#include &lt;Set.h&gt;
#include &lt;Char.h&gt;

int main() {

  // local variables
  //
  Set&lt;long&gt; d(USER);
  Long* j;

  // add 10 unique items to the Set    
  //
  for (long i = 0; i&lt 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-&gt;debug(L"item from the List");
  delete l;
  
  while((l=d.getNext())!=NULL) {
    d.gotoNext();
    l-&gt;debug(L"item from the List");      
    delete l;
  }

  // exit gracefully
  //     
  Integral::exit();
}</pre>
       
</ul>

<a name="notes">
<b>notes:</b>
<br><br>

<ul>
  <li> 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.

       <br><br>
       
  <li> 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.

       <br><br>

  <li> 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.
</ul>

<!--#include virtual="/hse/ies/templates/documentation/footer/footer.html" -->






