cvrGenericMatrix.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2004
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 * Copyright (C) 2007-2008
 * Pablo Alvarado
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * \file   cvrGenericMatrix.h
 *         Contains a template class to describe matrices of data, in a way
 *         that each row can be accessed as a cvr::genericVector
 * \author Pablo Alvarado
 * \date   09.04.1999
 *
 * $Id: cvrGenericMatrix.h,v 1.19 2007/09/15 03:36:57 alvarado Exp $
 */

#ifndef _CVR_GENERIC_MATRIX_H_
#define _CVR_GENERIC_MATRIX_H_

#include "cvrContainer.h"
#include "cvrGenericVector.h"
#include "cvrPoint.h"
#include "cvrRectangle.h"
#include "cvrAssert.h"
#include "cvrResizeType.h"
#include "cvrDebugIterator.h"
#include "cvrDeprecated.h"

namespace cvr {
  /**
   * Container class for generic matrices.
   *
   * The cvr::genericMatrix class is a container class implemented as a
   * template.
   *
   * The cvr::genericMatrix class allows the representation of \e n x \e m
   * matrices of any type that does not use any form of dynamic memory
   * allocation.  The rows will be indexed between 0 and n-1, and the columns
   * between 0 and m-1.
   *
   * All types defined in cvrTypes.h use static members and can be contained
   * by the cvr::genericVector and cvr::genericMatrix classes.
   *
   * If you need to create a genericMatrix of floats with 20 rows and
   * 15 columns, all elements initialized with an initial value of
   * 4.27 just create it:
   *
   * \code
   * cvr::genericMatrix<float> myMat(20,15,4.27f) // creates genericMatrix
   *                                              // with 300 elements
   *                                              // all initialized with 4.27f
   * \endcode
   *
   * To access the cvr::genericMatrix elements use the access operators.
   * There are many possibilities.  With at(const int row, const int
   * col) it is possible to access an element directly.  With getRow(const
   * int row) you can get the row vector.  You cannot for instance
   * resize nor change the memory referenced in this vector (see
   * cvr::vector::resize).  For example:
   *
   * \code
   * float accu = 0; // initialize accumulator
   * cvr::genericMatrix<float> myMat(20,15,4.27f)
   * cvr::vector<float> myVct;
   *
   * for (int j = 0; j < myMat.rows(); j++) {
   *   for (int i = 0; i < myMat.columns(); i++) {
   *   tmp += myMat.at(j,i); // access each element of the genericMatrix:
   *                         // j is the row and i the column
   *   }
   * }
   *
   * myMat.getRowCopy(5,myVct); // copy the sixth row in myVct!
   * myVct.resize(6);           // Valid, the vector has its own memory!
   * myMat.getRow(5).resize(6)  // ERROR!! the vector is not resizable!
   *
   * \endcode
   *
   * The image representation in the CVR-Lib is derived indirectly from the
   * cvr::genericMatrix class.  It is quite confusing to use first the
   * y-coordinate and then the x-coordinate to access the image elements.  To
   * avoid confusion use the cvr::ipoint class to access the elements of the
   * genericMatrix:
   *
   * \code
   *
   * cvr::channel8 aChannel(20,15); // creates an 8bit image
   * cvr::channel8::value_type tmp; // tmp is of the element type of the
   *                                // channel8!
   * cvr::ipoint p;
   *
   *
   * for (p.y = 0; p.y < aChannel.rows(); p.y++) {
   *   for (p.x = 0; p.x < aChannel.columns(); p.x++) {
   *   tmp += aChannel.at(p); // access each element of the genericMatrix:
   *                          // equivalent to: tmp += aChannel.at(p.y,p.x)!
   *   }
   * }
   *
   * \endcode
   *
   * Matrices in the CVR-Lib use always a continuous block of memory, which
   * allows efficient elementwise operations.  The previous version of the
   * library (LTI-Lib) provided a lined-mode of the matrices, which is now
   * contained in its own class cvr::genericSubmatrix.
   *
   * @see cvr::genericSubmatrix, cvr::matrix
   *
   * The genericMatrix has following methods:
   * - Constructors Constructors
   *   -  You can construct an empty genericMatrix with the default constructor
   *      (genericMatrix()).
   *   - If you know the number of rows and columns use
   *     genericMatrix(const int rows,const int columns,const T&
   *     initialValue)
   * - Access members
   *   - at(), operator[]()
   *   - The rows() member returns the number of rows of the genericMatrix.
   *   - The columns() member returns the number of columns of the
         genericMatrix.
   * - Fill and Copy members
   *   - With the fill() members you can fill the genericMatrix with a given
   *     constant value or with values taken from other matrices.
   *   - With the copy() member you can copy another genericMatrix.
   *   - You can specify, that the genericMatrix should be used just as a
   *     wrapper-object to access external memory regions: useExternData().
   *     To check if a genericMatrix is a wrapper-object you can use
   *     ownsData().
   * - Iterators
   *   - It is possible to iterate within the genericMatrix by making use of
   *     the genericMatrix iterators.  (see begin() for more information)
   *   - Instead of reverse_iterators as in the STL we use iterators
   *     going backwards, due to faster execution times (see
   *     inverseBegin() for more information)
   *
   * @ingroup gLinearAlgebra
   * @ingroup gAggregate
   */
  template<class T>
  class genericMatrix : public container {
  public:

    /**
     * \name Internal types and classes
     */
    //@{

    /**
     * Exception thrown when a constant reference is violated.
     */
    typedef cvr::constReferenceException constReferenceException;

    /**
     * Type of the contained data
     */
    typedef T value_type;

    /**
     * Return type of the size() member
     */
    typedef ipoint size_type;

    /**
     * Vector type of each row
     */
    typedef genericVector<T> row_type;

#   ifdef NDEBUG
    /**
     * Iterator type (allows read and write operations)
     *
     * The use of the iterator classes is similar to the iterators of
     * the STL (Standard Template Library). See cvr::genericMatrix::begin()
     * for an example .
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done,
     * and the iterators are sometimes a factor 10 faster than the
     * debug iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a genericMatrix use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than "at()").
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) over the
     * postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     */
    typedef T* iterator;

