name: MVector
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_math_vector.a

>     #include <MVector.h>

>     MVector();
>     MVector(const MVector& arg);
>     MVector(long len);
>     boolean setLength(long len, boolean preserve_values = true);
>     boolean setCapacity(long cap, boolean preserve_values = true);
>     boolean add(const MVector& source_vector);
>     TIntegral min(long& position) const;
>     TIntegral dotProduct(const MVector& vector) const;
>     TIntegral norm(const MVector& vector) const;

quick start:

>     MVector<Double, double> val0;
>     MVector<Double, double> val1;
>     MVector<Double, double> vsum;

>     double dotp;
>     double norm_val;
>     double min_val;
>     long pos;

>     val0.assign(L"1, 3, 5, 7");
>     val0.add(2);
>     val1.assign(L"2, 4, 6, 8, 10");
>     val1.setLength(4);

>     vsum.add(val0, val1);

>     dotp = val0.dotProduct(val1);
>     norm_val = val1.norm();
>     min_val = val1.min(pos);

description:
The MVector class is the base class of the vector classes. It includes the commonly used mathematical, logical, dsp and linear algebra methods for vectors. All the other vector classes are derived from it. A vector object can read itself from (or write itself to) a sof file. The MVector methods are not supposed to be used by the user directly. They are designed for the other vector classes and the MMatrix templates to use.
dependencies:

- Byte
- Short
- Long
- Llong
- Ulong
- Ushort
- Ullong
- Float
- Double
- String
- MVectorMethods

public constants:

- define the class name:

      static const String CLASS_NAME = L"MVector";

- i/o related constants:

      static const String DEF_PARAM = L"value";

- i/o data buffering lengths:

      static const long TEXT_READ_SIZE = 128;
      static const long TEXT_PARTIAL_READ_SIZE = 33;
      static const long TEXT_WRITE_SIZE = 512;

- define the default value(s) of the class data:

      static const TIntegral DEF_VALUE = TScalar::DEF_VALUE;

      static const long DEF_LENGTH = 0;

- default arguments to methods:

      static const TIntegral DEF_OFFSET = (TIntegral)0;

      static const TIntegral DEF_INCR = (TIntegral)1;

      static const unichar DEF_DELIM = L',';

      static const String DEF_DELIM_STR = L", ";

error codes:

- error code indicating MVector class general error:

      static const long ERR = 22000;

      static const long ERR_LEN = 22001;

protected data:

- vector elements:

      TScalar* v_d;

- the number of elements of this vector:

      Long length_d;

- the maximum number of elements:

      Long capacity_d;

- debug level:

      static Integral::DEBUG debug_level_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG level);

- debug methods:

      boolean debug(const unichar* message) const;

      static boolean setDebug(Integral::DEBUG level);

- destructor/constructor(s):

      ~MVector();

      MVector();

      MVector(const MVector& arg);

- assign methods:

      template<class TAScalar, class TAIntegral>
      boolean assign(const MVector<TAScalar, TAIntegral>& arg);

- operator= methods:

      these methods are omitted because they are defined in
      the classes that instantiate this template

- i/o methods:

      long sofSize() 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, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = true);

      boolean writeData(Sof& sof, const String& name) const;

- equality methods:

      boolean eq(const MVector& vector) const;

- memory management methods:

      the new and delete methods are omitted because they are
      defined in the classes that instantiate this template

      boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);

class-specific public methods:

- debug methods:

      boolean debug(const String& name, const unichar* message) const;

- constructors:

      MVector(long len);

- assign methods:

      boolean assign(TIntegral arg);

      boolean assign(long length, TIntegral arg);

- array conversion methods:

      template<class TAIntegral> boolean assign(long num_elem, const TAIntegral* arg)

      boolean assign(long num_elem, const String* arg)

- conversion methods from string using parsing:

      boolean assign(const String& arg, unichar delim = DEF_DELIM);

      boolean assign(const unichar* arg, unichar delim = DEF_DELIM);

- conversion methods to string:

      boolean get(String& arg, const String& delim = DEF_DELIM_STR) const;

      boolean get(String& arg, const unichar* delim) const;

- swap methods: swap the current vector with the input vector

      boolean swap(MVector& arg);

- partial i/o methods:

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

      long 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);

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

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

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

- memory size method:

      long memSize() const;

- equality and comparison methods:

      boolean eq(TIntegral arg) const;

      boolean ne(const MVector& vector) const;

      boolean ne(TIntegral value) const;

      boolean lt(TIntegral value) const;

      boolean le(TIntegral value) const;

      boolean gt(TIntegral value) const;

      boolean ge(TIntegral value) const;

      boolean operator == (TIntegral arg) const;

      boolean operator != (TIntegral arg) const;

      boolean operator < (TIntegral arg) const;

      boolean operator <= (TIntegral arg) const;

      boolean operator > (TIntegral arg) const;

      boolean operator >= (TIntegral arg) const;

      boolean almostEqual(const MVector& vector, double percent = Integral::DEF_PERCENTAGE, double bound = Integral::DEF_BOUND) const;

      boolean almostEqual(TIntegral value, double percent = Integral::DEF_PERCENTAGE, double bound = Integral::DEF_BOUND) const;

