/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */

/*
  $Id: vctFixedSizeConstVectorRef.h,v 1.15 2007/04/26 19:33:58 anton Exp $
  
  Author(s):	Ofri Sadowsky, Anton Deguet
  Created on:	2003-09-30

  (C) Copyright 2003-2007 Johns Hopkins University (JHU), All Rights
  Reserved.

--- begin cisst license - do not edit ---

This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.

--- end cisst license ---
*/


/*! 
  \file 
  \brief Declaration of vctFixedSizeConstVectorRef
 */


#ifndef _vctFixedSizeConstVectorRef_h
#define _vctFixedSizeConstVectorRef_h


#include <cisstVector/vctFixedSizeVectorBase.h>


/*!  \brief An implementation of the ``abstract''
  vctFixedSizeConstVectorBase.

  \ingroup cisstVector

  This implementations uses a pointer to the vector beginning as the
  vector defining data member.  An instantiation of this type can be
  used as a subsequence with GetConstSubsequence().

  Note that the class provides only const operations, except for
  assigning the vector start, which does not affect the vector.
  This is despite the fact that the stored pointer is non-const.
 
  See the base class (vctFixedSizeConstVectorBase) for template
  parameter details.
*/
template<class _elementType, unsigned int _size, int _stride>
class vctFixedSizeConstVectorRef : public vctFixedSizeConstVectorBase<
    _size, _stride, _elementType, 
    typename vctFixedSizeVectorTraits<_elementType, _size, _stride>::pointer >
{
 public:
    VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType);
    typedef vctFixedSizeVectorTraits<_elementType, _size, _stride> VectorTraits;
    typedef vctFixedSizeConstVectorRef<value_type, _size, _stride> ThisType;
    typedef vctFixedSizeConstVectorBase<_size, _stride, value_type, pointer> BaseType;
    typedef typename BaseType::CopyType CopyType;
    

    /*! Default constructor: create an uninitialized vector */
    vctFixedSizeConstVectorRef() {}

    /*! Initialize the vector with a (non-const) pointer */
    vctFixedSizeConstVectorRef(pointer p) {
        SetRef(p);
    }
    
    /*! Initialize the vector with a const pointer.  This requires
      const_cast. */
    vctFixedSizeConstVectorRef(const_pointer p) {
        SetRef(p);
    }


    /*! Initialize a fixed size reference to a fixed-size vector.
      \note There is no need to declare this constructor as explicit, because a vctFixedSizeConstVectorRef
      protects the content.
      \note The stride values are taken from the fixed size vector.
    */
    template<unsigned int __size, class __dataPtrType>
    vctFixedSizeConstVectorRef(const vctFixedSizeConstVectorBase<__size, _stride, _elementType, __dataPtrType> & otherVector,
                                        size_type startPosition = 0)
    {
        SetRef(otherVector, startPosition);
    }

    /*! Initialize a fixed size reference to a dynamic vector.
      \note This constructor is declared as explicit, since it is atypical.
    */
    template<class __vectorOwnerType>
    explicit vctFixedSizeConstVectorRef(const vctDynamicConstVectorBase<__vectorOwnerType, _elementType> & otherVector,
                                        size_type startPosition = 0)
    {
        SetRef(otherVector, startPosition);
    }

    
    /*! Assign the vector start with a (non-const) pointer */
    void SetRef(pointer p) {
        this->Data = p;
    }

    
    /*! Assign the vector start with a const pointer.  This requires const_cast. */
    void SetRef(const_pointer p) {
        this->Data = const_cast<pointer>(p);
    }

    /*! Set a fixed size reference to a fixed-size vector.
      \note the stride of the input vector must be identical to the stride of this
      vector (this is enforced by the template parameters).
      \note this vector must be contained in the input vector, that is, startPos+_size <= __size
      (otherwise cmnThrow is used to throw std::out_of_range).
    */
    template<unsigned int __size, class __dataPtrType>
    void SetRef(const vctFixedSizeConstVectorBase<__size, _stride, _elementType, __dataPtrType> & otherVector,
                size_type startPosition = 0)
    {
        if (startPosition + this->size() > otherVector.size()) {
            cmnThrow(std::out_of_range("vctFixedSizeConstVectorRef SetRef out of range"));
        }
        SetRef(otherVector.Pointer(startPosition));
    }

    /*! Set a fixed size reference to a dynamic vector.
      \note the stride of the input vector must be identical to the stride of this
      vector (otherwise cmnThrow is used to throw std::runtime_error).
      \note this vector must be contained in the input vector, that is, startPos+_size <= __size
      (otherwise cmnThrow is used to throw std::out_of_range).
    */
    template<class __vectorOwnerType>
    void SetRef(const vctDynamicConstVectorBase<__vectorOwnerType, _elementType> & otherVector,
                size_type startPosition = 0)
    {
        if (this->stride() != otherVector.stride()) {
            cmnThrow(std::runtime_error("vctFixedSizeConstVectorRef SetRef with incompatible stride"));
        }
        if (startPosition + this->size() > otherVector.size()) {
            cmnThrow(std::out_of_range("vctFixedSizeConstVectorRef SetRef out of range"));
        }
        SetRef(otherVector.Pointer(startPosition));
    }

};