    /**
     * Constant iterator type (allows read-only operations)
     *
     * The use of the iterator classes is similar to the iterators of
     * the STL (Standard Template Library). See cvr::genericMatrix::begin()
     * for an example.
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done,
     * and the iterators are sometimes a factor 10 faster than the
     * debug iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a genericMatrix use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than "at()").
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) instead
     * of the postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     */
    typedef const T* const_iterator;

#   else

    /**
     * Iterator type (allows read and write operations)
     *
     * The use of the iterator classes is similar to the iterators of
     * the STL (Standard Template Library). See cvr::genericMatrix::begin()
     * for an example .
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done,
     * and the iterators are sometimes a factor 10 faster than the
     * debug iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a genericMatrix use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than "at()").
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) over
     * the postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     */
    typedef internal::debugIterator<genericMatrix<T>,false> iterator;

    /**
     * Constant iterator type (allows read-only operations)
     *
     * The use of the iterator classes is similar to the iterators of
     * the STL (Standard Template Library). See cvr::genericMatrix::begin()
     * for an example.
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done,
     * and the iterators are sometimes a factor 10 faster than the
     * debug iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a genericMatrix use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than "at()").
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) instead
     * of the postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     */
    typedef internal::debugIterator<genericMatrix<T>,true> const_iterator;
#   endif
    //@}

    /**
     * Default constructor creates an empty genericMatrix
     */
    genericMatrix();

    /**
     * Create a \a rows x \a cols genericMatrix with uninitialized elements.
     *
     * \warning This is an interface change with the previous library.
     * It has been done to be consistent with the more basic features
     * of the C++ language.  If you write for example \c int \c c; ,
     * the content of \c c is not defined, and in the same way, if you
     * want a vector with initialized data, you have to specify
     * explicitely the value with which the elements have to be
     * initialized.
     *
     * @param rows number of rows of the genericMatrix
     * @param cols number of columns of the genericMatrix
     */
    genericMatrix(const int rows,const int cols);

    /**
     * Create a \a size.x x \a size.y genericMatrix with
     * uninitialized elements.
     *
     * \warning This is an interface change with the previous library.
     * It has been done to be consistent with the more basic features
     * of the C++ language.  If you write for example \c int \c c; ,
     * the content of \c c is not defined, and in the same way, if you
     * want a vector with initialized data, you have to specify
     * explicitely the value with which the elements have to be
     * initialized.
     *
     * @param size size of the matrix (size.x columns and size.y rows)
     */
    genericMatrix(const size_type& size);

    /**
     * Create a \a rows x \a cols genericMatrix and
     * initializes all elements with \a iniValue.
     *
     * @param rows number of rows of the genericMatrix
     * @param cols number of columns of the genericMatrix
     * @param iniValue all elements will be initialized with this value
     */
    genericMatrix(const int rows,const int cols,const T& iniValue);

    /**
     * This constructor creates a \a size.y x \a size.x
     * GenericMatrix and initializes all elements with \a iniValue
     *
     * @param size the size of the genericMatrix  (size.x is the number of
     *             columns and size.y the number of rows)
     * @param iniValue all elements will be initialized with this value
     */
    genericMatrix(const size_type& size,const T& iniValue);

    /**
     * Create a \a rows x \a cols genericMatrix and initialize all
     * elements with the data pointed by \a data.
     *
     * The first \a cols-elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param rows number of rows of the genericMatrix
     * @param cols number of columns of the genericMatrix
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     */
    genericMatrix(const int rows,const int cols,const T data[]);

    /**
     * Create a \a dim.y x \a dim.x genericMatrix and initialize all
     * elements with the data pointed by \a data.
     *
     * The first \a dim.x -elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param dim matrix dimensions
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     */
    genericMatrix(const size_type& dim,const T data[]);

    /**
     * Create a \a rows x \a cols genericMatrix and use the given \a data as
     * if it was given through the useExternData().
     *
     * @see useExternData()
     *
     * The first \a cols-elements of the data will be copied on the
     * first row, the next ones on the second row and so on.
     *
     * \note Please observe that the third argument makes a huge difference to
     *       the constructors that do not have it.  Here the data is \b not
     *       copied, just a reference is kept.  Without the third argument, the
     *       data is always copied.
     *
     * @param rows number of rows of the genericMatrix
     * @param cols number of columns of the genericMatrix
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this to be \c ConstantReference
     */
    genericMatrix(const int rows,const int cols,
                  T data[],
                  const eConstantReference constRef);


    /**
     * Create a \a rows x \a cols genericMatrix and use the given \a data as
     * if it was given through the useExternData().
     *
     * @see useExternData()
     *
     * The first \a cols-elements of the data will be copied on the
     * first row, the next ones on the second row and so on.
     *
     * \note Please observe that the third argument makes a huge difference to
     *       the constructors that do not have it.  Here the data is \b not
     *       copied, just a reference is kept.  Without the third argument, the
     *       data is always copied.
     *
     * @param theSize size of the matrix
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this to be \c ConstantReference
     */
    genericMatrix(const size_type& theSize,
                  T data[],
                  const eConstantReference constRef);

    /**
     * Copy constructor.
     *
     * Create this genericMatrix as a copy of another genericMatrix.
     *
     * @param other the genericMatrix to be copied.
     */
    genericMatrix(const genericMatrix<T>& other);


    /**
     * Copy constructor.
     *
     * Create this genericMatrix as a copy of another genericMatrix for this
     * const version, the data will be always copied! 
     *
     * @param other the genericMatrix to be copied.
     * @param fromRow initial row of the other genericMatrix to be copied
     * @param fromCol initial column of the other genericMatrix to be copied
     * @param toRow last row to be copied of the other genericMatrix
     * @param toCol last column to be copied of the other genericMatrix
     *
     * Example:
     * \code
     * cvr::genericMatrix<int> m(4,6,0); // integer genericMatrix with 25
     *                                   // elements
     * // ...
     * // initialize GenericMatrix with:
     * //        0  1  2  3  4  5
     * //        2  1  5  4  0  3
     * //        1  2  1  2  3  2
     * //        3  3  2  1  2  3
     *
     * cvr::genericMatrix<int> sm(m,0,2,1,3)  // last line will lead to
     * //                                 following contents in sm:
     * //        1  2  3
     * //        1  5  4
     * //        2  1  2
     * \endcode
     */
    genericMatrix(const genericMatrix<T>& other,
                  const int fromRow,
                  const int fromCol,
                  const int toRow=MaxIndex,
                  const int toCol=MaxIndex);


