cvrGenericLattice1D.h

Go to the documentation of this file.

/*
 * 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   cvrGenericLattice1D.h
 *         Contains a one-dimensional lattice container, which is somewhat
 *         similar to a genericVector but with a selectable initial index, 
 *         that, besides zero, can be positive or negative.
 * \author Pablo Alvarado
 * \date   09.04.1999
 *
 * $Id: cvrGenericLattice1D.h,v 1.16 2007/09/15 03:36:57 alvarado Exp $
 */

#ifndef _CVR_GENERIC_LATTICE_1D_H_
#define _CVR_GENERIC_LATTICE_1D_H_

#include "cvrContainer.h"
#include "cvrConstantReferenceType.h"
#include "cvrConstReferenceException.h"
#include "cvrAllocException.h"
#include "cvrTypes.h"
#include "cvrAssert.h"
#include "cvrResizeType.h"
#include "cvrDebugIterator.h"
#include "cvrGenericVector.h"
#include "cvrInterval.h"

#include <vector>

namespace cvr {
  /**
   * Generic Lattice 1D container.
   *
   * This container is inspired on mathematical integer lattices, at least with
   * respect to the indices, which are taken from \f$Z^n\f$ in the general
   * case with $n=1$ in this particular case.
   *
   * You can consider this a generalization of a cvr::genericVector, in which
   * the index of the first element is not necessarily zero, but a negative or
   * positive value.
   *
   * The main goal of this class is to provide a \b fast implementation for
   * random access containers, addressable with negative indices, like filter
   * kernels, and since speed is the premise, it is achieved at some memory
   * costs.  This means this class has some storage overhead in order to
   * provide some information at zero time, like size, first and last indices
   * the begin and end iterators, etc., which is only possible by storing them
   * directly.
   *
   * This class cannot be used to contain objects which use some sort of
   * dynamic memory allocation.  This means, you should not try to make a
   * cvr::genericLattice1D of other vectors or matrices, which administrate
   * some memory.  If you do so, the behaviour of copy or fill operations will
   * be unpredictable.
   *
   * Most of times you will want to use cvr::lattice1D instead, since they
   * provide some mathematical functionality.
   *
   * The difference between cvr::genericLattice1D and its most used inherited
   * class cvr::lattice1D is the support for arithmetical operations.  The
   * generic lattice is more a "pure" container.  It inherits its memory
   * management versatility to cvr::lattice1D.  Again, it is usually employed
   * as a container of any \e static type, which do not do by itself any memory
   * managment.
   *
   * The genericLattice1D class is a generic container class implemented as a
   * template, where the template type \c T is the type of the elements
   * assigned to each point in the lattice.
   *
   * If you need to create a lattice of floats with 255 elements indexed from
   * -127 to 127, all of them initialized with a value of 4.27 just create it
   * with
   *
   * \code
   * cvr::genericLattice1D<float> myLat(-127,127,4.27f);
   * \endcode
   *
   * To access the lattice elements use the access operators at() (or the
   * overloaded operator[]()).  For example:
   *
   * \code
   * float accu = 0; // initialize accumulator
   *
   * for (int i = myLat.firstIndex(); i <= myLat.lastIndex(); i++) {
   *   accu += myLat.at(i); // access each element of the vector
   * }
   * \endcode
   *
   * In the CVR-Lib, the debug-mode library always makes a boundary check for
   * both at() and operator[](), and in the release-mode there is no check for
   * any of both methods.
   *
   * @ingroup gAggregate
   */
  template<typename T>
  class genericLattice1D : public container {
  public:

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

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

    /**
     * Type of the genericLattice1D elements.
     */
    typedef typename genericVector<T>::value_type value_type;

    /**
     * Return type of the size() member
     */
    typedef typename genericVector<T>::size_type size_type;

    /**
     * Pointer to value_type
     */
    typedef typename genericVector<T>::pointer pointer;

    /**
     * Const pointer to value_type
     */
    typedef typename genericVector<T>::const_pointer const_pointer;
    
    /**
     * Reference to value_type
     */
    typedef typename genericVector<T>::reference reference;

    /**
     * Const reference to value_type
     */
    typedef typename genericVector<T>::const_reference const_reference;

    /**
     * \c 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::genericLattice1D::begin() and
     * cvr::genericLattice1D::inverseBegin() for examples.
     *
     * 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 genericLattice1D 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!
     *
     * @see genericLattice1D<T>::const_iterator
     */
    typedef typename genericVector<T>::iterator iterator;

    /**
     * \c const_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::genericLattice1D::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 genericLattice1D 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!
     *
     * @see genericLattice1D<T>::iterator
     */
    typedef typename genericVector<T>::const_iterator const_iterator;
    //@}

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

