cvrGenericLattice2D.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   cvrGenericLattice2D.h
 *         Contains a template class to describe 2D lattices, which are like 
 *         matrices but addressable with negative indices, and whose rows are
 *         of type cvr::genericLattice1D.
 * \author Pablo Alvarado
 * \date   27.12.2007
 *
 * $Id: cvrGenericLattice2D.h,v 1.19 2007/09/15 03:36:57 alvarado Exp $
 */

#ifndef _CVR_GENERIC_LATTICE_2_D_H_
#define _CVR_GENERIC_LATTICE_2_D_H_

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

namespace cvr {
  /**
   * Container class for two dimensional lattices.
   *
   * The cvr::genericLattice2D class is a container class implemented as a
   * template.
   *
   * The cvr::genericLattice2D class allows the representation of two
   * dimensional lattice, containing an element at each point of the lattice.
   * The points are inidicated with an ordered pair \e n x \e m, where n and m
   * can be taken from intervals selected at construction time, that may
   * include negative values. 
   *
   * The type of the elements contained must be static in nature.  All types
   * defined in cvrTypes.h use static members and can be contained by the
   * cvr::genericLattice1D and cvr::genericLattice2D classes.
   *
   * If you need to create a genericLattice2D of floats with 20 rows and
   * 15 columns, all elements initialized with an initial value of
   * 4.27 just create it:
   *
   * \code
   * cvr::genericLattice2D<float> myMat(-9,10,
   *                                    -7,8,4.27f) // creates genericLattice2D
   *                                                // with 300 elements all
   *                                                // initialized with 4.27f
   * \endcode
   *
   * To access the cvr::genericLattice2D 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 cvr::lattice1D.  You cannot
   * for instance resize nor change the memory referenced in this lattice1D
   * (see cvr::lattice1D::resize).  For example:
   *
   * \code
   * float accu = 0; // initialize accumulator
   * cvr::genericLattice2D<float> myMat(-9,10,-7,8,4.27f)
   * cvr::genericLattice1D<float> myLat;
   *
   * for (int j = myMat.firstRow(); j <= myMat.lastRow(); j++) {
   *   for (int i = myMat.firstColumn(); i <= myMat.lastColumn(); i++) {
   *   tmp += myMat.at(j,i); // access each element of the genericLattice2D:
   *                         // j is the row and i the column
   *   }
   * }
   *
   * myMat.getRowCopy(5,myLat);    // copy the row with index 5 in myLat!
   * myLat.resize(-6,6);           // Valid, the vector has its own memory!
   * myMat.getRow(5).resize(-6,6); // ERROR!! the vector is not resizable!
   *
   * \endcode
   *
   * Lattices in the CVR-Lib use always a continuous block of memory, which
   * allows efficient elementwise operations. 
   *
   * @see cvr::lattice2D
   *
   * The genericLattice2D has following methods:
   * - Constructors Constructors
   *   - You can construct an empty genericLattice2D with the default
   *     constructor (genericLattice2D()).
   *   - If you know the number of rows and columns use
   *     genericLattice2D(const int fromRow,const int toRow,
   *                      const int fromColumn, const int toRow, 
   *                      const T& initialValue)
   * - Access members
   *   - at(), operator[]()
   *   - The rows() member returns the number of rows of the genericLattice2D.
   *   - The columns() member returns the number of columns of the
         genericLattice2D.
   * - Fill and Copy members
   *   - With the fill() members you can fill the genericLattice2D with a given
   *     constant value or with values taken from other matrices.
   *   - With the copy() member you can copy another genericLattice2D.
   *   - You can specify, that the genericLattice2D should be used just as a
   *     wrapper-object to access external memory regions: useExternData().
   *     To check if a genericLattice2D is a wrapper-object you can use
   *     ownsData().
   * - Iterators
   *   - It is possible to iterate within the genericLattice2D by making use of
   *     the genericLattice2D 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 genericLattice2D : 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 genericLattice1D<T> row_type;

    /**
     * Pointer to value_type
     */
    typedef T* pointer;

    /**
     * Const pointer to value_type
     */
    typedef const T* const_pointer;
    
    /**
     * Reference to value_type
     */
    typedef T& reference;