    /**
     * Copy constructor.
     *
     * Create this genericMatrix as a copy of a submatrix of another
     * genericMatrix.
     *
     * @param other the genericMatrix to be copied.
     * @param from initial position in the other genericMatrix to be copied
     * @param to last position to be copied of the other genericMatrix
     *
     * Example:
     * \code
     * cvr::genericMatrix<int> m(4,6,0); // integer genericMatrix with 25
     *                                   // elements
     * // ...
     * // initialize GenericMatrix with:
     * //        0  1  2  3  4  5
     * //        2  1  5  4  0  3
     * //        1  2  1  2  3  2
     * //        3  3  2  1  2  3
     *
     * cvr::genericMatrix<int> sm(m,0,2,1,3)  // last line will lead to
     * //                                 following contents in sm:
     * //        1  2  3
     * //        1  5  4
     * //        2  1  2
     * \endcode
     */
    genericMatrix(const genericMatrix<T>& other,
                  const size_type& from,
                  const size_type& to);


    /**
     * Copy constructor.
     *
     * Create this genericMatrix as a copy of another genericMatrix taking only
     * the rows indicated by the vector.
     *
     * The data will be always copied!  Multiple occurence of one row index in
     * \a rows is allowed.
     *
     * @param other the genericMatrix to be copied.
     * @param rows indices of the rows to be copied
     *
     * Example:
     * \code
     * cvr::vector<int> rows(2);
     * // initialize with
     * // 1 3
     * cvr::genericMatrix<int> m(4,6,0); // integer genericMatrix with 25
     *                                   // elements
     * // ...
     * // initialize GenericMatrix with:
     * //        0  1  2  3  4  5
     * //        2  1  5  4  0  3
     * //        1  2  1  2  3  2
     * //        3  3  2  1  2  3
     *
     * cvr::genericMatrix<int> sm(m,rows)     // last line will lead to
     * //                                 following contents in sm:
     * //        2  1  5  4  0  3
     * //        3  3  2  1  2  3
     * \endcode
     */
    genericMatrix(const genericMatrix<T>& other,
                  const genericVector<int>& rows);

    /**
     * Destructor
     */
    virtual ~genericMatrix();

    /**
     * Owns this %object the data?
     * returns <em>false</em> if this genericMatrix contains a reference to
     *         extern data.
     */
    inline bool ownsData() const;

    /**
     * If this object does not own its data, this member will create a new
     * memory buffer with the same data and will make this genericMatrix as its
     * owner.  If this genericMatrix already owns its data nothing happens.
     */
    void restoreOwnership();

    /**
     * Reference to extern data.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at (r,c) is equivalent to
     * data[r*columns() + c].
     *
     * The user must take care for memory allocation and deallocation:
     * this object will never delete the given data!.
     *
     * If <em>rows</em> and <em>cols</em> are invalid dimensions, the
     * behaviour will be unpredictible.
     *
     * In case the provided data is the same than the one being used
     * by this matrix, and additionally the provided rows and columns
     * coincide with the dimensions in use, nothing will be changed,
     * not even the ownership of the data.
     *
     * @param rows number of rows
     * @param cols number of columns
     * @param data a pointer to the memory block to be used
     * @param constRef usually you want this to be \c ConstantReference
     *
     * For an example see attach()
     */
    void useExternData(const int rows,const int cols,
                       T data[],
                       const eConstantReference constRef=VariableReference);

    /**
     * Reference to extern data.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at (r,c) is equivalent to
     * data[r*columns() + c].
     * The user must take care for memory allocation and deallocation:
     * this object will never delete the data!.
     * If <em>rows</em> and <em>cols</em> are invalid dimensions, the
     * behaviour will be unpredictible.
     *
     * @param theSize size of the matrix
     * @param data a pointer to the memory block to be used
     * @param constRef usually you want this to be \c ConstantReference
     *
     * For an example see attach()
     */
    inline void 
    useExternData(const size_type& theSize,
                  T data[],
                  const eConstantReference constRef=VariableReference);

    /**
     * Attach extern data to the genericMatrix.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at (r,c) is equivalent to
     * data[r*columns() + c].
     * If <em>rows</em> and <em>cols</em> are invalid dimensions, the
     * behaviour will be unpredictible.
     *
     * The memory will be administrated by this genericMatrix object,
     * and may be deleted if required (genericMatrix deleted or
     * resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param rows number of rows
     * @param cols number of columns
     * @param data a pointer to the memory block to be used
     *
     * Example:
     * \code
     * cvr::genericMatrix<int> myMat;
     * int block1[25];
     * int* block2;
     * block2 = new int[25];
     *
     * myMat.useExternData(5,5,block1); // ok
     * myMat.attach(5,5,block1); // wrong!!! genericMatrix will try
     *                           // to manipulate stack memory:
     *                           // DO NOT DO THIS!!!!!
     * myMat.attach(5,5,block2); // ok!  but do not try to delete the memory
     *                           //      block2!!
     * \endcode
     */
    void attach(const int rows,const int cols,T* data);

    /**
     * Attach extern data to the genericMatrix.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at (r,c) is equivalent to
     * data[r*columns() + c].
     * If <em>rows</em> and <em>cols</em> are invalid dimensions, the
     * behaviour will be unpredictible.
     *
     * The memory will be administrated by this genericMatrix object,
     * and may be deleted if required (genericMatrix deleted or
     * resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param theSize \c x number of columns and \c y number of rows
     * @param data a pointer to the memory block to be used
     *
     * Example:
     * \code
     * cvr::genericMatrix<int> myMat;
     * int block1[25];
     * int* block2;
     * block2 = new int[25];
     * ipoint p(5,5);
     * myMat.useExternData(p,block1); // ok
     * myMat.attach(p,block1); // wrong!!! genericMatrix will try
     *                         // to manipulate stack memory:
     *                         // DO NOT DO THIS!!!!!
     * myMat.attach(p,block2); // ok!  but do not try to delete the memory
     *                         //      block2!!
     * \endcode
     */
    inline void attach(const size_type& theSize,T* data);