    /**
     * Create a genericLattice1D indexed by the given interval but do \b not
     * initialize its elements.
     *
     * @param from initial index.
     * @param to   final index.
     * 
     * The size of the container will be to-from+1.  The \c to value must be
     * greater or equal than the \c from value, otherwise an empty lattice will
     * be created.
     */
    explicit genericLattice1D(const size_type from,const size_type to);

    /**
     * Create a genericLattice1D indexed by the given interval but do \b not
     * initialize its elements.
     *
     * @param indices interval of indices to be used.
     */
    explicit genericLattice1D(const iinterval& indices);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given value.
     *
     * @param from initial index value
     * @param to final index value
     * @param iniValue all elements will be initialized with this value.
     */
    explicit genericLattice1D(const size_type from,
                              const size_type to,
                              const_reference iniValue);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given value.
     *
     * @param indices interval of indices to be used.
     * @param iniValue all elements will be initialized with this value.
     */
    explicit genericLattice1D(const iinterval& indices,
                              const_reference iniValue);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given data. The \a data will be copied.
     *
     * If you need to just use the memory block without copying it, then you
     * can wether use a third parameter of eConstantReference type or later
     * call the useExternData() method.
     *
     * @see useExternData()
     *
     * @param from initial index value
     * @param to final index value
     * @param data a pointer to the data that will be copied.
     */
    genericLattice1D(const size_type from,
                     const size_type to,
                     const value_type data[]);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given data. The \a data will be copied.
     *
     * If you need to just use the memory block without copying it, then you
     * can wether use a third parameter of eConstantReference type or later
     * call the useExternData() method.
     *
     * @see useExternData()
     *
     * @param indices interval of indices to be used.
     * @param data a pointer to the data that will be copied.
     */
    genericLattice1D(const iinterval& indices,
                     const value_type data[]);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given data, the same way "useExternData" does, i.e. the 
     * \a data will \b not be copied!.
     *
     * @see useExternData()
     *
     * @param from initial index
     * @param to final index
     * @param data a pointer to the data that will be used.
     * @param constRef if this parameter is \c ConstantReference it will not be
     *                 possible to change the pointer to the external memory
     *                 block nor to resize the genericLattice1D.  Despite this,
     *                 the value of each element can be changed by the access
     *                 operators.
     */
    genericLattice1D(const size_type from,
                     const size_type to,
                     value_type data[],
                     const eConstantReference constRef);

    /**
     * Create a genericLattice1D indexed by the given interval and initialize
     * it with the given data, the same way "useExternData" does, i.e. the 
     * \a data will \b not be copied!.
     *
     * @see useExternData()
     *
     * @param indices interval used for the lattice indices
     * @param data a pointer to the data that will be used.
     * @param constRef if this parameter is \c ConstantReference it will not be
     *                 possible to change the pointer to the external memory
     *                 block nor to resize the genericLattice1D.  Despite this,
     *                 the value of each element can be changed by the access
     *                 operators.
     */
    genericLattice1D(const iinterval& indices,
                     value_type data[],
                     const eConstantReference constRef);

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

    /**
     * Create this genericLattice1D as a copy of the specified interval of
     * elements of another genericLattice1D.  The \c from and \c to values are
     * truncated to the interval used by the \c other lattice.
     *
     * @param other the genericLattice1D to be copied.
     * @param from starting index of \c other lattice.
     * @param to end index of the \c other lattice.
     */
    genericLattice1D(const genericLattice1D<T>& other,
                     const size_type from, const size_type to=MaxIndex);

    /**
     * Create this genericLattice1D as a copy of the specified interval of
     * elements of another genericLattice1D.  The \c from and \c to values are
     * truncated to the interval used by the \c other lattice.
     *
     * @param other the genericLattice1D to be copied.
     * @param indices index interval of the elements of \c other to be copied.
     */
    genericLattice1D(const genericLattice1D<T>& other,
                     const iinterval& indices);


    /**
     * Create this genericLattice1D as a copy of another std::vector<T>
     *
     * @param other the genericLattice1D to be copied.
     * @param firstIndex index to be used for the first element of the vector.
     */
    genericLattice1D(const std::vector<T>& other,const int firstIndex=0);

    /**
     * Create this genericLattice1D as a copy of another cvr::genericVector.
     *
     * @param other the genericLattice1D to be copied.
     * @param firstIndex optional argument indicating which index is
     *        going to be assigned to the first vector element.
     */
    genericLattice1D(const genericVector<T>& other,const int firstIndex=0);

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

    /**
     * Check whether this %object owns the data.
     *
     * @return \a false if this genericLattice1D contains a reference to extern
     * data.
     */
    inline bool ownsData() const;

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