- operator overload methods:

      TScalar& operator()(long index_a);

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

      long length() const;

      long getCapacity() const;

- resize methods:

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

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

- bitwise methods:

      boolean band(const MVector& v2);

      boolean band(const MVector& v1, const MVector& v2);

      boolean band(TIntegral value;)

      boolean band(const MVector& v1, TIntegral value);

      boolean bor(const MVector& v2;)

      boolean bor(const MVector& v1, const MVector& v2);

      boolean bor(TIntegral value);

      boolean bor(const MVector& v1, TIntegral value);

      boolean bxor(const MVector& v2);

      boolean bxor(const MVector& v1, const MVector& v2);

      boolean bxor(TIntegral value);

      boolean bxor(const MVector& v1, TIntegral value);

      boolean brs(TIntegral increment);

      boolean brs(const MVector& v1, TIntegral increment);

      boolean bls(TIntegral increment)

      boolean bls(const MVector& v1, TIntegral increment);

      boolean bcmpl(const MVector& v1);

      boolean bcmpl();

- algebraic methods:

      boolean add(const MVector& vector);

      boolean add(const MVector& v1, const MVector& v2);

      boolean add(TIntegral value);

      boolean add(const MVector& vector, TIntegral value);

      boolean sub(const MVector& vector);

      boolean sub(const MVector& v1, const MVector& v2);

      boolean sub(TIntegral value);

      boolean sub(const MVector& vector, TIntegral value);

      boolean mult(const MVector& vector);

      boolean mult(const MVector& v1, const MVector& v2);

      boolean mult(TIntegral value);

      boolean mult(const MVector& vector, TIntegral value);

      boolean div(const MVector& vector);

      boolean div(const MVector& v1, const MVector& v2);

      boolean div(TIntegral value);

      boolean div(const MVector& vector, TIntegral value);

      boolean mod(const MVector& vector);

      boolean mod(const MVector& v1, const MVector& v2);

      boolean mod(TIntegral value);

      boolean mod(const MVector& vector, TIntegral value);

- common mathematical methods:

      boolean pow(double y);

      boolean pow(const MVector& x, double y);

      boolean exp();

      boolean exp(const MVector& vector);

      boolean exp2();

      boolean exp2(const MVector& vector);

      boolean exp10();

      boolean exp10(const MVector& vector);

      boolean factorial();

      boolean factorial(const MVector& x);

      boolean log();

      boolean log(const MVector& vector);

      boolean log1p();

      boolean log1p(const MVector& vector);

      boolean log2();

      boolean log2(const MVector& vector);

      boolean log10();

      boolean log10(const MVector& vector);

- sorting and indexing methods:

      boolean sort(Integral::ORDER order = Integral::DEF_ORDER);

      boolean sort(const MVector& vector, Integral::ORDER order = Integral::DEF_ORDER);

      boolean index(VectorLong& sort_index);

      boolean randperm(long size);

- mathematical limits, ceiling, floor and rounding methods:

      boolean abs();

      boolean abs(const MVector& vector);

      TIntegral max() const;

      TIntegral max(long& position) const;

      TIntegral min() const;

      TIntegral min(long& position) const;

      double minMag() const;

      double minMag(long& position) const;

      double maxMag() const;

      double maxMag(long& position) const;

      boolean neg();

      boolean neg(const MVector& vector);

      boolean round();

      boolean round(const MVector& vector);

      boolean ceil();

      boolean ceil(const MVector& vector);

      boolean rceil();

      boolean rceil(const MVector& vector);

      boolean floor();

      boolean floor(const MVector& vector);

      boolean rfloor();

      boolean rfloor(const MVector& vector);

      boolean fraction();

      boolean fraction(const MVector& vector_a);

      boolean sign();

      boolean sign(const MVector& vector);

- trigonometric methods:

      boolean sin();

      boolean sin(const MVector& vector);

      boolean sinh();

      boolean sinh(const MVector& vector);

      boolean cos();

      boolean cos(const MVector& vector);

      boolean cosh();

      boolean cosh(const MVector& vector);

      boolean tan();

      boolean tan(const MVector& vector);

      boolean tanh();

      boolean tanh(const MVector& vector);

      boolean asin();

      boolean asin(const MVector& vector);

      boolean asinh();

      boolean asinh(const MVector& vector);

      boolean acos();

      boolean acos(const MVector& vector);

      boolean acosh();

      boolean acosh(const MVector& vector);

      boolean atan();

      boolean atan(const MVector& vector);

      boolean atanh();

      boolean atanh(const MVector& vector);

- ramp function generation methods:

      boolean ramp(TIntegral offset = DEF_OFFSET, TIntegral incr = DEF_INCR);

      boolean ramp(TIntegral offset, TIntegral incr, TIntegral end);

- square methods:

      boolean sqrt();

      boolean sqrt(const MVector& x);

      boolean square();

      boolean square(const MVector& x);

- inverse methods:

      boolean inverse();

      boolean inverse(const MVector& x);