    /**
     * Free the data of this object and hand it over to the
     * "receiver". The value of ownsData is also transfered to the
     * receiver. (see Note).
     *
     * This function makes a "memory block transfusion" to another
     * genericMatrix.  It is a very efficient way to make a copy of
     * this genericMatrix, if you don't need the source data anymore!
     *
     * If the current matrix does not own its data, neither will the receiver
     * matrix, which will also be just a wrapper of the same data.
     *
     * If the current matrix is lined, then the other matrix will end as an
     * exact copy if this one, and this one will be emptied after the
     * detachment.  In other words, it works similar like a swap() followed by
     * clear().  In extremely time critical situations you may want to use
     * swap() as it does not need to deallocate any memory of the receiver and
     * is therefore a little bit faster.
     *
     * Please take special care to the memory management issues involved if the
     * current object does not own its data, as its control will still be
     * yours.
     *
     * At the end of the detachment, this genericMatrix will be empty.
     *
     * @param receiver the genericMatrix which will receive the memory
     *        block.  All data of that genericMatrix will be first deleted!
     */
    void detach(genericMatrix<T>& receiver);

    /**
     * Free the data of this object and hand it over to the
     * "receiver". The value of ownsData is also transfered to the
     * receiver. (see Note).
     *
     * This function makes a "memory block transfusion" to a vector by
     * concatenating the rows of the genericMatrix.  It is a very efficient
     * way to move the data of this genericMatrix into a vector, if you don't
     * need the source data anymore!
     *
     * \b Note: If the attach() or useExternData() methods of this
     * genericMatrix have been called before detachment, the same rules for
     * memory management apply now for the \c receiver.
     *
     * At the end of the detachment, this genericMatrix will be empty.
     *
     * @param receiver the genericMatrix which will receive the memory block.
     *                 All data of that genericMatrix will be first deleted!
     */
    void detach(genericVector<T>& receiver);

    /**
     * Exchange (in a fast way) the data between this and the other
     * genericMatrix.
     *
     * Similar to detach(), this method will exchange the complete memory
     * blocks, avoiding an element-wise copy.
     * @param other the genericMatrix with which the data will be exchanged.
     */
    void swap(genericMatrix<T>& other);

    /**
     * Number of rows of the genericMatrix
     */
    inline int rows() const;

    /**
     * Number of columns of the genericMatrix
     */
    inline int columns() const;

    /**
     * Index of the last row (rows()-1)
     */
    inline int lastRow() const;

    /**
     * Index of the last columns (columns()-1)
     */
    inline int lastColumn() const;

    /**
     * Returns the size of the %genericMatrix in a cvr::ipoint structure.
     *
     * @return cvr::ipoint with the number of columns in its
     *         \a x coordinate and the number of rows in its
     *         \a y coordinate.
     */
    inline const size_type& size() const;

    /**
     * Returns a read-only reference to the last index of the matrix
     *
     * @return cvr::ipoint with the number of columns in its
     *         \a x coordinate and the number of rows in its
     *         \a y coordinate.
     */
    inline const size_type& lastIndex() const;

    /**
     * Return iterator to the begin of the genericMatrix.
     *
     * The use of the interators is similar to the iterators of the
     * Standard Template Library (STL).
     * If you need to iterate on all elements of the genericMatrix, you can
     * use following code:
     * \code
     * int tmp,accu;                  // a temporal variable
     * cvr::genericMatrix<int> myMat(10,8,1); // a vector with 10 elements
     * cvr::genericMatrix<int>::iterator it;  // an iterator
     *
     * for (it=myMat.begin();it!=myMat.end();it++) {
     *   tmp = *it;                   // tmp has value of element pointed
     *                                // by the iterator.
     *   accu += tmp;
     *   (*it) = accu;                // change the value in the genericMatrix.
     * }
     * \endcode
     * Please note that if you define \c it as a const_iterator,
     * you can not do something like <code>*it=accu</code>.
     */
    inline iterator begin();

    /**
     * Return first element of the genericMatrix as a const_iterator.
     *
     * Note that you can not change the values of the genericMatrix
     * elements when you use a const_iterator. See also begin() for an example
     */
    inline const_iterator begin() const;

    /**
     * returns iterator to the end of the genericMatrix
     */
    inline iterator end();

    /**
     * returns iterator to the end of the genericMatrix
     */
    inline const_iterator end() const;


    /**
     * This method returns an iterator that points to the \b last
     * valid element of the genericMatrix. It is used for inverse order
     * iteration through the genericMatrix using normal iterators (as opposed
     * to reverse iterators). This has the advantage that iterators
     * going from front to end and in the inverse direction are the
     * same and can thus be compared, copied etc. Further the
     * implementation of reverse_iterators is not as fast as that of
     * iterators and thus not desired in the CVR-Lib.
     *
     * See cvr::genericVector<T>::inverseBegin() for an example.
     */
    inline iterator inverseBegin();

    /**
     * This method returns an iterator that points to the \b last
     * valid element of the genericMatrix. See inverseBegin() for more details.
     */
    inline const_iterator inverseBegin() const;

    /**
     * This method returns an iterator that points to the element \b
     * before the \b first valid element of the genericMatrix. It is used to
     * mark the end for inverse order iteration through the genericMatrix
     * using normal iterators (as opposed to reverse iterators). This
     * has the advantage that iterators going from front to end and in
     * the inverse direction are the same and can thus be compared,
     * copied etc.
     */
    inline iterator inverseEnd();

    /**
     * This method returns an iterator that points to the element \b
     * before the \b first valid element of the genericMatrix.
     */
    inline const_iterator inverseEnd() const;