    /**
     * Reference to extern data.
     *
     * This member allows the use of this %object as an wrapper-%object to
     * access some memory block as a genericLattice1D.
     * The user must take care for memory allocation and deallocation of
     * the block.  This %object will never delete the external data!.
     *
     * @param from initial index
     * @param to   final index
     * @param data    pointer to the external memory block.
     * @param constRef if this parameter is true, it will not be possible to
     *                 change the pointer to the external memory block nor to
     *                 resize the genericLattice1D.  Despite this, the value of
     *                 each element can be changed by the access operators.
     *
     * For Example:
     * \code
     * int i;
     * double tmp;
     * double a[10];               // memory block!
     *
     * for (i=0;i<10;i++) {
     *   a[i]=2*i;                 // initialize the memory block
     * }
     *
     * cvr::genericLattice1D<double> myLat;  // an empty genericLattice1D
     *
     * myLat.resize(-2,2,0);       // resize the genericLattice1D: now 5
     *                             // elements initialized with 0
     *
     * myLat.useExternData(-4,5,a,true); // use the genericLattice1D as wrapper
     *                             // for the memory block
     *
     * tmp = myLat.at(5);          // tmp is now 10
     *
     * myLat.at(9) = 3;            // the last element of myLat
     *                             // has now the value 3
     *
     * myLat.resize(0,5);          // INVALID!! this will throw an exception
     *                             // constReferenceException()
     * \endcode
     *
     *
     * If the size (from-to+1) is greater than the allocated memory, the
     * behaviour could be unpredictible.
     */
    inline void 
    useExternData(const size_type from,
                  const size_type to,
                  pointer data,
                  const eConstantReference constRef=VariableReference);

    /**
     * Reference to extern data.
     *
     * This member allows the use of this %object as an wrapper-%object to
     * access some memory block as a genericLattice1D.
     * The user must take care for memory allocation and deallocation of
     * the block.  This %object will never delete the external data!.
     *
     * @param indices interval to be used by the lattice to access the data.
     *                Note that this is NOT the number of bytes of the external
     *                block.
     * @param data    pointer to the external memory block.
     * @param constRef if this parameter is true, it will not be possible to
     *                 change the pointer to the external memory block nor to
     *                 resize the genericLattice1D.  Despite this, the value of
     *                 each element can be changed by the access operators.
     *
     * For Example:
     * \code
     * int i;
     * double tmp;
     * double a[10];               // memory block!
     *
     * for (i=0;i<10;i++) {
     *   a[i]=2*i;                 // initialize the memory block
     * }
     *
     * cvr::genericLattice1D<double> myLat;  // an empty genericLattice1D
     *
     * myLat.resize(-2,2,0);       // resize the genericLattice1D: now 5
     *                             // elements initialized with 0
     *
     * myLat.useExternData(-4,5,a,true); // use the genericLattice1D as wrapper
     *                             // for the memory block
     *
     * tmp = myLat.at(5);          // tmp is now 10
     *
     * myLat.at(9) = 3;            // the last element of myLat
     *                             // has now the value 3
     *
     * myLat.resize(0,5);          // INVALID!! this will throw an exception
     *                             // constReferenceException()
     * \endcode
     *
     *
     * If the size (from-to+1) is greater than the allocated memory, the
     * behaviour could be unpredictible.
     */
    inline void 
    useExternData(const iinterval& indices,
                  pointer data,
                  const eConstantReference constRef=VariableReference);

    /**
     * Attach extern data to the vector.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at(x) is equivalent to
     * data[x].
     * If \a theSize is an invalid dimension, the behaviour will be
     * unpredictible.
     *
     * The memory will be administrated by this genericLattice1D
     * instance, and may be deleted if required (e.g. genericLattice1D 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
     * @param data a pointer to the memory block to be used
     *
     * Example:
     * \code
     * cvr::genericLattice1D<int> myLat;
     * int block1[25];
     * int* block2;
     * block2 = new int[25];
     *
     * myLat.useExternData(25,block1); // ok
     * myLat.attach(25,block1); // wrong!!! matrix will try to manipulate
     *                          // stack memory: DO NOT DO THIS!!!!!
     * myLat.attach(25,block2); // ok!  but do not try to delete the memory
     *                          //      block2!!
     * \endcode
     */
    inline void attach(const size_type from,
                       const size_type to,
                       value_type data[]);