    /**
     * Const reference to value_type
     */
    typedef const T& const_reference;

#   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::genericLattice2D::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 genericLattice2D 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::genericLattice2D::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 genericLattice2D 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::genericLattice2D::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 genericLattice2D 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<genericLattice2D<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::genericLattice2D::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 genericLattice2D 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<genericLattice2D<T>,true> const_iterator;
#   endif
    //@}

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

    /**
     * Create a genericLattice2D with uninitialized elements.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     */
    genericLattice2D(const int fromRow,
                     const int fromCol,
                     const int toRow,
                     const int toCol);

    /**
     * Create a \a rows x \a cols genericLattice2D with uninitialized elements.
     *
     * @param from lowest row and column
     * @param to   highest row and column
     */
    genericLattice2D(const size_type& from,
                     const size_type& to);

    /**
     * Create a genericLattice2D with uninitialized elements.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     */
    genericLattice2D(const iinterval& rows,
                     const iinterval& columns);

    /**
     * Create a genericLattice2D and initialize all elements with the given
     * value.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param value value used for initializing the elements
     */
    genericLattice2D(const int fromRow,
                     const int fromCol,
                     const int toRow,
                     const int toCol,
                     const T& value);

    /**
     * Create a genericLattice2D and initialize all elements with the given
     * value.
     *
     * @param from lowest index 
     * @param to highest index (inclusive)
     * @param value value used for initializing the elements
     */
    genericLattice2D(const size_type& from,
                     const size_type& to,
                     const T& value);

    /**
     * Create a genericLattice2D and initialize all elements with the given
     * value.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     * @param value value used for initializing the elements
     */
    genericLattice2D(const iinterval& rows,
                     const iinterval& columns,
                     const T& value);

    /**
     * Create a genericLattice2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    genericLattice2D(const int fromRow,
                     const int fromCol,
                     const int toRow,
                     const int toCol,
                     const T data[]);

    /**
     * Create a genericLattice2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param from lowest index
     * @param to   highest index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    genericLattice2D(const size_type& from,
                     const size_type& to,
                     const T data[]);

    /**
     * Create a genericLattice2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    genericLattice2D(const iinterval& rows,
                     const iinterval& columns,
                     const T data[]);

    /**
     * Create a genericLattice2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first 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 last 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 last argument, the data is
     * always copied.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    genericLattice2D(const int fromRow,
                     const int fromCol,
                     const int toRow,
                     const int toCol,
                     T data[],
                     const eConstantReference constRef);

    /**
     * Create a genericLattice2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first 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 last 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 last argument, the data is
     * always copied.
     *
     * @param from lowest index
     * @param to highest index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    genericLattice2D(const size_type& from,
                     const size_type& to,
                     T data[],
                     const eConstantReference constRef);


    /**
     * Create a genericLattice2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first 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 last 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 last argument, the data is
     * always copied.
     *
     * @param rows interval for rows
     * @param columns interval for columns
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    genericLattice2D(const iinterval& rows,
                     const iinterval& columns,
                     T data[],
                     const eConstantReference constRef);

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

    /**
     * Copy constructor.
     *
     * Create this genericLattice2D as a copy of another genericLattice2D for
     * this const version, the data will be always copied!
     *
     * @param other the genericLattice2D to be copied.
     * @param fromRow initial row of the other genericLattice2D to be copied
     * @param fromCol initial column of the other genericLattice2D to be copied
     * @param toRow last row to be copied of the other genericLattice2D
     * @param toCol last column to be copied of the other genericLattice2D
     */
    genericLattice2D(const genericLattice2D<T>& other,
                     const int fromRow,
                     const int fromCol,
                     const int toRow=MaxIndex,
                     const int toCol=MaxIndex);
    
    /**
     * Copy constructor.
     *
     * Create this genericLattice2D as a copy of a sublattice2D of another
     * genericLattice2D.
     *
     * @param other the genericLattice2D to be copied.
     * @param from initial position in the other genericLattice2D to be copied
     * @param to last position to be copied of the other genericLattice2D
     */
    genericLattice2D(const genericLattice2D<T>& other,
                     const size_type& from,
                     const size_type& to);

    /**
     * Copy constructor.
     *
     * Create this genericLattice2D as a copy of a sublattice2D of another
     * genericLattice2D.
     *
     * @param other the genericLattice2D to be copied.
     * @param rows interval of rows to be copied.
     * @param columns interval of columns to be copied.
     */
    genericLattice2D(const genericLattice2D<T>& other,
                     const iinterval& rows,
                     const iinterval& columns);

