dynamicarrays/docs/DynamicArrays_e.html - master - lasersquad/DynamicArrays

dynamicarrays/docs/DynamicArrays_e.html
586 строк21 KB
lasersquad
no message
11 фев 2003, 13:17
11 фев 2003, 13:178d91b09
<HTML>
<HEAD>
<TITLE>Dynamic Arrays</TITLE>
</HEAD>
<BODY >

<table width="100%" border="0" cellpadding="5" cellspacing="0">
   <tr>
   <td align=center bgColor=#009999>
    <font face="verdana,arial" size="5" color="#FFFFFF">
     <b>Dynamic Arrays </font><br>
<font face="verdana,arial" size="2" color="#FFFFFF"><b> Version 1.0</b><br></font>
 </td>
   </tr>
</table>

<font face="verdana,arial" size=2>

<p>Copyright &copy; 1998-2001 by Andrey Romanchenko<br>
All rights reserved.

<p><table cellspacing=2 cellpadding=0>
<tr>
   <td><font face="verdana,arial" size=2>
    <i>e-mail:&nbsp;&nbsp;</i></font>
	</td>
	<td><font face="verdana,arial" size=2>
	 <a href="mailto:lasersquard@yahoo.com?subject=Dynamic Arrays version 2.0">lasersquad@tut.by</a></font>
	</td>
</tr>
<tr>
   <td><font face="verdana,arial" size=2>
    <i>web site:&nbsp;&nbsp;</i></font>
   </td>
   <td><font face="verdana,arial" size=2>
    <a href="http://DynamicArrays.narod.ru" target=_new>http://DynamicArrays.narod.ru/</a></font>
	</td>