    /**
     * Attach extern data to the vector.
     *
     * This member allows the use of this %object as an access-functor for
     * the 'data'. An access to the element at(x) is equivalent to
     * data[x].
     * If \a theSize is an invalid dimension, the behaviour will be
     * unpredictible.
     *
     * The memory will be administrated by this genericLattice1D
     * instance, and may be deleted if required (e.g. genericLattice1D deleted
     * or resized!).  The user should not try to manipulate the memory
     * allocation of the data after the attachment!  See also
     * useExternData().
     *
     * @param indices interval of indices for the lattice.
     * @param data a pointer to the memory block to be used
     *
     * Example:
     * \code
     * cvr::genericLattice1D<int> myLat;
     * int block1[25];
     * int* block2;
     * block2 = new int[25];
     *
     * myLat.useExternData(25,block1); // ok
     * myLat.attach(25,block1); // wrong!!! matrix will try to manipulate
     *                          // stack memory: DO NOT DO THIS!!!!!
     * myLat.attach(25,block2); // ok!  but do not try to delete the memory
     *                          //      block2!!
     * \endcode
     */
    inline void attach(const iinterval& indices,pointer 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
     * genericLattice1D.  It is a very efficient way to make a copy of
     * this genericLattice1D, if you don't need the source data anymore!
     *
     * \b Note: Take care that if the attach() or useExternData()
     * methods of this genericLattice1D have been called before detachment, the
     * same rules for memory management apply now for the receiver.
     *
     * At the end of the detachment, this genericLattice1D will be empty.
     * @param receiver the genericLattice1D which will receive the memory
     *        block.  All data of that genericLattice1D will be first deleted!
     */
    void detach(genericLattice1D<T>& receiver);

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

    /**
     * Returns the number of elements of the genericLattice1D
     */
    inline size_type size() const;

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

    /**
     * Returns iterator pointing to the first element.
     *
     * The use of the iterators is similar to the iterators of the
     * Standard Template Library (STL).
     * If you need to iterate on all elements of the genericLattice1D, you can
     * use following code:
     *
     * \code
     *   int tmp,accu;                        // a temporal variable
     *   // genericLattice1D with 10 elements
     *   cvr::genericLattice1D<int> myLat(10,1); 
     *   // an iterator set to the beginning of myLat
     *   cvr::genericLattice1D<int>::iterator it=myLat.begin();
     *   // an iterator set to the end of myLat
     *   cvr::genericLattice1D<int>::iterator eit=myLat.begin();
     *
     *   for (; it!=eit ; ++it) {
     *     tmp = *it;     // tmp has value of element pointed
     *                    // by the iterator.
     *     accu += tmp;
     *     (*it) = accu;  // change the value in the genericLattice1D.
     *   }
     * \endcode
     *
     * \note It is significantly faster in debug builds to use a pre-increment
     * with iterators (++it) than a post-increment (it++).
     *
     * Please note that if you define \a it as a const_iterator, you can not do
     * something like \a *it=accu.
     */
    inline iterator begin();

    /**
     * Returns first index (in a genericLattice1D this is always size()-1)
     */
    inline size_type firstIndex() const;

    /**
     * Returns last index (in a genericLattice1D this is always size()-1)
     */
    inline size_type lastIndex() const;

    /**
     * Returns last index as a const_iterator.
     *
     * For an example see begin()
     */
    inline const_iterator end() const;

    /**
     * Returns last index as an iterator
     *
     * For an example see begin()
     */
    inline iterator end();

    /**
     * This method returns an iterator that points to the \b last valid element
     * of the genericLattice1D. It is used for inverse order iteration through
     * the genericLattice1D using normal iterators (as opposed to
     * reverse_iterators used in the STL). 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.
     *
     * \code
     * igenericLattice1D v(false,10);
     * int i,tmp;
     * for (i=0; i<10; i++) {
     *   v.at(i)=i;
     * }
     * igenericLattice1D::iterator forwardIt=v.begin();
     * igenericLattice1D::iterator backIt=v.inverseBegin();
     *
     * while (forwardIt<=backIt) {
     *   tmp = (*forwardIt); (*forwardIt)=(*backIt); (*backIt)=tmp;
     *   ++forwardIt; ++backIt;
     * }
     * \endcode
     */
    inline iterator inverseBegin();

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

    /**
     * Return an iterator that points to the element \b
     * before the \b first valid element of the genericLattice1D. It is used to
     * mark the end for inverse order iteration through the genericLattice1D
     * using normal iterators (as opposed to reverse_iterators as used
     * in the STL). 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.
     */
    inline iterator inverseEnd();

    /**
     * Return an iterator that points to the element \b before the \b first
     * valid element of the genericLattice1D.
     */
    inline const_iterator inverseEnd() const;

    /**
     * Change dimension and if desired the contents of the genericVector.
     *
     * @param from initial index
     * @param to   final index
     * @param iniValue the initialization value.
     * @param resizeType specifies what should happen with the data of the
     *                   resized vector.
     *
     * For example:
     * \code
     *   cvr::genericVector<int> myVct;  // creates empty genericVector
     *   myVct.resize(5,0);       // genericVector with 5 elements initialized
     *                            // with 0
     *   myVct.resize(10,2);      // genericVector has now 10 elements: the
     *                            // first five are still 0 and the
     *                            // rest have a 2
     *   myVct.resize(20,3,cvr::AllocateOnly); // now the genericVector has 20
     *                                         // elements but their values
     *                                         // are unknown.
     *   myVct.resize(5,1,cvr::Init); // the genericVector has now 5
     *                                // elements initialized with 1
     *
     * \endcode
     *
     * If the resize is possible (see useExternData()), after the resize, this
     * %object will always own the data!
     *
     * @see eResizeType, resize(const int), allocate(), assign()
     */
    void resize(const size_type from,
                const size_type to,
                const_reference iniValue,
                const eResizeType resizeType=CopyAndInit);

    /**
     * Change dimension and if desired the contents of the genericVector.
     *
     * @param indices interval to be used by the lattice indices.
     * @param iniValue the initialization value.
     * @param resizeType specifies what should happen with the data of the
     *                   resized vector.
     *
     * For example:
     * \code
     *   cvr::genericVector<int> myVct;  // creates empty genericVector
     *   myVct.resize(5,0);       // genericVector with 5 elements initialized
     *                            // with 0
     *   myVct.resize(10,2);      // genericVector has now 10 elements: the
     *                            // first five are still 0 and the
     *                            // rest have a 2
     *   myVct.resize(20,3,cvr::AllocateOnly); // now the genericVector has 20
     *                                         // elements but their values
     *                                         // are unknown.
     *   myVct.resize(5,1,cvr::Init); // the genericVector has now 5
     *                                // elements initialized with 1
     *
     * \endcode
     *
     * If the resize is possible (see useExternData()), after the resize, this
     * %object will always own the data!
     *
     * @see eResizeType, resize(const int), allocate(), assign()
     */
    inline void resize(const iinterval& indices,
                       const_reference iniValue,
                       const eResizeType resizeType=CopyAndInit);

    /**
     * Resize the vector keeping all the old elements, but \b without
     * initializing the new ones.
     *
     * This is an alias for resize(from,to,T(),Copy);
     *
     * @param from initial index
     * @param to final index
     *
     * @see resize(const int,const_reference,const eResizeType)
     * @see allocate(),assign()
     */
    inline void resize(const size_type from,const size_type to);

    /**
     * Resize the vector keeping all the old elements, but \b without
     * initializing the new ones.
     *
     * This is an alias for resize(from,to,T(),Copy);
     *
     * @param indices interval used for the lattice indices.
     *
     * @see resize(const int,const_reference, const eResizeType),
     * @see allocate(),assign()
     */
    inline void resize(const iinterval& indices);

    /**
     * Change the vector to contain exactltly the given number of elements.  In
     * opposition to resize, allocate() does \b not copy the previous data but
     * only modifies the size of the vector, discarding all contained data and
     * leaving the new data uninitialized.
     *
     * This is in principle an alias to
     * resize(newSize,T(),AllocateOnly).
     *
     * @param from initial index
     * @param to final index
     * 
     * All current data will be discarded.
     *
     * @see eResizeType, resize(const int,const_reference, const eResizeType)
     * @see resize(const int),allocate(), assign()
     */
    inline void allocate(const size_type from,const size_type to);

    /**
     * Change the vector to contain exactltly the given number of elements.  In
     * opposition to resize, allocate() does \b not copy the previous data but
     * only modifies the size of the vector, discarding all contained data and
     * leaving the new data uninitialized.
     *
     * This is in principle an alias to
     * resize(newSize,T(),AllocateOnly).
     *
     * @param indices interval used for the indices of this lattice.
     * 
     * All current data will be discarded.
     *
     * @see eResizeType, 
     * @see resize(const int,const int,const_reference, const eResizeType)
     * @see resize(const int),allocate(), assign()
     */
    inline void allocate(const iinterval& indices);

    /**
     * Assign copies of \a initValue to the genericVector such that the given
     * interval is covered.
     *
     * Change the size and contents of this vector to be exactly \a newSize
     * elements long, with all the elements initialized to the value indicated
     * in \a initValue.  In opposition to resize, this method does \b not copy
     * the previous data but changes the size of the vector, discarding all
     * contained data, replacing it with \a newSize copies of \a initValue.
     *
     * This is in principle an alias to resize(newSize,T(),Init).
     *
     * @param from initial index.
     * @param to final index.
     * @param initValue all elements of the vector will be initialized with
     *        this value.
     */
    inline void assign(const size_type from,
                       const size_type to,
                       const_reference initValue);

    /**
     * Assign copies of \a initValue to the genericVector such that the given
     * interval is covered.
     *
     * Change the size and contents of this vector to be exactly \a newSize
     * elements long, with all the elements initialized to the value indicated
     * in \a initValue.  In opposition to resize, this method does \b not copy
     * the previous data but changes the size of the vector, discarding all
     * contained data, replacing it with \a newSize copies of \a initValue.
     *
     * This is in principle an alias to resize(newSize,T(),Init).
     *
     * @param indices interval of indices to be used.
     * @param initValue all elements of the vector will be initialized with
     *        this value.
     */
    inline void assign(const iinterval& indices,
                       const_reference initValue);

    /**
     * Removes all elements from the genericVector (Set dimensions to 0)
     */
    void clear();

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

    /**
     * Fills the genericLattice1D elements with \a iniValue between
     * \a from and \a to.
     * @param iniValue the elements will be initialized with this
     *                 value.
     * @param from     first element index
     * @param to       last element index
     *
     * If \a from or \a to are out of bounds, they will be (internaly) adjusted
     * to correct values.
     *
     * Example:
     * \code
     *   cvr::genericLattice1D<double> myLat(-1,8,0); // genericLattice1D with 
     *                                                // 10 elements with 0
     *   myLat.fill(9,1,3);                      // myLat=[0,0,9,9,9,0,0,0,0,0]
     * \endcode
     */
    void fill(const_reference iniValue,
              const size_type from = MinIndex,
              const size_type to = MaxIndex);

    /**
     * Fills the genericLattice1D elements with \a iniValue between
     * \a from and \a to.
     * @param iniValue the elements will be initialized with this value.
     * @param indices interval of the lattice to be filled in
     *
     * If \a from or \a to are out of bounds, they will be (internaly) adjusted
     * to correct values.
     *
     * Example:
     * \code
     *   cvr::genericLattice1D<double> myLat(0,9,0); // genericLattice1D with
     *                                               // 10 elements with 0
     *   myLat.fill(9,iinterval(1,3));          // myLat=[0,9,9,9,0,0,0,0,0,0]
     * \endcode
     */
    inline void fill(const_reference iniValue,
                     const iinterval& indices);

    /**
     * Fills the genericLattice1D elements with data pointed by \a data
     * between \a from and \a to.
     *
     * @param data the data to by copied into this genericLattice1D
     * @param from first element index
     * @param to   last element index
     *
     * If \a from or \a to are out of bounds, they will be (internaly) adjusted
     * to correct values.
     *
     * Example:
     * \code
     *   double* data = {2,4,8,16};
     *   cvr::genericLattice1D<double> myLat(10,0);// genericLattice1D with 10
     *                                             // elements with 0
     *   myLat.fill(data,1,3);             // myLat=[0,2,4,8,0,0,0,0,0,0]
     * \endcode
     */
    void fill(const value_type data[],
              const size_type from = MinIndex,
              const size_type to = MaxIndex);

    /**
     * Fills the genericLattice1D elements with data pointed by \a data
     * between \a from and \a to.
     * @param data the data to by copied into this genericLattice1D
     * @param indices interval of the lattice to be filled in.
     *
     * If \a from or \a to are out of bounds, they will be (internaly) adjusted
     * to to correct value.
     *
     * Example:
     * \code
     *   double* data = {2,4,8,16};
     *   cvr::genericLattice1D<double> myLat(-5,5,0);// genericLattice1D with
     *                                               // 11 elements with 0
     *   myLat.fill(data,1,3);             // myLat=[0,0,0,0,0,0,2,4,8,0,0]
     * \endcode
     */
    inline void fill(const value_type data[],const iinterval& indices);

    /**
     * Fills the genericLattice1D elements from \a from to \a to with the
     * elements of \a vct starting at \a startAt.
     *
     * @param lat genericLattice1D with the elements to be copied
     * @param from first element index of the actual genericLattice1D
     * @param to   last element index of the actual genericLattice1D
     * @param startAt start index of the source genericLattice1D \a vct.
     */
    inline void fill(const genericLattice1D<T>& lat,
                     const size_type from = MinIndex,
                     const size_type to   = MaxIndex,
                     const size_type startAt = 0);

    /**
     * Fills the genericLattice1D elements from \a from to \a to with the
     * elements of \a vct starting at \a startAt.
     *
     * @param vct genericLattice1D with the elements to be copied.
     * @param indices interval of the lattice to be filled.
     * @param startAt start index of the source genericLattice1D \a vct.
     */
    inline void fill(const genericLattice1D<T>& vct,
                     const iinterval& indices,
                     const size_type startAt = 0);

    /**
     * Access element x of the genericLattice1D
     *
     * @param x index of the genericLattice1D element to be accessed. It should
     * be between firstIndex() and lastIndex()
     */
    inline reference at(const size_type x);

    /**
     * Access element x of the genericLattice1D in a read-only modus.
     *
     * @param x index of the genericLattice1D element to be accessed. It should
     * be between firstIndex() and lastIndex()
     */
    inline const_reference at(const size_type x) const;

    /**
     * Access operator (alias for at(const size_type x)).
     */
    inline reference operator[](const size_type x);

    /**
     * Constant access operator (alias for at(const size_type x) const).
     */
    inline const_reference operator[](const size_type x) const;

    /**
     * Access element \p n of the genericLattice1D as a vector.
     *
     * The lattice is indexed from 0 to to-from.
     *
     * This member function is needed for generic programming with different
     * container types. 
     */
    inline reference elem(const size_type n);

    /**
     * Constant access to element \p n of the genericLattice1D as a vector.
     *
     * The lattice is indexed from 0 to to-from.
     *
     * This member function is needed for generic programming with different
     * container types.
     */
    inline const_reference elem(const size_type n) const;

    /**
     * Assigment operator.
     *
     * Copy the contents of \a other in this %object.
     *
     * If this instance has a constReference, then only the contents are
     * copied.
     *
     * @param other the source genericLattice1D to be copied.
     *
     * @return Reference to the current object.
     */
    genericLattice1D<T>& copy(const genericLattice1D<T>& other);

    /**
     * Assignment operator.
     *
     * Copy a specified interval of elements of another genericLattice1D.  At
     * the end this vector will contain t-f+1 elements, where
     * f=max(other.firstIndex(),from) and t=min(other.lastIndex(),to).
     *
     * @param other the genericLattice1D to be copied.
     * @param from starting index
     * @param to final index.
     *
     * @return Reference to the current object.
     */
    genericLattice1D<T>& copy(const genericLattice1D<T>& other,
                              const size_type from, 
                              const size_type to=MaxIndex);

    /**
     * Assignment operator.
     *
     * Copy a specified interval of elements of another genericLattice1D.  At
     * the end this vector will contain t-f+1 elements, where f=max(0,from) and
     * t=min(other.lastIndex()-1,to).
     *
     * @param other the genericLattice1D to be copied.
     * @param indices interval of the other lattice to be copied into this one.
     *
     * @return Reference to the current object.
     */
    inline genericLattice1D<T>& copy(const genericLattice1D<T>& other,
                                     const iinterval& indices);

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

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

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

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

    /**
     * Compare this genericLattice1D with other.
     *
     * @param other the other genericLattice1D to be compared with
     *
     * @return \c true if both genericLattice1Ds have the same elements and
     *          same definition interval
     */
    bool equals(const genericLattice1D<T>& other) const;

    /**
     * Compare this genericLattice1D with other.
     *
     * @param other the other genericLattice1D to be compared with
     *
     * @return true if both genericLattice1Ds have the same elements and same
     *         size
     */
    inline bool operator==(const genericLattice1D<T>& other) const;

    /**
     * Compare this genericLattice1D with other.
     *
     * @param other the other genericLattice1D to be compared with.
     *
     * @return true if both genericLattice1Ds different dimensions or elements
     */
    inline bool operator!=(const genericLattice1D<T>& other) const;

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

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

    /**
     * Copy a subvector of the \a other genericLattice1D by casting each of its
     * elements.
     *
     * @param other The genericLattice1D to be copied.
     * @param from starting point included
     * @param to end point included.
     *
     * @return A reference to the current casted subvector
     */
    template<typename U>
    genericLattice1D<T>& castFrom(const genericLattice1D<U>& other,
                                  const size_type from,
                                  const size_type to=MaxIndex);

    /**
     * Copy a subvector of the \a other genericLattice1D by casting each of its
     * elements.
     *
     * @param other The genericLattice1D to be copied.
     * @param indices interval of indices to be copied from \c other.
     *
     * @return A reference to the current casted subvector
     */
    template<typename U>
    inline genericLattice1D<T>& castFrom(const genericLattice1D<U>& other,
                                         const iinterval& indices);

    /**
     * This is just an alias for 
     * copy(const genericLattice1D<T>&,
     *      const size_type from, const size_type to)
     * to facilitate generic programming.
     *
     * @param other The genericLattice1D to be copied.
     * @param from starting point included
     * @param to end point included
     */
    genericLattice1D<T>& castFrom(const genericLattice1D<T>& other,
                                  const size_type from,
                                  const size_type to=MaxIndex);


    /**
     * This is just an alias for 
     * copy(const genericLattice1D<T>&, const size_type from, 
     *      const size_type to)
     * to facilitate generic programming.
     *
     * @param other The genericLattice1D to be copied.
     * @param indices interval of \c other to be copied in this lattice.
     */
    genericLattice1D<T>& castFrom(const genericLattice1D<T>& other,
                                  const iinterval& indices);

    /**
     * Cast from a std::genericLattice1D of the same type
     * @param other vector to be copied
     * @param firstIndex index used for the first element of the vector.
     */
    template<typename U>
    genericLattice1D<T>& castFrom(const std::vector<U>& other,
                                  const int firstIndex = 0);

    /**
     * Cast from a std::genericLattice1D of the same type
     * @param other vector to be copied
     * @param firstIndex index used for the first element of the vector.
     */
    template<typename U>
    genericLattice1D<T>& castFrom(const genericVector<U>& other,
                                  const int firstIndex = 0);

    /**
     * Get a read-only reference to this container as a vector
     */
    inline const genericVector<T>& getAsVector() const;

    /**
     * @name Apply Methods
     */
    //@{

    /**
     * Applies a C-function to each element of the genericLattice1D.
     *
     * In the following example, %genericLattice1D \a vct is initialized with
     * 4.0. After applying \a sqrt(), all elements of \a vct are 2.0.
     * \code
     * genericLattice1D<float> vct(4,4.0);
     * vct.apply(sqrt);
     * \endcode
     *
     * @param function a pointer to a C-function
     *
     * @return A reference to the actual genericLattice1D
     */
    genericLattice1D<T>& apply(T (*function)(T));

    /**
     * Applies a C-function to each element of the other genericLattice1D and
     * leaves the result here.
     *
     * @param other the source genericLattice1D
     * @param function a pointer to a C-function
     *
     * @return A reference to the actual genericLattice1D
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& other,
                               T (*function)(T));

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

    /**
     * Applies a C-function to each element the other genericLattice1D and
     * leaves the result here.
     *
     * @param other the genericLattice1D with the source data
     * @param function a pointer to a C-function
     *
     * @return A reference to the actual genericLattice1D
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& other,
                               T (*function)(const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this and the
     * given genericLattice1D and the result will be left in this
     * genericLattice1D.  Note that both genericLattice1Ds MUST have the same
     * size!  If both genericLattice1Ds have different size, the function will
     * throw an assertion without changing anything!
     *
     * @param other the second genericLattice1D to be considered (the first
     *              genericLattice1D will be this object!)
     * @param function a pointer to a two parameters C-function
     *
     * @return A reference to the actual genericLattice1D.
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& other,
                            T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this and the
     * given genericLattice1D and the result will be left in this
     * genericLattice1D.  Note that both genericLattice1Ds MUST have the same
     * size!  If both genericLattice1Ds have different size, the function will
     * throw an assertion without changing anything!
     *
     * @param other the second genericLattice1D to be considered (the first
     *              genericLattice1D will be this object!)
     * @param function a pointer to a two parameters C-function
     *
     * @return A reference to the actual genericLattice1D.
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& other,
                               T (*function)(T,T));

    /**
     * A two-parameter C-function receives the i-th elements of the given
     * genericLattice1Ds and leaves the result here.  Note that both
     * genericLattice1Ds MUST have the same size!  If both genericLattice1Ds
     * have different size, the function will throw an assertion without
     * changing anything!
     *
     * The following example uses cvr::min as function. The genericLattice1Ds
     * \a a and \a b contain the values [1,2,3,4] and [4,3,2,1],
     * respectively. After applying the function, %genericLattice1D \a c
     * contains the values [1,2,2,1].
     *
     * \code
     * igenericLattice1D a,b,c;
     * int i=0;
     * for (i=0; i<4; ++i) {
     *   a.at(i)=i+1;
     *   b.at(i)=4-i;
     * }
     * c.apply(a,b,cvr::min);
     * \endcode
     *
     * @param a the first genericLattice1D
     * @param b the second genericLattice1D
     * @param function a pointer to a two parameters C-function
     *
     * @return A reference to the actual genericLattice1D
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& a,
                               const genericLattice1D<T>& b,
                               T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of the
     * given genericLattice1Ds and leaves the result here.
     *
     * Note that both genericLattice1Ds MUST have the same size!  If both
     * genericLattice1Ds have different size, the function will throw an
     * assertion without changing anything!
     *
     * @param a the first genericLattice1D
     * @param b the second genericLattice1D
     * @param function a pointer to a two parameters C-function
     *
     * @return a reference to the actual genericLattice1D
     */
    genericLattice1D<T>& apply(const genericLattice1D<T>& a,
                               const genericLattice1D<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:
    /**
     * Index of the last element of the genericLattice1D.
     *
     * We sacrifice this sizeof(int) to improve speed in many operations that
     * require this first index.
     */
    size_type first_;

    /**
     * Index of the last element of the genericLattice1D (always
     * vectorSize-1)
     *
     * We sacrifice this sizeof(int) to improve speed in many operations that
     * require this last index.
     */
    size_type last_;

    /**
     * Pointer to the element with index zero.
     */
    pointer theElements0_;

    /**
     * A generic vector is used to contain the data.
     */
    genericVector<T> data_;
  };

} // namespace cvr

namespace std {
  /*
   * outputs the elements of the genericLattice1D on a std::stream
   */
  template <typename T>
  ostream& operator<<(ostream& s,const cvr::genericLattice1D<T>& v);
}

#include "cvrGenericLattice1D_inline.h"
#include "cvrGenericLattice1D_template.h"

#else

#include "cvrGenericLattice1D_template.h"

#endif