    /**
     * Copy constructor.
     *
     * Create this genericLattice2D as a copy of another genericLattice2D
     * 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 genericLattice2D to be copied.
     * @param rows indices of the rows to be copied
     */
    genericLattice2D(const genericLattice2D<T>& other,
                     const genericLattice1D<int>& rows);

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

    /**
     * Owns this %object the data?
     * returns <em>false</em> if this genericLattice2D 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 genericLattice2D as
     * its owner.  If this genericLattice2D 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 data!.
     * If <em>rows</em> and <em>cols</em> are invalid dimensions, the
     * behaviour will be unpredictible.
     * @param fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index
     * @param toCol final column index
     * @param data a pointer to the memory block to be used
     * @param constRef constant reference
     *
     * For an example see attach()
     */
    void useExternData(const int fromRow,
                       const int fromCol,
                       const int toRow,
                       const int toCol,
                       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 from initial index
     * @param to initial index
     * @param data a pointer to the memory block to be used
     * @param constRef constant reference
     *
     * For an example see attach()
     */
    inline void 
    useExternData(const size_type& from,
                  const size_type& to,
                  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 rows interval of rows to be used.
     * @param columns interval of columns to be used.
     * @param data a pointer to the memory block to be used.
     * @param constRef constant reference.
     *
     * For an example see attach()
     */
    inline void 
    useExternData(const iinterval& rows,
                  const iinterval& columns,
                  T data[],
                  const eConstantReference constRef=VariableReference);


    /**
     * Attach extern data to the genericLattice2D.
     *
     * 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 genericLattice2D object,
     * and may be deleted if required (genericLattice2D deleted or
     * resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index (inclusive)
     * @param toCol final column index (inclusive)
     * @param data a pointer to the memory block to be used
     */
    void attach(const int fromRow,
                const int fromCol,
                const int toRow,
                const int toCol,
                T* data);

    /**
     * Attach extern data to the genericLattice2D.
     *
     * 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 genericLattice2D object,
     * and may be deleted if required (genericLattice2D deleted or
     * resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param from initial index
     * @param to final index (inclusive)
     * @param data a pointer to the memory block to be used
     */
    inline void attach(const size_type& from,
                       const size_type& to,
                       T* data);

    /**
     * Attach extern data to the genericLattice2D.
     *
     * 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 genericLattice2D object,
     * and may be deleted if required (genericLattice2D deleted or
     * resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param rows interval for rows
     * @param columns interval fro columns
     * @param data a pointer to the memory block to be used
     */
    inline void attach(const iinterval& rows,
                       const iinterval& columns,
                       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
     * genericLattice2D.  It is a very efficient way to make a copy of
     * this genericLattice2D, if you don't need the source data anymore!
     *
     * If the current lattice2D does not own its data, neither will the
     * receiver lattice2D, which will also be just a wrapper of the same data.
     *
     * If the current lattice2D is lined, then the other lattice2D 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 genericLattice2D will be empty.
     *
     * @param receiver the genericLattice2D which will receive the memory
     *        block.  All data of that genericLattice2D will be first deleted!
     */
    void detach(genericLattice2D<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 genericLattice2D.  It is a very efficient
     * way to move the data of this genericLattice2D into a vector, if you
     * don't need the source data anymore!
     *
     * \b Note: If the attach() or useExternData() methods of this
     * genericLattice2D have been called before detachment, the same rules for
     * memory management apply now for the \c receiver.
     *
     * At the end of the detachment, this genericLattice2D will be empty.
     *
     * @param receiver the genericLattice2D which will receive the memory 
     *                 block.
     *                 All data of that genericLattice2D will be first deleted!
     */
    void detach(genericVector<T>& receiver);

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

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

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

    /**
     * Index of the first row (rows()-1)
     */
    inline int firstRow() const;

    /**
     * Index of the first columns (columns()-1)
     */
    inline int firstColumn() 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 %genericLattice2D 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 lattice2D
     *
     * @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& firstIndex() const;

    /**
     * Returns a read-only reference to the last index of the lattice2D
     *
     * @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 genericLattice2D.
     *
     * 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 genericLattice2D, you can
     * use following code:
     * \code
     * int tmp,accu;                  // a temporal variable
     * cvr::genericLattice2D<int> myMat(10,8,1); // a vector with 10 elements
     * cvr::genericLattice2D<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 lattice.
     * }
     * \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 genericLattice2D as a const_iterator.
     *
     * Note that you can not change the values of the genericLattice2D
     * 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 genericLattice2D
     */
    inline iterator end();

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


    /**
     * This method returns an iterator that points to the \b last valid element
     * of the genericLattice2D. It is used for inverse order iteration through
     * the genericLattice2D 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 genericLattice2D. 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 genericLattice2D. It is used to
     * mark the end for inverse order iteration through the genericLattice2D
     * 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 genericLattice2D.
     */
    inline const_iterator inverseEnd() const;

    /**
     * Change the dimensions of the genericLattice2D.
     *
     * @param fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index (inclusive)
     * @param toCol final column index (inclusive)
     * @param iniValue the initialization value.
     * @param resizeType specifies what should happen with the data of the
     *                   resized lattice2D.
     *
     * If the resize is possible (see useExternData()), this %object
     * will always owns the data!
     *
     * @see eResizeType, assign(),allocate()
     */
    void resize(const int fromRow,
                const int fromCol,
                const int toRow,
                const int toCol,
                const T& iniValue,
                const eResizeType resizeType=CopyAndInit);

    /**
     * Change the dimensions of the genericLattice2D.
     *
     * @param from initial index
     * @param to final index
     * @param iniValue value to initialize the rest
     * @param resizeType specifies what should happen with the data of the
     *                   resized lattice2D.
     *
     * 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& from,
                       const size_type& to,
                       const T& iniValue,
                       const eResizeType resizeType=CopyAndInit);

    /**
     * Change the dimensions of the genericLattice2D.
     *
     * @param rows interval of valid rows
     * @param columns interval of valid columns
     * @param iniValue value to initialize the rest
     * @param resizeType specifies what should happen with the data of the
     *                   resized lattice2D.
     *
     * 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 iinterval& rows,
                       const iinterval& columns,
                       const T& iniValue,
                       const eResizeType resizeType=CopyAndInit);



    /**
     * Change the dimensions of the genericLattice2D, copying old data but
     * leaving all new elements uninitialized.
     *
     * @param fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index (inclusive)
     * @param toCol final column index (inclusive)
     *
     * If the resize is possible (see useExternData()), this %object
     * will always owns the data!
     *
     * @see eResizeType, assign(),allocate()
     */
    inline void resize(const int fromRow,
                       const int fromCol,
                       const int toRow,
                       const int toCol);

    /**
     * Change the dimensions of the genericLattice2D, copying old data but
     * leaving all new elements uninitialized.
     *
     * @param from initial index
     * @param to final index
     *
     * 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& from,
                       const size_type& to);

    /**
     * Change the dimensions of the genericLattice2D, copying old data but
     * leaving all new elements uninitialized.
     *
     * @param rows interval of valid rows
     * @param columns interval of valid columns
     *
     * 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 iinterval& rows,
                       const iinterval& columns);



    /**
     * Change the dimensions of the genericLattice2D and leave ALL data
     * uninitialized.
     *
     * @param fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index (inclusive)
     * @param toCol final column index (inclusive)
     *
     * 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 fromRow,
                         const int fromCol,
                         const int toRow,
                         const int toCol);

    /**
     * Change the dimensions of the genericLattice2D and leave ALL data
     * uninitialized.
     *
     * @param from initial index
     * @param to final index
     *
     * 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& from,
                         const size_type& to);

    /**
     * Change the dimensions of the genericLattice2D and leave ALL data
     * uninitialized.
     *
     * @param rows interval of valid rows
     * @param columns interval of valid columns
     *
     * 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 iinterval& rows,
                         const iinterval& columns);

    /**
     * Change the dimensions of the genericLattice2D 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 fromRow initial row index
     * @param fromCol initial column index
     * @param toRow final row index (inclusive)
     * @param toCol final column index (inclusive)
     * @param initValue value to be assigned to all lattice2D elements
     */
    inline void assign(const int fromRow,
                       const int fromCol,
                       const int toRow,
                       const int toCol,
                       const T& initValue);

    /**
     * Change the dimensions of the genericLattice2D 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 from initial index
     * @param to final index
     * @param initValue value to be assigned to all lattice2D elements
     */
    inline void assign(const size_type& from,
                       const size_type& to,
                       const T& initValue);

    /**
     * Change the dimensions of the genericLattice2D 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 rows interval of valid rows
     * @param columns interval of valid columns
     * @param initValue value to be assigned to all lattice2D elements
     */
    inline void assign(const iinterval& rows,
                       const iinterval& columns,
                       const T& initValue);

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

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

    /**
     * Fills genericLattice2D 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 sublattice2D to be filled
     * @param fromCol  first column of the sublattice2D to be filled
     * @param toRow    last row of the sublattice2D to be filled
     * @param toCol    last column of the sublattice2D to be filled
    */
    void fill(const T& iniValue,
              const int fromRow=MinIndex,
              const int fromCol=MinIndex,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex);

    /**
     * Fills genericLattice2D 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 sublattice2D to be filled
     * @param to   last row of the sublattice2D to be filled
    */
    inline void fill(const T& iniValue,
                     const size_type& from,
                     const size_type& to=size_type(MaxIndex,MaxIndex));

    /**
     * Fills genericLattice2D 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 genericLattice2D 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 sublattice2D to be filled
     * @param fromCol  first column of the sublattice2D to be filled
     * @param toRow    last row of the sublattice2D to be filled
     * @param toCol    last column of the sublattice2D to be filled
     */
    void fill(const T data[],
              const int fromRow=MinIndex,
              const int fromCol=MinIndex,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex);

    /**
     * Fills genericLattice2D 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 sublattice2D to be filled
     * @param to    last position of the sublattice2D to be filled
     */
    inline void fill(const T data[],
                     const size_type& from,
                     const size_type& to=size_type(MaxIndex,MaxIndex));

    /**
     * Fills genericLattice2D 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 genericLattice2D between the "from's" and "to's" with
     * the contents of the genericLattice2D \a mat starting at
     * \a startAtRow and \a startAtCol
     *
     * @param mat      the genericLattice2D with the data to be copied
     * @param fromRow  first row of the sublattice2D to be filled
     * @param fromCol  first column of the sublattice2D to be filled
     * @param toRow    last row of the sublattice2D to be filled
     * @param toCol    last column of the sublattice2D 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 genericLattice2D<T>& mat,
              const int fromRow=MinIndex,
              const int fromCol=MinIndex,
              const int toRow=MaxIndex,
              const int toCol=MaxIndex,
              const int startAtRow=MinIndex,
              const int startAtCol=MinIndex);

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

    /**
     * Fills the region of this genericLattice2D specified by \a window with the
     * contents of the genericLattice2D \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
     *               genericLattice2D \a mat
     */
    inline void fill(const genericLattice2D<T>& mat,
                     const irectangle& window,
                     const size_type& start=size_type(MinIndex,MinIndex));

    /**
     * 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 genericLattice2D 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 genericLattice2D element
     */
    inline const T& at(const int row, const int col) const;

    /**
     * Access operator of genericLattice2D 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 genericLattice2D element
     */
    inline T& at(const size_type& p);

    /**
     * Const access operator of genericLattice2D 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 genericLattice2D can be accessed as a
     * vector, where the rows of the genericLattice2D are concatenated.
     * The access to the genericLattice2D with at(row,col) is equivalent
     * to elem(row*columns()+col), but more efficient.
     *
     * @param pos the index of the element of the genericLattice2D
     *
     * @return a reference to the genericLattice2D element
     */
    inline T& elem(const int pos);

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

    /**
     * Return genericLattice2D-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 genericLattice2D-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 genericLattice2D
     * 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 genericLattice2D-row as a vector.
     *
     * This method copies the data of the genericLattice2D, 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 genericLattice2D
     */
    inline row_type getRowCopy(const int row) const;

    /**
     * Return genericLattice2D-column as a vector.
     *
     * This method copies the data of the genericLattice2D, 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 genericLattice2D
     *               should be copied.
     */
    void getColumnCopy(const int col,row_type& theCol) const;

    /**
     * Return genericLattice2D-column as a vector.
     *
     * This method copies the data of the genericLattice2D, 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 genericLattice2D
     */
    inline row_type getColumnCopy(const int col) const;

    /**
     * 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 genericLattice2D to be copied
     */
    genericLattice2D<T>& copy(const genericLattice2D<T>& other);

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


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

    /**
     * Assigment operator.
     *
     * copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     * @param r interval used for the rows
     * @param c interval used for the columns
     */
    inline genericLattice2D<T>& copy(const genericLattice2D<T>& other,
                                     const iinterval& r,
                                     const iinterval& c);

    /**
     * Assigment operator.
     *
     * Copy the contents of a sublattice2D 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 sublattice2D.
     *
     * @param other the other genericLattice2D to be copied
     * @param window rectangle define the copy area
     */
    inline genericLattice2D<T>& copy(const genericLattice2D<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 genericLattice2D to be copied
     * @param idx indices of the rows to be copied.
     */
    genericLattice2D<T>& copyRows(const genericLattice2D<T>& other,
                                  const genericLattice1D<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 genericLattice2D to be copied
     * @param idx indices of the rows to be copied.
     */
    genericLattice2D<T>& copyColumns(const genericLattice2D<T>& other,
                                     const genericLattice1D<int>& idx);

    /**
     * Copy the \a other genericLattice2D by casting each of
     * its elements
     *
     * @param other The genericLattice2D to be casted
     */
    template<typename U>
    genericLattice2D<T>& castFrom(const genericLattice2D<U>& other);

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

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

    /**
     * This is just an alias for copy(const genericLattice2D<T>&, const int
     * fromRow, const int fromCol, const int toRow, const int toCol) to
     * facilitate generic programming.
     *
     * @param other The genericLattice2D to be copied.
     * @param fromRow initial row of the other genericLattice2D to be copied
     * @param fromCol initial column of the other genericLattice2D to be copied
     * @param toRow last row to be copied of the other genericLattice2D
     * @param toCol last column to be copied of the other genericLattice2D
     *
     * @return a reference to the current casted lattice2D.
     */
    genericLattice2D<T>& castFrom(const genericLattice2D<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 genericLattice2D
     * @return a pointer to a copy of this genericLattice2D
     */
    virtual genericLattice2D<T>* clone() const;

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

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

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

    /**
     * Assigment operator (alias for copy(other)).
     *
     * @param other the genericLattice2D to be copied
     * @return a reference to the actual genericLattice2D
     */
    inline genericLattice2D<T>& operator=(const genericLattice2D<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 genericLattice2D.
     * @param function a pointer to a C-function
     * @return a reference to the actual genericLattice2D
     */
    genericLattice2D<T>& apply(T (*function)(T));

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

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

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

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

    /**
     * A two-parameter C-function receives the i-th elements of this
     * and the given genericLattice2D and the result will be left in this
     * genericLattice2D.  Note that both matrices must have the same size!
     * @param other the second genericLattice2D to be considered (the first
     *              genericLattice2D will be this object!)
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericLattice2D
     */
    genericLattice2D<T>& apply(const genericLattice2D<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 genericLattice2D
     * @param b the second genericLattice2D
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericLattice2D
     */
    genericLattice2D<T>& apply(const genericLattice2D<T>& a,
                               const genericLattice2D<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 genericLattice2D
     * @param b the second genericLattice2D
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual genericLattice2D
     */
    genericLattice2D<T>& apply(const genericLattice2D<T>& a,
                               const genericLattice2D<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.
     *
     * Never remove the returned pointer directly, since it is moved with
     * an offset of fromRow.
     *
     * You need to add to the pointer "fromRow" before deleting it.
     *
     * If the given interval is invalid (fromRow > toRow) then a null
     * pointer will be returned.
     */
    inline virtual row_type* allocNewRows(const int fromRow,
                                          const int toRow);

    /**
     * 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 fromRow,
                    const int fromColumn,
                    const int toRow,
                    const int toColumn);

    /**
     * Release the given block of memory.
     *
     * The block is directly released (not previously modified with the
     * offset).
     */
    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 int offset) const;

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

    /**
     * Size of the lattice2D 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 first_;

    /**
     * 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 lattice2D class!!
     * (see useExternData())
     */
    eConstantReference constReference_;

    /**
     * Pointer to the elements of the genericLattice2D
     */
    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::genericLattice2D<T>& amat);
}

#include "cvrGenericLattice2D_inline.h"
#include "cvrGenericLattice2D_template.h"

#else
#include "cvrGenericLattice2D_template.h"
#endif