    /**
     * Change the dimensions of the genericMatrix.
     *
     * @param newRows new number of rows
     * @param newCols new number of columns
     * @param iniValue the initialization value.
     * @param resizeType specifies what should happen with the data of the
     *                   resized matrix.
     *
     * For example:
     * \code
     *   cvr::genericMatrix<int> myMat;  // creates empty genericMatrix
     *   myMat.resize(5,5,0);     // genericMatrix with 5x5 elements
     *                            // initialized with 0
     *   myMat.resize(10,7,2);    // genericMatrix has now 10x7 elements: the
     *                            // submatrix 5x5 at (0,0) has still 0s
     *                            // and the rest have a 2
     *   myMat.resize(20,10,0,cvr::AllocateOnly); // now the genericMatrix has
     *                                            // 20 elements but their
     *                                            // values are unknown.
     *   myMat.resize(5,5,1,Copy); // the genericMatrix has now 5x5
     *                             // elements all initialized with 1
     * \endcode
     *
     * If the resize is possible (see useExternData()), this %object
     * will always owns the data!
     *
     * @see eResizeType
     */
    void resize(const int newRows,const int newCols,
                const T& iniValue,
                const eResizeType resizeType=CopyAndInit);

    /**
     * Change the dimensions of the genericMatrix.
     *
     * @param newDim   new dimensions of the genericMatrix
     * @param iniValue the initialization value.
     * @param resizeType specifies what should happen with the data of the
     *                   resized matrix.
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     *
     * This is equivalent to call
     *   resize(newDim.y,newDim.x,iniValue,resizeType)
     *
     * @see eResizeType
     */
    inline void resize(const size_type& newDim,
                       const T& iniValue,
                       const eResizeType resizeType=CopyAndInit);

    /**
     * Change the dimensions of the genericMatrix.
     *
     * @param newRows new number of rows
     * @param newCols new number of columns
     *
     * The old values will be copied, but the new data will be kept
     * uninitialized.  In principle this is an alias for
     * \c resize(newRows,newCols,T(),Copy).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     */
    inline void resize(const int newRows,const int newCols);

    /**
     * Change the dimensions of the genericMatrix.
     *
     * @param newSize new size of the matrix.
     *
     * The old values will be copied, but the new data will be kept
     * uninitialized.  In principle this is an alias for
     * \c resize(newRows,newCols,T(),Copy).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     */
    inline void resize(const size_type& newSize);

    /**
     * Change the dimensions of the genericMatrix and leave ALL data
     * uninitialized.
     *
     * @param newRows new number of rows
     * @param newCols new number of columns
     *
     * The old values will be discarded and the new data will be kept
     * uninitialized.  In principle this is an alias for
     * \c resize(newRows,newCols,T(),AllocateOnly).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     */
    inline void allocate(const int newRows,const int newCols);

    /**
     * Change the dimensions of the genericMatrix and leave ALL data
     * uninitialized.
     *
     * @param newSize new size of the matrix.
     *
     * The old values will be discarded and the new data will be kept
     * uninitialized.  In principle this is an alias for
     * \c resize(newSize.y, newSize.x, T(), AllocateOnly).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     */
    inline void allocate(const size_type& newSize);

    /**
     * Change the dimensions of the genericMatrix and initialize ALL data
     * with the given value.
     *
     * The old values will be discarded and all data will be initialized with
     * initValue.  In principle this is an alias for \c
     * resize(newRows, newCols, initValue, Init).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     *
     * @param newRows new number of rows
     * @param newCols new number of columns
     * @param initValue value to be assigned to all matrix elements
     */
    inline void assign(const int newRows,
                       const int newCols,
                       const T& initValue);

    /**
     * Change the dimensions of the genericMatrix and initialize ALL data
     * with the given value.
     *
     * The old values will be discarded and all data will be initialized with
     * initValue.  In principle this is an alias for \c
     * resize(newSize.y, newSize.x, initValue, Init).
     *
     * If the resize is possible (see useExternData()), this %object
     * will always own the data!
     *
     * @param newSize new size of the matrix.
     * @param initValue value to be assigned to all matrix elements
     */
    inline void assign(const size_type& newSize,
                       const T& initValue);

    /**
     * Clears the genericMatrix (at the end this will be an empty
     * genericMatrix)
     */
    void clear();

    /**
     * Returns true if the genericMatrix is empty
     */
    inline bool empty() const;

    /**
     * Fills genericMatrix elements with \a iniValue.
     * The fill "area" is limited by \a fromCol,\a toCol,
     * \a fromRow and \a toRow.
     * If these values are out of bounds, they will be (internally)
     * adjusted to correct values.
     *
     * @param iniValue the elements will be initialized with this value
     * @param fromRow  first row of the submatrix to be filled
     * @param fromCol  first column of the submatrix to be filled
     * @param toRow    last row of the submatrix to be filled
     * @param toCol    last column of the submatrix to be filled
    */
    void fill(const T& iniValue,
              const int fromRow=0,
              const int fromCol=0,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex);

    /**
     * Fills genericMatrix elements with \a iniValue.
     * The fill "area" is limited by \a from and \a to
     * points
     * If these values are out of bounds, they will be (internally)
     * adjusted to correct values.
     *
     * @param iniValue the elements will be initialized with this value
     * @param from first position of the submatrix to be filled
     * @param to   last row of the submatrix to be filled
    */
    inline void fill(const T& iniValue,
                     const size_type& from,
                     const size_type& to=size_type(MaxIndex,MaxIndex));

    /**
     * Fills genericMatrix elements with \a iniValue.
     * The fill "area" is limited by \a window.
     * If these values are out of bounds, they will be (internally)
     * adjusted to correct values.
     * @param iniValue the elements will be initialized with this value
     * @param window   the window to be filled
     */
    inline void fill(const T& iniValue,const irectangle& window);

    /**
     * Fills genericMatrix elements with the data pointed by \a data.
     * The fill "area" is limited by \a fromCol,\a toCol,
     * \a fromRow and \a toRow.
     * If these values are out of bounds, they will be (internally)
     * adjusted to correct values.
     *
     * @param data     pointer to the data to be copied.
     * @param fromRow  first row of the submatrix to be filled
     * @param fromCol  first column of the submatrix to be filled
     * @param toRow    last row of the submatrix to be filled
     * @param toCol    last column of the submatrix to be filled
     */
    void fill(const T data[],
              const int fromRow=0,
              const int fromCol=0,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex);

