name: Vector<class TObject>: public DstrBase<TObject>
synopsis:

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

>     #include <Vector.h>
>     Vector(long length = DEF_LENGTH);
>     boolean assign(const Vector<TObject>& copy_vector);
>     boolean shift(long delta);
>     boolean apply(boolean (TObject::*method)());

quick start:

>     // declare a character Vector of length 5
>     //
>     Vector<Char> val0(5);

>     // assign all the elements to be 'a'
>     //
>     Char item(L'a');
>     val0.assign(item);

>     // check that each element is 'a'
>     //
>     for (long i = 0; i < 5; i++) {

>       if (val0(i).ne(item)) {
>          // error
>       }
>     }

description:
The Vector class is a container class that can hold an array of objects, such as Char, String, etc. Vector provides the functionality of a standard C++ vector, such as random indexing, supports dynamic resizing, and even allows you to read/write the data from an Sof file as a single Vector object.
dependencies:

- DstrBase
- DoubleLinkedList
- Long
- String
- Char
- Console

public constants:

- define the class name:

      static const SysString CLASS_NAME = L"Vector";

- i/o related constants:

      static const SysString DEF_PARAM = L"values";

      static const SysString BLOCK_START_STR = L"{";

      static const SysString BLOCK_DELIM_STR = L"}, {";

      static const SysString BLOCK_END_STR = L"}";

      static const SysString BLOCK_TERM_STR = L";\n";

      static const long static const long SKIP_TABLE_FREQUENCY = 1000;

      static const long static const long SKIP_TABLE_SKIP = 100;

      static const long SKIP_TABLE_SIZE = sizeof(int32) * (SKIP_TABLE_FREQUENCY / SKIP_TABLE_SKIP);

- i/o data buffering lengths:

      static const long TEXT_WRITE_SIZE = 512;

- default values and arguments:

      static const long DEF_LENGTH = 0;
      static const long DEF_END_POS = -1;

error codes:

- general Vector class error:

      static const long ERR = 40900;

      static const long ERR_WMODE = 40901;

protected data:

- vector elements :

      TObject* v_d;

- number of elements of this vector:

       Long length_d;

- the maximum number of elements:

      Long capacity_d;

- mode of write:

      boolean write_partial_d;

- the end index of the sof being written:

      long end_pos_d;

- the position in sof to write the length:

      long len_pos_d;

- debugging parameters:

      static Integral::DEBUG debug_level_d;

- 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 VectorDiagnose.h in order to avoid the issues related with the preprocessing of the diagnose code

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      static boolean setDebug(Integral::DEBUG debug_level);

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Vector();

      Vector(long length = DEF_LENGTH);

      Vector(const Vector<TObject>& copy_Vector);

- assign methods:

      boolean assign(const Vector<TObject>& copy_Vector);

- operator= methods:

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

- equality methods:

      boolean eq(const Vector<TObject>& compare_Vector) const;

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

      long sofSize() const;

      boolean read(Sof& sof_a, long tag_a);

      boolean write(Sof& sof_a, long tag_a) const;

      boolean read(Sof& sof_a, long tag_a, const String& name_a);

      boolean write(Sof& sof_a, long tag_a, const String& name_a) const;

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

      boolean writeData(Sof& sof, const String& pname) 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);

      boolean clear();

class-specific public methods:

- assign methods:

      boolean assign(TObject& arg);

- equality methods:

      boolean ne(const Vector<TObject>& compare_Vector) const;

- partial i/o methods:

      boolean readStart(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = true);

      boolean readPartialData(Sof& sof, long start_pos, long num_elem, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean readTerminate(Sof& sof);

      long writeStart(Sof& sof, const String& pname = DEF_PARAM);

      boolean writePartialData(Sof& sof, long start_pos, long num_elem);

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

- item access methods:

      TObject& operator()(long index_a);

      const TObject& operator()(long index_a) const;

- size-related methods:

      long length() const;

      long getCapacity() const;

      long getVectorSize(long offset_a, Sof& sof_a);

      long getVectorSize(Sof& sof, long tag, const String& name = name(), const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = true);

- resize methods:

      boolean setLength(long length, boolean preserve_values = true);

      boolean setCapacity(long capacity, boolean preserve_values = true);

- data manipulation methods:

      boolean move(const Vector<TObject>& source_vector, long num_elements, long source_offset, long dest_offset);

      boolean shift(const Vector<TObject>& source_vector, long delta);

      boolean shift(long delta);

      boolean concat(const Vector<TObject>& v2);

      boolean concat(const Vector<TObject>& v1, Vector<TObject>& v2);

      boolean concat(const TObject& obj);

      boolean deleteRange(const Vector<TObject> arg, long offset, long num_elements);

      boolean deleteRange(long offset, long num_elements);

      boolean setRange(long offset, long num_elements, const TObject& value);

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

- item location and containment methods:

      long first(const TObject& value, long start_pos = Integral::NO_POS) const;

      long last(const TObject& value, long end_pos = Integral::NO_POS) const;

      boolean contains(long& index, const TObject* value) const;

      boolean contains(const TObject* value) const;

- apply methods: methods to apply an external function to each element in the Vector

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

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

private methods:

- sort methods:

      boolean randQuickSort(Integral::ORDER sort_order);

      boolean insertionSort(Integral::ORDER sort_order);

friend classes:

    friend class VectorDiagnose;

examples:

- This example shows how to construct a vector and check if two vectors are equal:

      #include <Char.h>
      #include <Vector.h>

      int main () {

        // prepare items for the Vector
        //
        Char item(L'a');

        // declare a Vector and assign all the items to be 'a'
        //
        Vector<Char> char_vector(5);
        char_vector.assign(item);

        if((!(char_vector.length() != (long)5)) || (char_vector(0).ne(item))) {

          // exit
          //
          Integral::exit();

        }

        // copy the Vector
        //
        Vector<Char> copy_char_vector(char_vector);

        // see if these Vectors are equivalent
        //
        if(!char_vector.eq(copy_char_vector)) {

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

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

notes:

- there is no memory allocation mode for the Vector class. Vector is always in SYSTEM mode.
- A USER mode Vector can be created by using the Vector<Node<TObject>> construct, but be weary that the setLength method does not cause memory leaks.
- the partial read and write methods should be called together so as to complete the read/write. The readStart method allocates an sofParser object, which is used by the partial read method.
- 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.
- To enable efficient random access to partial i/o in binary mode, we must write marker blocks every so often so that we can quickly skip through the file.
  Before element 0, I will write 40 bytes. These 40 bytes are 10 long integers, n0..n9.
  n0 is the location of element 100.
  n1 is the location of element 200.
  . . .
  n9 is the location of the next skip table.
  Before element 1000 I will write another 40 bytes, with skips to 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, and the table before element 2000.