#endif  // _vctFixedSizeConstVectorRef_h


// ****************************************************************************
//                              Change History
// ****************************************************************************
//
// $Log: vctFixedSizeConstVectorRef.h,v $
// Revision 1.15  2007/04/26 19:33:58  anton
// All files in libraries: Applied new license text, separate copyright and
// updated dates, added standard header where missing.
//
// Revision 1.14  2006/11/20 20:33:20  anton
// Licensing: Applied new license to cisstCommon, cisstVector, cisstNumerical,
// cisstInteractive, cisstImage and cisstOSAbstraction.
//
// Revision 1.13  2006/10/16 20:45:10  anton
// cisstVector: Corrected and completed tests on size and strides for the
// SetRef on all containers (see #247).
//
// Revision 1.12  2005/09/27 18:01:25  anton
// cisstVector: Use CMN_ASSERT instead of assert for vectors and matrices.
//
// Revision 1.11  2005/09/26 15:41:47  anton
// cisst: Added modelines for emacs and vi.
//
// Revision 1.10  2005/06/16 03:38:29  anton
// Port to gcc 3.4 (common, vector and numerical) tested with gcc 3.3 and MS
// VC 7.1 (.Net 2003).
//
// Revision 1.9  2005/05/19 19:29:01  anton
// cisst libs: Added the license to cisstCommon and cisstVector
//
// Revision 1.8  2005/02/13 20:16:06  ofri
// Removed the keyword *explicit* from constructor of vctFixedSizeConstVectorRef.
// See ticket #123.
//
// Revision 1.7  2005/02/08 21:30:26  ofri
// vctFixedSize(Const)VectorRef: Corrected syntax error in SetRef(dynamic) :
// replaced = with ==.
//
// Revision 1.6  2005/01/06 18:54:00  anton
// cisstVector: Introduction of type CopyType as requested in ticket #113.
//
// Revision 1.5  2004/11/11 20:35:46  anton
// cisstVector: *: Added a vctContainerTraits to centralize the declarations
// of size_type, difference_type, reference, const_reference, etc. *: All
// iterators are now derived from std::iterator. *: Added some missing typedef
// for iterators.
//
// Revision 1.4  2004/10/26 15:20:52  ofri
// Updating subsequence interfaces (ticket #76) and interfaces between fixed
// and dynamic vectors/matrices (ticket #72).
// *: vctFixedSize(Const)VectorBase::Get(Const)Subsequence now deprecated.
// Replaced by Get(Const)Subvector with equal stride to the parent.
// *: Added constructors for [Fixed|Dynamic][Vector|Matrix]Ref from the other
// storage type.
//
// Revision 1.3  2004/10/25 19:19:54  anton
// cisstVector:  Created vctForwardDeclarations.h and removed forward
// declarations of classes in all other files.  Added some constructors
// for vector references to reference fixed size from dynamic and vice versa.
//
// Revision 1.2  2004/10/25 13:52:05  anton
// Doxygen documentation:  Cleanup all the useless \ingroup.
//
// Revision 1.1  2004/08/13 17:47:40  anton
// cisstVector: Massive renaming to replace the word "sequence" by "vector"
// (see ticket #50) as well as another more systematic naming for the engines.
// The changes for the API are as follow:
// *: vctFixedLengthSequenceBase -> vctFixedSizeVectorBase (and Const)
// *: vctFixedLengthSequenceRef -> vctFixedSizeVectorRef (and Const)
// *: vctDynamicSequenceBase -> vctDynamicVectorBase (and Const)
// *: vctDynamicSequenceRef -> vctDynamicVectorRef (and Const)
// *: vctDynamicSequenceRefOwner -> vctDynamicVectorRefOwner
// *: vctFixedStrideSequenceIterator -> vctFixedStrideVectorIterator (and Const)
// *: vctVarStrideSequenceIterator -> vctVarStrideVectorIterator (and Const)
// *: vctSequenceRecursiveEngines -> vctFixedSizeVectorRecursiveEngines
// *: vctSequenceLoopEngines -> vctDynamicVectorLoopEngines
// *: vctMatrixLoopEngines -> vctFixedSizeMatrixLoopEngines
// *: vctDynamicMatrixEngines -> vctDynamicMatrixLoopEngines
// Also updated and corrected the documentation (latex, doxygen, figures) as
// well as the tests and examples.
//
// Revision 1.4  2004/08/11 20:38:15  ofri
// Removed redundant subsequence definitions from vctFixedLengthSequenceRef
// and vctFixedLengthConstSequenceRef, as they are now defined in the base
// types.
// Added excluded code in vctFixedLengthConstSequenceBase to conditionally
// evaulate a compilation error.  Pending decision before including.
//
// Revision 1.3  2004/07/27 20:08:06  anton
// cisstVector: Added some Doxygen documentation.  Minor code changes to
// keep the dynamic vectors in sync with the fixed size ones.
//
// Revision 1.2  2004/07/02 16:16:45  anton
// Massive renaming in cisstVector for the addition of dynamic size vectors
// and matrices.  The dynamic vectors are far from ready.
//
// Revision 1.1  2003/11/20 18:31:04  anton
// Splitted const and non const classes in two files.  Renamed FixedLengthSequence to FixedLengthSequenceRef
//
//
// Revision 1.8  2003/11/11 22:04:50  anton
// STRIDE undeclared, uses _stride (idem for size).  Added assignement operator from vctFixedLengthConstSequenceBase
//
// Revision 1.7  2003/11/10 21:40:43  anton
// Added operator =
//
// Revision 1.6  2003/11/03 21:31:31  ofri
// Changed the order of template parameters when refering to
// vctFixedLengthSequenceBase (_elementType now comes third instead of first).
// This change of order does not apply to the definition of vctFixedLengthSequence
// itself.
//
// Revision 1.5  2003/10/20 18:35:19  anton
// Changed FixedSizeVectorOperations and FixedSizeVectorTraits to FixedLengthSequence Operations and Traits
//
// Revision 1.4  2003/10/20 17:07:15  anton
// Removed commented code
//
// Revision 1.3  2003/10/03 19:15:51  anton
// Updated doxygen documentation
//
// Revision 1.2  2003/09/30 18:47:16  anton
// Renamed template parameters __stride to _subStride
//
// Revision 1.1  2003/09/30 14:02:49  anton
// creation
//
//
// ****************************************************************************