/* -*- 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: vctDynamicVectorOwner.h,v 1.20 2007/04/26 19:33:58 anton Exp $
  
  Author(s):	Ofri Sadowsky, Anton Deguet
  Created on: 2004-07-01

  (C) Copyright 2004-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 ---
*/


#ifndef _vctDynamicVectorOwner_h
#define _vctDynamicVectorOwner_h


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


#include <cisstVector/vctFixedStrideVectorIterator.h>


/*!
  This templated class owns a dynamically allocated array, but does
  not provide any other operations */
template<class _elementType>
class vctDynamicVectorOwner
{
public:
    /* define most types from vctContainerTraits */
    VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType);

    /* iterators are container specific */    
    enum { DEFAULT_STRIDE = 1 };
#ifndef SWIG
    typedef vctFixedStrideVectorConstIterator<value_type, DEFAULT_STRIDE> const_iterator;
    typedef vctFixedStrideVectorConstIterator<value_type, -DEFAULT_STRIDE> const_reverse_iterator;
    typedef vctFixedStrideVectorIterator<value_type, DEFAULT_STRIDE> iterator;
    typedef vctFixedStrideVectorIterator<value_type, -DEFAULT_STRIDE> reverse_iterator;
#endif // SWIG

    vctDynamicVectorOwner()
        : Size(0)
        , Data(0)
    {}
    
    vctDynamicVectorOwner(size_type size):
        Size(0)
    {
        SetSize(size);
    }
    
    ~vctDynamicVectorOwner() {
        Disown();
    }
    
    size_type size(void) const {
        return Size;
    }

    int stride() const
    {
        return DEFAULT_STRIDE;
    }
    
    pointer Pointer(index_type index = 0) {
        return Data + index;
    }
    
    const_pointer Pointer(index_type index = 0) const {
        return Data + index;
    }
    
    const_iterator begin(void) const {
        return const_iterator(Data);
    }

    const_iterator end(void) const {
        return const_iterator(Data + Size);
    }

    iterator begin(void) {
        return iterator(Data);
    }

    iterator end(void) {
        return iterator(Data + Size);
    }

    const_reverse_iterator rbegin(void) const {
        return const_reverse_iterator(Data + Size - 1);
    }

    const_reverse_iterator rend(void) const {
        return const_reverse_iterator(Data - 1);
    }

    reverse_iterator rbegin(void) {
        return reverse_iterator(Data + Size-1);
    }

    reverse_iterator rend(void) {
        return reverse_iterator(Data - 1);
    }

    /*!  Non-preserving resize operation.  This method discards of all
      the current data of the dynamic array and allocates new space in
      the requested size.

      \note If the size is unchanged, this method does nothing.

      \note If the size is set to zero, the data pointer is set to
      null (0).
     */
    void SetSize(size_type size) {
        if (size == Size) return;
        Disown();
        Own(size, (size == 0) ? 0 : new value_type[size]);
    }

    /*! Data preserving resize operation.  This method allocates a
      buffer of the input size and copies all possible old buffer
      elements to the new buffer.  If the new buffer is larger than
      the old, the tail elements are initialized with a default
      constructor.

      \note If the size is unchanged, this method does nothing.

      \note If the size is set to zero, the data pointer is set to
      null (0).
    */
    void resize(size_type size) {
        if (size == Size) return;
        const size_type oldSize = Size;
        value_type * oldData = Release();
        SetSize(size);
        const size_type minSize = std::min(oldSize, size);
        std::copy(oldData, oldData + minSize, Data);
        delete[] oldData;
    }

    /*! Release the currently owned data pointer from being owned.
      Reset this owner's data pointer and size to zero.  Return the
      old data pointer without freeing memory.
     */
    value_type * Release()
    {
        value_type * oldData = Data;
        Data = 0;
        Size = 0;
        return oldData;
    }

    /*! Have this owner take ownership of a new data pointer. Return
      the old data pointer without freeing memory.
    */
    value_type * Own(size_type size, value_type * data) {
        value_type * oldData = Data;
        Size = size;
        Data = data;
        return oldData;
    }

    /*! Free the memory allocated for the data pointer.  Reset data
      pointer and size to zero.
    */
    void Disown(void) {
        delete[] Data;
        Size = 0;
        Data = 0;
    }
    