- vector to scalar mathematical methods:

      TIntegral sum() const;

      TIntegral sumSquare() const;

      TIntegral mean() const;

      TIntegral rms() const;

      TIntegral var() const;

      TIntegral stdev() const;

      TIntegral dotProduct(const MVector& vector) const;

      TIntegral norm() const;

      TIntegral distance(const MVector& vector) const;

      TIntegral distanceSquare(const MVector& vector) const;

      long numEqual(TIntegral test_value) const;

      long numNotEqual(TIntegral test_value) const;

- dsp methods:

      boolean limit(TIntegral min_val, TIntegral max_val);

      boolean limit(TIntegral min_val, TIntegral max_val, const MVector& vector);

      boolean limitMin(TIntegral min_val);

      boolean limitMin(TIntegral min_val, const MVector& vector);

      boolean limitMax(TIntegral max_val);

      boolean limitMax(TIntegral max_val, const MVector& vector);

      boolean limitMag(TIntegral cmp_val, TIntegral new_val);

      boolean limitMag(TIntegral cmp_val, TIntegral new_val, const MVector& vector);

      boolean centerClip(TIntegral min_val, TIntegral max_val);

      boolean centerClip(TIntegral min_val, TIntegral max_val, const MVector& vector);

- random number generation methods:

      boolean rand(Random& generator = Random::GLOBAL_UNIFORM);

      boolean rand(TIntegral min_val, TIntegral max_val, Random& generator = Random::GLOBAL_UNIFORM);

      boolean grand(TIntegral mean, TIntegral stdev, Random& generator = Random::GLOBAL_GAUSSIAN);

- position operation methods:

      boolean move(const MVector& vector, long num_elements, long source_offset, long dest_offset);

      boolean shift(long delta);

      boolean shift(const MVector& vector, long delta);

      boolean concat(const MVector& v2);

      boolean concat(const MVector& v1, const MVector& v2);

      boolean deleteRange(long offset, long num_elements);

      boolean deleteRange(const MVector& v1, long offset, long num_elements);

      boolean setRange(long offset, long num_elements, Integral value);

- search, ordering and reverse methods:

      long first(TIntegral value, long start_pos = Integral::NO_POS);

      long last(TIntegral value, long end_pos = Integral::NO_POS);

      boolean reorder(const MVector& indexes);

      boolean reorder(const MVector& arg, const MVector& indexes);

      boolean reverse();

private methods:

- apply methods:

      boolean apply(const MVector& v_a, TIntegral (TScalar::*method_a));

      template<class TAScalar, class TAIntegral> boolean apply(const MVector& v_a, const MVector<TAScalar, TAIntegral>& arg2, TIntegral (TScalar::*method_a));

      boolean apply(const MVector& v_a, TIntegral arg2, TIntegral (TScalar::*method_a));

      boolean apply(TIntegral arg2, boolean (TScalar::*method) (TIntegral) const) const;

examples:

- This example shows how to use the i/o methods for a MVector<Long, long> object

             MVector<Long, long> val0;
             MVector<Long, long> val1;

             val0.assign(L"1, 2, 3, 4, 5");
             val1.assign(L"2, 4, 6");

             String file_name(L"foo");
             Sof tmp_file0;
             tmp_file0.open(file_name, File::WRITE_ONLY, File::TEXT);

             // write the values
             //
             val0.write(tmp_file0, (long)0);
             val1.write(tmp_file0, (long)1);

             // close the files
             //
             tmp_file0.close();

             // open the files in read mode
             //
             tmp_file0.open(file_name);

             // read the values back in
             //
             if (!val1.read(tmp_file0, (long)0) || (!val1.almostEqual(val0))) {
                  val0.debug(L"val0");
                  val1.debug(L"val1");
                  return Error::handle(val0.name(), L"read-text", Error::TEST,
                                       __FILE__,__LINE__);
             }
             // close the files
             //
             tmp_file0.close();

- This example shows how to do some basic mathematical, logical and dsp operations for MVector objects

             MVector<Double, double> val0;
             MVector<Long, long>val1;
             MVector<Double, double> val2;

             double mean;
             double variance;
             double sum;

             val0.assign(L"45.21, 38.23, 52.56, 47.80");
             val0.round();
             val1.assign(val0);

             val2.log(val0);

             val1.limit(40, 50);
             if (!val1.gt(39)){
                return Error::handle(val0.name(), L"gt", Error::TEST, __FILE__, __LINE__);
             }
             mean = val0.mean();
             variance = val0.var();
             sum = val0.sum();

notes:

- Each vector has both "length" and "capacity". Capacity needs to be changed only when we want to change the allocated memory for the vector object. Length shows number of valid scalar objects in the vector.
- Some methods in this template class are also template functions, such as assign, add, sub, mult, and div. This means that these functions accept any Vector type as input, so you can assign a VectorFloat to a VectorLong, subtract a VectorShort from a VectorDouble, etc. For more information see the library level documentation.
- The setDebug method for this class is static because the debug_level is shared across all objects of this class type.
- We implemented generalized dotProduct method. For complex vectors it conjugates the elements of the second vector.
- While friend functions are generally discouraged in the ISIP environment, they are used in the MVector class to circumvent the template delayed compilation problem.