    /**
     * Fills genericMatrix elements with the data pointed by \a data.
     * The fill "area" is limited by \a fromCol,\a toCol,
     * \a fromRow and \a toRow.
     * If these values are out of bounds, they will be (internally)
     * adjusted to correct values.
     *
     * @param data  pointer to the data to be copied.
     * @param from  first position of the submatrix to be filled
     * @param to    last position of the submatrix to be filled
     */
    inline void fill(const T data[],
                     const size_type& from,
                     const size_type& to=size_type(MaxIndex,MaxIndex));

    /**
     * Fills genericMatrix elements with \a iniValue.
     *
     * The fill "area" is limited by \a window.
     *
     * If these values are out of bounds, they will be (internally) adjusted to
     * correct values.
     *
     * @param data   pointer to the data to be copied
     * @param window the window to be filled
     */
    inline void fill(const T data[],const irectangle& window);

    /**
     * Fills this genericMatrix between the "from's" and "to's" with
     * the contents of the genericMatrix \a mat starting at
     * \a startAtRow and \a startAtCol
     *
     * @param mat      the genericMatrix with the data to be copied
     * @param fromRow  first row of the submatrix to be filled
     * @param fromCol  first column of the submatrix to be filled
     * @param toRow    last row of the submatrix to be filled
     * @param toCol    last column of the submatrix to be filled
     * @param startAtRow starting row of \a mat where the data is
     *                   located.
     * @param startAtCol starting column of \a mat where the data
     *                   is located.
     */
    void fill(const genericMatrix<T>& mat,
              const int fromRow=0,
              const int fromCol=0,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex,
              const int startAtRow=0,
              const int startAtCol=0);

    /**
     * Fills this genericMatrix between the "from's" and "to's" with
     * the contents of the genericMatrix \a mat starting at
     * \a startAtRow and \a startAtCol
     *
     * @param mat     the genericMatrix with the data to be copied
     * @param from    first position of the submatrix to be filled
     * @param to      last position of the submatrix to be filled
     * @param startAt starting position of \a mat where the data is
     *                located.
     */
    inline void fill(const genericMatrix<T>& mat,
                     const size_type& from,
                     const size_type& to=size_type(MaxIndex,MaxIndex),
                     const size_type& startAt=size_type(0,0));

    /**
     * Fills the region of this genericMatrix specified by \a window with the
     * contents of the genericMatrix \a mat starting at \a start.  If these
     * values are out of bounds, they will be (internally) adjusted to correct
     * values.
     *
     * @param mat    pointer to the data to be copied
     * @param window the window to be filled
     * @param start  the start position of the region to be copied of the
     *               genericMatrix \a mat
     */
    inline void fill(const genericMatrix<T>& mat,
                     const irectangle& window,
                     const size_type& start=size_type(0,0));

    /**
     * Access element at the given row and column
     *
     * @param row the row of the element
     * @param col the column of the element
     * @return a reference to the genericMatrix element
     */
    inline T& at(const int row, const int col);

    /**
     * Read-only access at the given row and column
     *
     * @param row the row of the element
     * @param col the column of the element
     * @return a reference to the genericMatrix element
     */
    inline const T& at(const int row, const int col) const;

    /**
     * Access operator of genericMatrix element as a point in a 2D-Map
     *
     * @param p position of the element (this is equivalent to at(p.y,p.x))
     * @return a reference to the genericMatrix element
     */
    inline T& at(const size_type& p);

    /**
     * Const access operator of genericMatrix element as a point in a 2D-Map
     *
     * @param p position of the element (this is equivalent to at(p.y,p.x))
     * @return a const reference to the vector element
     */
    inline const T& at(const size_type& p) const;

    /**
     * Access element at the given position.
     *
     * With this operator the genericMatrix can be accessed as a
     * vector, where the rows of the genericMatrix are concatenated.
     * The access to the genericMatrix with at(row,col) is equivalent
     * to elem(row*columns()+col).
     *
     * @param pos the index of the element of the genericMatrix
     *
     * @return a reference to the genericMatrix element
     */
    inline T& elem(const int pos);

    /**
     * Access element at the given position.
     *
     * With this operator the genericMatrix can be accessed as a
     * vector, where the rows of the genericMatrix are concatenated.
     * The access to the genericMatrix with at(row,col) is equivalent
     * to elem(row*columns()+col).
     *
     * @param pos the index of the element of the genericMatrix
     *
     * @return a reference to the genericMatrix element
     */
    inline const T& elem(const int pos) const;

    /**
     * Return genericMatrix-row as a vector.
     *
     * This method works fast, since it returns a reference to the row vector.
     * The data will NOT be copied.
     *
     * @param row the row to be accessed
     * @return a reference to the vector row
     */
    inline row_type& getRow(const int row);

    /**
     * Return genericMatrix-row as a const vector.
     * This method works fast, since it returns a reference to the row vector.
     * The data will NOT be copied.
     *
     * @param row the row to be accessed
     * @return a const reference to the vector row
     */
    inline const row_type& getRow(const int row) const;

    /**
     * Alias for getRow()
     */
    inline row_type& operator[](const int row);

    /**
     * Alias for getRow()
     */
    inline const row_type& operator[](const int row) const;

    /**
     * Copy a row vector in the given parameter.
     *
     * This method copies the data of a given row of the genericMatrix
     * in the given vector.
     *
     * @param row the number of the row to be copied
     * @param theRow the vector, where the data will be copied
     * @see getRow()
     */
    inline void getRowCopy(const int row,row_type& theRow) const;

    /**
     * Return genericMatrix-row as a vector.
     *
     * This method copies the data of the genericMatrix, therefore is not as
     * fast as getRow().
     *
     * @param row the number of the row to be copied
     * @return a vector with the contents of the row of the genericMatrix
     */
    inline row_type getRowCopy(const int row) const;

    /**
     * Return genericMatrix-column as a vector.
     *
     * This method copies the data of the genericMatrix, therefore is not as
     * fast as getRow().
     *
     * @param col the number of the column to be copied
     * @param theCol a vector, where the column vector of the genericMatrix
     *               should be copied.
     */
    void getColumnCopy(const int col,row_type& theCol) const;

