name: Mask : public AlgorithmBase

synopsis:

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

#include <Mask.h>

Mask(ALGORITHM algorithm = DEF_ALGORITHM);
Mask(const Mask& arg);
boolean eq(const Mask& arg);
boolean setAlgorithm(ALGORITHM algorithm);
boolean set(const VectorByte& mask);
boolean set(const String& source);

quick start:

VectorFloat data(L"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,48,32,32,0,32,-32,16");
VectorFloat output;
String mask_str(L"0-3, 14-19, 21");
Mask mask(mask_str);
mask.compute(output, data);

description:

The Mask class is used to extract or remove the indicated elements from the input data. Two algorithms are supported: SELECT and REMOVE. When the algorithm is SELECT, the Mask class will output the elements of input data which are identified in the mask string. When algorithm is REMOVE, the Mask class will remove those elements which are identified in the mask string.

The table below summarizes the options available for this class:

The mask string can be specified using a fairly flexible mixture of numbers and ranges (e.g, "1, 3, 5", "0-3, 4, 7-9"), making it easy to specify ranges of elements. The range "7-9" denotes elements 7, 8, and 9 (inclusive).

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Mask";

define the algorithm choices:

enum ALGORITHM { SELECT = 0, REMOVE, DEF_ALGORITHM = SELECT };

define the implementation choices:

enum IMPLEMENTATION { INDEX = 0, DEF_IMPLEMENTATION = INDEX };

define internal on/off value(s):

static const byte OFF = 0;

static const byte ON = 1;

define the static NameMap objects:

static const NameMap Mask::ALGO_MAP(L"SELECT, REMOVE");

static const NameMap Mask::IMPL_MAP(L"INDEX");

define i/o related constants:

static const String Mask::DEF_PARAM = L"";

static const String Mask::PARAM_ALGORITHM = L"algorithm";

static const String Mask::PARAM_IMPLEMENTATION = L"implementation";

static const String Mask::PARAM_MASK = L"mask";

error codes:

error codes:
```
static const long ERR = 71200;
```

protected data:

algorithm name:

ALGORITHM algorithm_d;

implementation name:

IMPLEMENTATION implementation_d;

the mask string in source format (what the user supplied):

String source_d;

the mask vector (used internally):

VectorByte mask_d;

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

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods: setDebug method is inherited from the base class
```
boolean debug(const unichar* message) const;
```

destructor/constructor(s):

~Mask();

Mask(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

Mask(const Mask& arg);

assign methods:
```
boolean assign(const Mask& arg);
```
operator= methods:
```
Mask& operator= (const Mask& arg);
```

i/o methods:

long sofSize() const;

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

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

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

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

equality methods:
```
boolean eq(const Mask& arg) 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(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

constructor(s):

Mask(const String& arg);

Mask(const VectorByte& arg);

assign methods:

boolean assign(const String& source);

boolean assign(const VectorByte& mask);

set methods:

boolean setAlgorithm(ALGORITHM algorithm);

boolean setImplementation(IMPLEMENTATION implementation);

boolean set(const String& source);

boolean set(const VectorByte& source);

boolean convert(String& out, const VectorByte& in);

boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

get methods:

ALGORITHM getAlgorithm() const;

IMPLEMENTATION getImplementation() const;

const String& getString() const;

const VectorByte& get() const;

boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation) const;

computational methods:

boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = AlgorithmData::UNKNOWN, long index = DEF_CHANNEL_INDEX);

boolean compute(VectorComplexFloat& output, const VectorComplexFloat& input, AlgorithmData::COEF_TYPE input_coef_type = AlgorithmData::UNKNOWN, long index = DEF_CHANNEL_INDEX);

AlgorithmBase interface contract methods:

boolean assign(const AlgorithmBase& arg);

boolean eq(const AlgorithmBase& arg) const;

const String& className() const;

boolean apply(Vector<AlgorithmData>& output, const Vector<AlgorithmData>& input);

boolean setParser(SofParser* parser);

private methods:

common i/o methods:

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

boolean writeDataCommon(Sof& sof, const String& pname) const;

algorithm-specific computation methods:

boolean computeSelectIndex(VectorFloat& output, const VectorFloat& input);

boolean computeRemoveIndex(VectorFloat& output, const VectorFloat& input);

insert method:

boolean insert(VectorByte& src, long start_index, long num_elem, byte mode);

examples:

Here's a quick example that demonstrates the selection and removal of the elements in the input vector:

// isip include files
//
#include <Mask.h>

// main program starts here
//
int main(int argc, const char **argv) {

  // declare the local variables
  //
  VectorFloat input;
  VectorFloat output;
  String str;

  // set the variables
  //
  input.assign(L"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,48,32,32,0,32,-32,16");
  str.assign(L"3, 14-19, 21");
  Mask mask(str);
  
  // set algorithm and implementation
  //
  mask.setAlgorithm(Mask::SELECT);
  mask.setImplementation(Mask::INDEX);

  // compute the output that contains the selected elements
  //
  if(!mask.compute(output, input)) {
    Error::handle(mask.name(), L"compute", Error::TEST, __FILE__,
                  __LINE__);
  }
  
  // print the input and the output
  //
  input.debug(L"input:");
  mask.debug(L"mask:");
  output.debug(L"output:");

  str.assign(L"0-2, 4-13, 20");
  
  // set algorithm and elements that will be removed
  //
  mask.setAlgorithm(Mask::REMOVE);
  mask.set(str);

  // compute the output that contains the elements other than the
  // selected ones
  //
  if(!mask.compute(output, input)) {
    Error::handle(mask.name(), L"compute", Error::TEST, __FILE__,
                  __LINE__);
  }
    
  // print the input and the output
  //
  input.debug(L"input:");
  mask.debug(L"mask:");
  output.debug(L"output:");

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

notes:

none.