protected:
    size_type Size;
    value_type* Data;
};


#endif // _vctDynamicVectorOwner_h


// ****************************************************************************
//                              Change History
// ****************************************************************************
//
//  $Log: vctDynamicVectorOwner.h,v $
//  Revision 1.20  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.19  2007/04/09 15:01:05  ofri
//  vctDynamic[Vector|Matrix|NArray]Owner:
//  1) Created a uniform implementation of constructors and SetSize methods,
//  following ticket #274.
//  2) Removed obsolete constructor (#275)
//  3) Cosmetic changes in the NArray owner.
//
//  Revision 1.18  2007/04/03 18:17:01  anton
//  vctDynamic{Vector,NArray}Owner: For both ctor and SetSize(), handles cases
//  when total size is zero (do not perform "new").  See #125.
//
//  Revision 1.17  2006/11/20 20:33:20  anton
//  Licensing: Applied new license to cisstCommon, cisstVector, cisstNumerical,
//  cisstInteractive, cisstImage and cisstOSAbstraction.
//
//  Revision 1.16  2006/11/08 04:28:20  anton
//  vctDynamic{Vector,Matrix}Owner: Changed behavior of SetSize() and resize()
//  so that if the size is zero, the data pointer is also 0 (aka null).
//
//  Revision 1.15  2005/09/26 15:41:47  anton
//  cisst: Added modelines for emacs and vi.
//
//  Revision 1.14  2005/07/28 20:54:13  anton
//  vctDynamic{Vector,Matrix}Owner: Modified SetSize() and resize() to do
//  nothing if the size of container is unchanged.
//
//  Revision 1.13  2005/05/19 19:29:01  anton
//  cisst libs: Added the license to cisstCommon and cisstVector
//
//  Revision 1.12  2005/04/02 23:04:49  anton
//  cisstVector:  Added conditional compilation for SWIG in dynamic containers.
//
//  Revision 1.11  2004/11/29 17:31:28  anton
//  cisstVector: Major corrections for matrices reverse iterators.  Correction
//  of the - operator which now takes into account the current column position.
//
//  Revision 1.10  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.9  2004/10/25 13:52:05  anton
//  Doxygen documentation:  Cleanup all the useless \ingroup.
//
//  Revision 1.8  2004/08/16 19:19:49  anton
//  cisstVector: Replaced a couple of "value_type *" by typedefed "pointer"
//  and "const value_type *" by "const_pointer".
//
//  Revision 1.7  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.6  2004/07/06 19:42:50  ofri
//  Giving the dynamic vector classes "standard look and feel" in terms of type
//  members, constructors, and indentations.  I made sure that the corresponding
//  example compiles and runs successfully.
//
//  Revision 1.5  2004/07/06 17:47:11  anton
//  Dynamic Sequences:
//  *: Compilation error re. const and const_iterator
//  *: Added some iterator methods to sequences
//  *: Compilation errors re. the order (size, stride, data) in constructor.  The order is now (size, data, stride = 1) everywhere to be consistant
//  *: The method Resize is now resize (STL spelling)
//
//  Revision 1.4  2004/07/06 00:53:16  ofri
//  Added reverse iterators to vctDynamicVectorOwner and vctDynamicSequenceRefOwner.
//  Fixed some bugs in vctDynamicVectorOwner.
//
//  Revision 1.3  2004/07/02 20:11:58  anton
//  vctDynamicVectorOwner::SetSize was not setting the data member Size correctly.
//
//  Revision 1.2  2004/07/02 18:18:31  anton
//  Introduced an index_type which might have to be moved to some kind of traits
//
//  Revision 1.1  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.
//
//
// ****************************************************************************