    /**
     * Return genericMatrix-column as a vector.
     *
     * This method copies the data of the genericMatrix, therefore is not as
     * fast as getRow()
     * @param col the number of the column to be copied
     * @return a vector with the contents of the column of the genericMatrix
     */
    inline row_type getColumnCopy(const int col) const;

    /**
     * Return the diagonal elements of the genericMatrix as vector.
     *
     * This method copies the diagonal elements of the genericMatrix into
     * the vector. If the genericMatrix is non-symmetrical, the vector will
     * be of dimension min(rows(),columns()).
     * @param diag a vector, where the diagonal of the genericMatrix
     *             should be copied.
     */
    void getDiagonal(row_type& diag) const;

    /**
     * Return the diagonal elements of the genericMatrix as vector.
     * This method copies the diagonal elements of the genericMatrix into
     * the vector. If the genericMatrix is non-symmetrical, the vector will
     * be of dimension min(rows(),columns()).
     * @return a vector with the diagonal elements of the genericMatrix.
     */
    inline row_type getDiagonal() const;

    /**
     * Sets the diagonal of the genericMatrix to the values given in
     * the genericVector \a diag. Let \c r be the number of rows and
     * \c c be the number of columns of the matrix. Then \c minRC is
     * \c min(r,c). Also let \c d be the size of \a diag. Only \c
     * min(minRC,d) values are copied from \a diag. If \c d is smaller
     * than \c minRC the remaining values on the diagonal are left
     * untouched. The copying always starts at (0,0) of the matrix.
     *
     * @param diag values to be copied into the diagonal of the matrix
     */
    void setDiagonal(const row_type& diag);

    /**
     * Copy the data of a vector in a given row.
     *
     * @param row the row that receives the data.
     * @param theRow the vector with the data to be copied
     */
    inline void setRow(const int row,const row_type& theRow);

    /**
     * Copy the data of a vector in a given column
     * @param col the column that receives the data.
     * @param theCol the vector with the data to be copied
     */
    void setColumn(const int col,const row_type& theCol);

    /**
     * Assigment operator.
     *
     * Copy the contents of \a other in this object.
     *
     * @param other the other genericMatrix to be copied
     */
    genericMatrix<T>& copy(const genericMatrix<T>& other);

    /**
     * Assigment operator.
     *
     * Copy the contents of a submatrix of \a other into this object.  The
     * content of the current object is removed and at the end it will contain
     * a copy the submatrix only.
     *
     * @param other the other genericMatrix to be copied
     * @param fromRow initial row of the other genericMatrix to be copied
     * @param fromCol initial column of the other genericMatrix to be copied
     * @param toRow last row to be copied of the other genericMatrix
     * @param toCol last column to be copied of the other genericMatrix
     */
    genericMatrix<T>& copy(const genericMatrix<T>& other,
                           const int fromRow,
                           const int fromCol,
                           const int toRow=MaxIndex,
                           const int toCol=MaxIndex);


    /**
     * Assigment operator.
     *
     * Copy the contents of a submatrix of \a other into this object.  The
     * content of the current object is removed and at the end it will contain
     * only the submatrix.
     *
     * @param other the other genericMatrix to be copied
     * @param from initial submatrix indices (x,y) to be copied
     * @param to   last submatrix indices (x,y) to be copied (inclusive)
     */
    inline genericMatrix<T>& copy(const genericMatrix<T>& other,
                                  const size_type& from,
                                  const size_type& to);

    /**
     * Assigment operator.
     *
     * Copy the contents of a submatrix of \a other into this object.  The
     * content of the current object is removed and at the end it will contain
     * only the copy of the submatrix.
     *
     * @param other the other genericMatrix to be copied
     * @param window rectangle define the copy area
     */
    inline genericMatrix<T>& copy(const genericMatrix<T>& other,
                                  const irectangle& window);

    /**
     * Assigment operator.
     *
     * Copy the contents of the specified rows of \a other into this
     * object. Multiple occurence of one row index in \a idx is allowed.
     *
     * @param other the other genericMatrix to be copied
     * @param idx indices of the rows to be copied.
     */
    genericMatrix<T>& copyRows(const genericMatrix<T>& other,
                           const genericVector<int>& idx);

    /**
     * Assigment operator.
     *
     * Copy the contents of the specified columns of \a other into this
     * object. Multiple occurence of one column index in \a idx is allowed.
     *
     * @param other the other genericMatrix to be copied
     * @param idx indices of the rows to be copied.
     */
    genericMatrix<T>& copyColumns(const genericMatrix<T>& other,
                                  const genericVector<int>& idx);

    /**
     * Copy the \a other genericMatrix by casting each of
     * its elements
     *
     * @param other The genericMatrix to be casted
     *
     * Example:
     * \code
     *   cvr::genericMatrix<int> matA(10,10,1);// a genericMatrix of integers
     *   cvr::genericMatrix<double> matB;      // a genericMatrix of doubles
     *
     *   matB.castFrom(matA);          // this will copy matA in matB!!
     * \endcode
     */
    template<typename U>
    genericMatrix<T>& castFrom(const genericMatrix<U>& other);

    /**
     * This is just an alias for copy(const genericMatrix<T>&) to facilitate
     * generic programming.
     *
     * @param other The genericMatrix to be copied.
     */
    genericMatrix<T>& castFrom(const genericMatrix<T>& other);

    /**
     * Copy a submatrix of the \a other genericMatrix by casting each of
     * its elements.
     *
     * @param other The genericMatrix to be casted
     * @param fromRow initial row of the other genericMatrix to be copied
     * @param fromCol initial column of the other genericMatrix to be copied
     * @param toRow last row to be copied of the other genericMatrix
     * @param toCol last column to be copied of the other genericMatrix
     *
     * @return a reference to the current casted matrix.
     */
    template<typename U>
    genericMatrix<T>& castFrom(const genericMatrix<U>& other,
                               const int fromRow,
                               const int fromCol,
                               const int toRow=MaxIndex,
                               const int toCol=MaxIndex);