</tr>
<tr>
   <td></td>
   <td><font face="verdana,arial" size=2>
   <!-- (������ �����: <a href="http://www.dynamicarrays.cjb.net/" target=_new>http://www.dynamicarrays.cjb.net/</a>)</font>-->
	</font></td>
</tr>

</table>

<h3>Table of Contens</h3>
<ul>
  <li> <a href="#commondescr">Common Description</a>  
  <li> <a href="#instalation">Installations</a>
 <li> <a href="#globals">Global Declarations</a>
 <li> Classes
  <ul>
 <li> <a href="#THArrayBase">THArrayBase</a>
 <li> <a href="#THArrayTYPE>">THArray&lt;Class T&gt;</a>
 <li> <a href="#THArrayStringFix">THArrayStringFix</a>

 </ul>
</ul>

<hr>

<a name="commondescr"></a>
<h3>Common Description</h3>

Dynamic arrays are a set of classes for storing, fast searching and manipulating data of various types.
<br>
Memory is allocated dynamically depending on elements number in the array.
<br>

Memory is allocated by special algorithm to minimize memory blocks movement and blocks reallocation.
<br>
All the arrays are zero based (the first element has 0).
 

 <br><br>
<hr>

<a name="instalation"></a>
<h3>Installation</h3>

The library requires no installation procedure. For successful usage you need only to include <strong>DynamicArrays.h</strong> 
file using "<font color=blue>#include</font>" directive: 
<br><br>

<font color=blue>#include</font> <font color=green>"DynamicArrays.h"</font> <br><br>

You will get all the module capabilities.
<hr>

<a name="globals"></a>
<h3>Global declarations</h3> 

  There are only 2 global declarations in the library: TStringHash, PHArrayInt.
  <br><br>
  
  <font color=blue>typedef THash</font>&lt;<font color=blue>std</font>::<font color=blue>string</font>,
  <font color=blue>std</font>::<font color=blue>string</font>&gt;<font color=blue> TStringHash</font>;<br><br>
  <br>
   <font color=blue>typedef THArray</font>&lt;<font color=blue>int</font>&gt;* <font color=blue>PHArrayInt</font>;<br><br>

	
<br><br>
<hr>

<a name="THArrayBase"></a>
<h3>THArrayBase</h3> 

 This the base for all  the classes in the library. THArrayBase is an abstract class declaring only virtual methods manipulating 
 arrays. It is not a template class therefore it contains only type independent methods.

<br><br>

<table cellspacing="0" cellpadding="5" border="1">
<tr bgcolor="#009999">
    <td colspan="2" align="center" valign="middle"> <font face="verdana,arial" size=4>
	 Methods </font></td>
</tr>

<tr>
<a name="Capacity"></a>
    <td width=40%><font face="Courier New" size=2> 
	  <font color="#0000FF">int</font> 
	  <font color="#AA0000">Capacity</font>()
	  	 <font color="#0000FF">const </font>
	  </font></td>
    <td><font face="verdana,arial" size=2> The number of <strong>T</strong> type elements for which memory was 
	allocated. Each element is of sizeof(<strong>T</strong>) size.
      </font></td>
</tr>

<tr>
<a name="Count"></a>
    <td><font face="Courier New" size=2> 
	<font color="#0000FF">inline int</font>
	<font color="#AA0000"> Count</font>()
	<font color="#0000FF">const </font> 
	</font></td>
    <td><font face="verdana,arial" size=2>
	 The number of elements in the array.</font></td>
</tr>

<a name="Add"></a>
  <td><font face="Courier New" size=2>
     <font color="#0000FF">virtual int</font>
	 <font color="#AA0000">Add</font> (<font color="#0000FF">const void</font>* Value);
	 </font></td>
  <td><font face="verdana,arial" size=2>
     The method adds new element to the end of array and returns the index of that element.
 </font></td>
</tr>

<tr>
<a name="AddMany"></a>
  <td><font face="Courier New" size=2>
  <font color="#0000FF">void</font>
  <font color="#AA0000">AddMany</font>(<font color="#0000FF">const void</font>*pValue,
     <font color="#0000FF">int</font> Count)
  </font></td>
  <td><font face="verdana,arial" size=2>
	Not implemented yet
  </font></td>
</tr>

<tr>
<a name="AddFillValues"></a>
  <td><font face="Courier New" size=2>
   <font color="#0000FF">virtual void</font><font color="#AA0000"> AddFillValues</font>(<font color="#0000FF">const int</font> Num); </font></td>
  <td><font face="verdana,arial" size=2>
    The method adds <strong>Num</strong> elements to the end of array. 
	<strong>T</strong> class default constructor is called <strong>Num</strong> times.
	</font></td>
</tr>

<tr>
<a name="Clear"></a>
    <td><font face="Courier New" size=2>
	  <font color="#0000FF">virtual void</font>
	  <font color="#AA0000"> Clear</font>()
	  </font></td>
    <td><font face="verdana,arial" size=2>
	Logically empties the array (zeroes the number of elements) but do not deallocate previously used memory. 
	It allows to avoid memory allocation overheads filling the array next time.
	See also <a href="#ClearMem">ClearMem()</a> method.
	</font></td>
</tr>
<tr>
<a name="ClearMem"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">virtual void</font>
	<font color="#AA0000"> ClearMem</font>
	</font></td>
  <td><font face="verdana,arial" size=2>
    Clears the array and frees all used memory.
	</font></td>
</tr>

<tr>
<a name="DeleteValue"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF"> virtual void</font>
	<font color="#AA0000"> DeleteValue</font>(<font color="#0000FF">const int</font> Index);
	</font></td>
  <td><font face="verdana,arial" size=2>
	The method deletes element in Index position. Other subsequent values are shifted to the beginning. 
	In this case memory is not deallocated. See <a href="#Hold">Hold</a> method to free unused memory.
  </font></td>
</tr>

<tr>
<a name="InsertValue"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">virtual void</font>
	<font color="#AA0000"> InsertValue</font>
	(<font color="#0000FF">const int</font> Index,<font color="#0000FF"> const void</font>* Value)
	</font></td>
  <td><font face="verdana,arial" size=2>
   The method adds the value referenced by <strong>Value</strong> pointer to the <strong>Index</strong> position. 
   The subsequent elements are shifted to the end.
</font></td>
</tr>

<tr>
<a name="InsertMany"></a>
  <td><font face="Courier New" size=2>
  <font color="#0000FF">virtual void</font>
  <font color="#AA0000"> InsertMany</font>(<font color="#0000FF">int</font> Num, <font color="#0000FF">void*</font> *pValue,
     <font color="#0000FF">int</font> Count)
  </font></td>
  <td><font face="verdana,arial" size=2>
	Not implemented yet.
	   </font></td>
</tr>

<tr>
<a name="Hold"></a>
  <td><font face="Courier New" size=2>
  <font color="#0000FF">inline void</font>
  <font color="#AA0000">Hold</font>()
  </font></td>
  <td><font face="verdana,arial" size=2>
    Free unused memory. Frees memory that is not used by elements. Unused memory appears during a optimized algorithm of memory
	allocation. By default allocation engine allocates more memory that it need to store elements. This algorithm reduces memory 
	allocation overheads and improves performance when values inserted and deleted quickly. The next request for adding elements 
	causes allocation a new memory.
 </font></td>
</tr>
<tr>
  <td><font face="Courier New" size=2>
   <font color="#0000FF">void</font> 
   <font color="#AA0000">Zero</font>()
    </font></td>
  <td><font face="verdana,arial" size=2>
	Zeroes arrays by default values. For each element default T() constructor is called. Use this method with care because all 
	data stored in array will be deleted after calling Zero().
	</font></td>
</tr>
<tr>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">void</font> 
	<font color="#AA0000">SetCapacity</font>
	(<font color="#0000FF">const int</font> Value)
	 </font></td>
  <td><font face="verdana,arial" size=2>
	The method allocates additional memory (when <strong>Value</strong> &gt; <strong>Count()</strong>) or frees superfluous one 
	(when <strong>Value</strong> &lt; Count()). The main difference from <strong>GrowTo</strong>() that it does not uses a special 
	algorithm to calculate memory size. This methos allocates memory exactly on <strong>Value</strong> elements.
 </font></td>
</tr>

</table>
<br>
<br>


 <a Name="#THArrayTYPE>"></a>
 <h3><font color="#0000FF">THArray</font>&lt;<font color="#0000FF">Class T</font>&gt;</h3>
 
 Class-template to store elements of any type. The elements can be any type even array type i.e. the constructions
 like  <font color="#0000FF">THArray</font>&lt;<font color="#0000FF">THArray</font>&lt;<font color="#0000FF">std::vector</font>
 &lt;<font color="#0000FF">std::string</font>&gt; &gt; &gt; are allowed.<br>
 Overrides all methods of  <a href= "#THArrayBase">THArrayBase</a> class and defines new ones.
<br><br>
 Throws THArrayException on attempt to get access to the nonexisting element. (when index is out of bounds).
 <br><br>
 Can be used as implementation of stack (LIFO). See methods  <a href="#Push">Push</a> and <a href="#Pop">Pop</a>.

 <br><br>

 <table cellspacing="0" cellpadding="5" border="1">
<tr bgcolor="#009999">
	<td colspan="2" align="center" valign="middle"><font face="verdana,arial" size=4>
      Methods
	</font></td>

</tr>

<tr>
<a name="Memory"></a>
    <td width=40%><font face="Courier New" size=2>
	 <font color="#0000FF">inline void</font>*
	 <font color="#AA0000">Memory</font>()
	 <font color="#0000FF">const </font>
	 </font></td>
    <td><font face="verdana,arial" size=2>
	 The pointer to the first element. All elements in array are stored subsequently. 
	 The second element has address 
	 <strong>Memory() + sizeof(T)</strong>,
	 the third 
	 <strong>Memory() + 2*sizeof(T)</strong>
	 and so on.
	 </font></td>
</tr>


<tr>
<a name="IndexOf1"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">inline int</font>
	<font color="#AA0000"> IndexOf</font>(<font color="#0000FF">const T</font>& Value)<font color="#0000FF">const</font>
	</font></td>
	<td><font face="verdana,arial" size=2>
	Th returns the index of the first element with Value value. Otherwise returns -1.
	For this function it is required to have operator = implemented in T class.
	If class <strong>T</strong> does not declare operator =, see another overridden function IndexOf described below to make 
	search in array using special Compare class.
	To make a rather searching see the method <a href="#IndexOfFrom1">IndexOfFrom</a>.
	</font></td>
</tr>

<tr>
<a name="IndexOf2"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">inline int</font>
	<font color="#AA0000"> IndexOf</font>(<font color="#0000FF">const T</font>& Value,
   	     <font color="#0000FF">const Compare</font><<font color="#0000FF">T</font>>& cmp)<font color="#0000FF">const</font>;
	</font></td>
	<td><font face="verdana,arial" size=2>
	The method returns the index of the first element with value <strong>Value</strong>. Otherwise returns <strong>-1</strong>. 
	This function compares elements by a special class <strong>Compare</strong> in second argument. You should use this function 
	if your class <strong>T</strong> does not declare operator = or you need some special compare algorithm. There are three virtual
	methods in Compare class: 
	<br>	
	<strong>bool eq(const C& a, const C& b)</strong> -
	 means "equal". Return <strong>true</strong> if elements are equal, otherwise return <strong>false</strong>.
	 <br>
	 <strong>bool lt(const C& a, const C& b)</strong>  -
	  means "less than". Return <strong>true </strong>when the first parameter is less than the second one, otherwise return <strong>false</strong>.
	  <br>
	 <strong>bool mt(const C& a, const C& b)</strong> - 
	  means "more than". Return <strong>true </strong>when the first parameter is more than the second one, otherwise return <strong>false</strong>.
	  <br>
	  See <strong>Compare.h</strong> source file for details. By default class <strong>Compare</strong> try to compare two values 
	  by operators =, &gt;, &lt;. To implement your own compare algorithm you should explicitly parameterize class <strong>Compare </strong>
	  as it done for <strong>std::string</strong> class (see class <font color="#0000FF">Compare</font>&lt;<font color="#0000FF">std::string</font>&gt; 
	  in <strong>Compare.h</strong> to compare strings case insensitive). To implement different compare algorithms for one storing 
	  type, you should create a descendant of <strong>Compare</strong> class. For example if you want to compare string by your 
	  special algorithm you can derive compare class as shown below:
	  <br>
	  <font color="#0000FF">
	  template</font>&lt;<font color="#0000FF">class C</font>&gt;<br>
	  <font color="#0000FF">
	  class CompareCaseSensitive : public Compare</font>&lt;<font color="#0000FF">C</font>&gt;<br>
	  {<br>
	  <font color="#0000FF">
	  public:<br>
	  bool</font> <font color="#AA0000">eq</font>(<font color="#0000FF">const std::string& </font> a, <font color="#0000FF">const std::string& </font> b){ <font color="#0000FF">your implementation of  operator = </font>};<br>
	  <font color="#0000FF">bool</font> <font color="#AA0000">lt</font>(<font color="#0000FF">const std::string& </font>a, <font color="#0000FF">const std::string& </font>b){ <font color="#0000FF"> your implementation of  operator &lt; </font>};<br>
	  <font color="#0000FF">bool</font> <font color="#AA0000">mt</font>(<font color="#0000FF">const std::string& </font>a, <font color="#0000FF">const std::string& </font>b){<font color="#0000FF"> your implementation of  operator &gt;</font> }; <br>
	  };
	  <br>

 	 To make rather searching see the method <a href="#IndexOfFrom1">IndexOfFrom</a>.
	</font></td>
</tr>

<tr>
<a name="IndexOfFrom"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">int</font>
	<font color="#AA0000">IndexOfFrom</font>
	(<font color="#0000FF">const T</font>& Value, <font color="#0000FF">const int</font>Start)
	</font></td>
	<td><font face="verdana,arial" size=2>
	The method returns the index of the first element with value <strong>Value</strong>. Otherwise returns <strong>-1</strong>. 
	The search begins from element with index <strong>Start</strong>. Element with index <strong>Start</strong> will be compared first, 
	then element with index <strong>Start</strong> + <strong>1</strong> and so on. 
	</font></td>
</tr>

<tr>
<a name="Grow"></a>
  <td><font face="Courier New" size=2>
   <font color="#0000FF">void</font> 
   <font color="#AA0000">Grow</font>()
   </font></td>
  <td><font face="verdana,arial" size=2>
	The method allocates additional memory using special algorithm for storing a new elements that will be added in future. 
	For large arrays (more than <strong>64</strong> elements) allocated memory grows by <strong>25%</strong>.
</font></td>
</tr>

<tr>
<a name="GrowTo"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">void</font> 
	<font color="#AA0000">GrowTo</font>
	(<font color="#0000FF">int</font> ToCount)
	</font></td>
  <td><font face="verdana,arial" size=2>
	The method allocates additional memory using special algorithm for storing a new elements that will be added in future. 
	The new memory capacity is calculated by the next formula:<br>
	<strong>Capacity = max(Capacity calculated by special algorithm, ToCount)</strong>. <br>
	This method is useful when you want to quickly add many elements without memory reallocation.
	</font></td>
</tr>


<tr>
<a name="GetValue"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">T</font> 
	<font color="#AA0000">GetValue</font>
	(<font color="#0000FF">const int</font> Index)<font color="#0000FF">const</font>
	 </font></td>
  <td><font face="verdana,arial" size=2>
	This method gets element by index. If no element with index Index the THArrayException raised.
	</font></td>
</tr>

<tr>
<a name="GetValuePointer"></a>
  <td><font face="Courier New" size=2>
   <font color="#0000FF"> T</font> 
   <font color="#AA0000">*GetValuePointer</font>
   (<font color="#0000FF">const int</font> Index)<font color="#0000FF">const</font>
   </font></td>
  <td><font face="verdana,arial" size=2>
	The method gets the pointer to the element in array. It useful when you want to make changes in element without copying 
	it from and to the array.</font></td>
</tr>


<tr>
<a name="Swap"></a>
  <td><font face="Courier New" size=2>
    <font color="#0000FF">inline void</font> 
	<font color="#AA0000">Swap</font>
	(<font color="#0000FF">int</font> Index1, <font color="#0000FF">int</font> Index2)
	</font></td>
  <td><font face="verdana,arial" size=2>
	 Swaps two elements with indexes <strong>Index1</strong> and <strong>Insdex2</strong>. 
  </font></td>
</tr>

<tr>
<a name="Pop"></a>
	<td><font face="Courier New" size=2>
    <font color="#0000FF">inline T</font> 
	<font color="#AA0000">Pop</font>()
	</font></td>
	<td><font face="verdana,arial" size=2>
	"Gets value from top of the stack" - returns the last value in the arrays and then deletes this value. After this method array
	will contains <strong>Count()-1</strong> elements.
	The method should be called when arrays are used as stack implementation.
	Throws <a href="#THArrayException" >THArrayException</a> when array is empty (no elements in stack).
	</font></td>
</tr>
<tr>
<a name="Push"></a>
	<td><font face="Courier New" size=2>
    <font color="#0000FF">inline void</font> 
	<font color="#AA0000">Push</font>
	(<font color="#0000FF">const T</font>& Value)
	</font></td>
	<td><font face="verdana,arial" size=2>
	"Pushes value to the stack" - addes the alue <strong>Value</strong> to the end of array. 
	The method is called when arrays are used as stack implementation.

	</font></td>
</tr>


</table>
<br>
 
<br>
<br>


 <a Name="#THArrayException>"></a>
 <h3>THArrayException</h3>
 
 A THArrayException represents an exception that can be occured in DynamicArrays. 
 Usualy it is a "Element with index ... not found" or "Key not found" errors.
 Does not have the default constructor (moved to the <strong>protected</strong> section).
 <br><br>

 <table cellspacing="0" cellpadding="5" border="1">
<tr bgcolor="#009999">
	<td colspan="2" align="center" valign="middle"><font face="verdana,arial" size=4>
      Methods
	</font></td>

</tr>
<tr>
<a name="THArrayException1"></a>
	<td width=40%><font face="Courier New" size=2>
	<font color="#0000FF">THArrayException</font>
	(<font color="#0000FF">const char</font>* Message)
	</font></td>
	<td><font face="verdana,arial" size=2>
		Constructs exception object from string in C format.	
	</font></td>
	
</tr>
<tr>
<a name="THArrayException2"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">THArrayException</font>
	(<font color="#0000FF">const std::string</font>& Message)
	</font></td>
	<td><font face="verdana,arial" size=2>
		Constructs exception object from standard C++ string format.		
	</font></td>
</tr>
<tr>
<a name="THArrayException3"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">THArrayException</font>
	(<font color="#0000FF">const THArrayException</font& ex)
	</font></td>
	<td><font face="verdana,arial" size=2>
	  Copy constructor. Constructs object from other exception object.
	</font></td>
</tr>
<tr>
<a name="THArrayException4"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">virtual ~THArrayException</font>()
	</font></td>
	<td><font face="verdana,arial" size=2>
	Virtual	Destructor. Does nothing in THArrayException class.
	</font></td>
</tr>
<tr>
<a name="operatoreq"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">THArrayException</font>& 
	<font color="#0000FF">operator=</font>
	(<font color="#0000FF">const THArrayException</font>& rhs) 
	</font></td>
	<td><font face="verdana,arial" size=2>
	Copy operator. Do the same as copy constructor.
	</font></td>
</tr>
<tr>
<a name="getErrorMessage"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">virtual std::string</font>
	<font color="#AA0000">getErrorMessage</font>()
	<font color="#0000FF">const</font>
	</font></td>
	<td><font face="verdana,arial" size=2>
	A virtual method that returns an error message. 
	Use this method in derived classes instead of old method what() from exception class.
	</font></td>
</tr>
<tr>
<a name="what"></a>
	<td><font face="Courier New" size=2>
	<font color="#0000FF">const char</font>*
	<font color="#AA0000">what</font>()
	<font color="#0000FF">const</font>;
	</font></td>
	<td><font face="verdana,arial" size=2>
	The method returns error message in C standard format (const char*). This is old method. Use getErrorMessage() to get error 
	message in standard C++ string format (std::string).
	</font></td>
</tr>

</table>

</font></BODY>
</HTML>