    /**
     * This is just an alias for copy(const genericMatrix<T>&, const int
     * fromRow, const int fromCol, const int toRow, const int toCol) to
     * facilitate generic programming.
     *
     * @param other The genericMatrix to be copied.
     * @param fromRow initial row of the other genericMatrix to be copied
     * @param fromCol initial column of the other genericMatrix to be copied
     * @param toRow last row to be copied of the other genericMatrix
     * @param toCol last column to be copied of the other genericMatrix
     *
     * @return a reference to the current casted matrix.
     */
    genericMatrix<T>& castFrom(const genericMatrix<T>& other,
                               const int fromRow,
                               const int fromCol,
                               const int toRow=MaxIndex,
                               const int toCol=MaxIndex);

    /**
     * Returns the name of this type.
     */
    virtual const std::string& name() const;

    /**
     * Create a clone of this genericMatrix
     * @return a pointer to a copy of this genericMatrix
     */
    virtual genericMatrix<T>* clone() const;

    /**
     * Create a new instance of genericMatrix
     * @return a pointer to a new instance of genericMatrix
     */
    virtual genericMatrix<T>* newInstance() const;

    /**
     * Compare this genericMatrix with other.
     *
     * @param other the other genericMatrix to be compared with
     * @return true if both matrices have the same elements and same size
     */
    bool equals(const genericMatrix<T>& other) const;

    /**
     * Compare the contents of each element of this genericMatrix with the
     * other one.  It assumes the type T can be compared using the
     * operator==.
     *
     * @param other the other genericMatrix to be compared with
     * @return true if both matrices have the same elements and same size
     */
    inline bool operator==(const genericMatrix<T>& other) const;

    /**
     * Assigment operator (alias for copy(other)).
     *
     * @param other the genericMatrix to be copied
     * @return a reference to the actual genericMatrix
     */
    inline genericMatrix<T>& operator=(const genericMatrix<T>& other);

    /**
     * \name Apply Methods
     *
     * Following methods are used to apply simple functions to each element
     * of the vector.
     */
    //@{

    /**
     * Applies a C-function to each element of the genericMatrix.
     * @param function a pointer to a C-function
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(T (*function)(T));

    /**
     * Applies a C-function to each element of the other genericMatrix
     * @param other the genericMatrix which elements will go through the given
     *              function.
     * @param function a pointer to a C-function
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& other,T (*function)(T));

    /**
     * Applies a C-function to each element of the genericMatrix.
     * @param function a pointer to a C-function
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(T (*function)(const T&));

    /**
     * Applies a C-function to each element of the other genericMatrix
     * @param other the genericMatrix which elements will go through the given
     *              function.
     * @param function a pointer to a C-function
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& other,
                            T (*function)(const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this
     * and the given genericMatrix and the result will be left in this
     * genericMatrix.  Note that both matrices must have the same size!
     * @param other the second genericMatrix to be considered (the first
     *              genericMatrix will be this object!)
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& other,
                            T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this
     * and the given genericMatrix and the result will be left in this
     * genericMatrix.  Note that both matrices must have the same size!
     * @param other the second genericMatrix to be considered (the first
     *              genericMatrix will be this object!)
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& other,
                            T (*function)(T,T));

    /**
     * A two-parameter C-function receives the i-th elements of both given
     * matrices and leaves the result here.
     * Note that both matrices must have the same size!
     * @param a the first genericMatrix
     * @param b the second genericMatrix
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& a,
                     const genericMatrix<T>& b,
                     T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of both given
     * matrices and leaves the result here.
     * Note that both matrices must have the same size!
     * @param a the first genericMatrix
     * @param b the second genericMatrix
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericMatrix
     */
    genericMatrix<T>& apply(const genericMatrix<T>& a,
                     const genericMatrix<T>& b,
                     T (*function)(T,T));

    //@}

    /**
     * @name Input and Output
     */
    //@{

    /**
     * Write the object in the given ioHandler
     */
    virtual bool write(ioHandler& handler,const bool complete = true) const;

    /**
     * Read the object from the given ioHandler
     */
    virtual bool read(ioHandler& handler,const bool complete = true);
    //@}

  protected:

    /**
     * @name Memory allocation and deallocation
     *
     * Restrict all memory allocation and deallocation to these functions.
     */
    //@{
    /**
     * Allocate \a n number of rows or the appropriate type.
     */
    inline virtual row_type* allocNewRows(const int n);

    /**
     * Reserve just a memory block of the given size;
     */
    inline T* reserveNewMem(const int theSize) const;

    /**
     * Reserve memory.
     *
     * This method allocates memory for the elements, for the rows and
     * distributes the memory into the blocks
     */
    void reserveMem(const int rows,const int cols);

    /**
     * Release the given block of memory.
     */
    void releaseMem(T*& block) const;
    
    /**
     * Release the internal memory blocks, including
     * theElements_ and the row array.
     */
    void releaseMem();
 
    /**
     * Allocate \a n number of rows or the appropriate type.
     */
    inline void releaseRows(row_type*& theRows) const;

    /**
     * Take the memory block and distribute it on the
     * allocated vectors pointed by theRows.
     */
    void distributeMem(const int theRows,
                       const int theCols,
                       T* block,
                       row_type* memRows) const;
    //@}

    /**
     * Size of the matrix as point
     */
    size_type theSize_;

    /**
     * Index of the last row, i.e. last_.x=theSize.x-1, and last_.y=theSize.y-1
     */
    size_type last_;

    /**
     * Size of theElements_ memory block, i.e. theSize_.x*theSize_.y;
     */
    int totalSize_;

    /**
     * Indicates if \a theElements points to own data or to
     * external data.
     */
    bool ownData_;

    /**
     * If constReference=true, is not possible to resize or change
     * the reference of this genericVector.
     *
     * Very important for an efficient matrix class!!
     * (see useExternData())
     */
    eConstantReference constReference_;

    /**
     * Pointer to the elements of the genericMatrix
     */
    T* theElements_;

    /**
     * Table of pointers to the rows
     */
    row_type* rowAddressTable_;
  };
}

namespace std {
  /*
   * Outputs the elements of the vector on a stream
   */
  template <class T>
  ostream& operator<<(ostream& s,const cvr::genericMatrix<T>& amat);
}

#include "cvrGenericMatrix_inline.h"
#include "cvrGenericMatrix_template.h"

#else
#include "cvrGenericMatrix_template.h"
#endif