Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Teuchos_ArrayRCPDecl.hpp
Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 //
00004 //                    Teuchos: Common Tools Package
00005 //                 Copyright (2004) Sandia Corporation
00006 //
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 //
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00038 //
00039 // ***********************************************************************
00040 // @HEADER
00041 
00042 
00043 #ifndef TEUCHOS_ARRAY_RCP_DECL_HPP
00044 #define TEUCHOS_ARRAY_RCP_DECL_HPP
00045 
00046 
00047 #include "Teuchos_RCP.hpp"
00048 #include "Teuchos_Exceptions.hpp"
00049 #include "Teuchos_ArrayViewDecl.hpp"
00050 
00051 
00052 namespace Teuchos {
00053 
00126 template<class T>
00127 class ArrayRCP {
00128 public:
00130 
00131 
00133   typedef Teuchos_Ordinal Ordinal;
00134 
00136   typedef Ordinal size_type;
00137 
00139   typedef Ordinal difference_type;
00140 
00142   typedef std::random_access_iterator_tag iterator_category;
00143 
00145   typedef  T* iterator_type;
00146 
00148   typedef  T value_type;
00149 
00151   typedef T& reference;
00152 
00154   typedef const T& const_reference;
00155 
00157   typedef T* pointer;
00158 
00160   typedef T* const_pointer;
00161 
00163   typedef T  element_type;
00164 
00165 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00166 
00167   typedef ArrayRCP<T> iterator;
00169   typedef ArrayRCP<const T> const_iterator;
00170 #else
00171 
00172   typedef T* iterator;
00174   typedef const T* const_iterator;
00175 #endif
00176 
00178 
00179 
00180 
00193   inline ArrayRCP( ENull null_arg = null );
00194 
00216   inline ArrayRCP( T* p, size_type lowerOffset, size_type size,
00217     bool has_ownership, const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP );
00218 
00241   template<class Dealloc_T>
00242   inline ArrayRCP( T* p, size_type lowerOffset, size_type size, Dealloc_T dealloc,
00243     bool has_ownership );
00244 
00260   inline explicit ArrayRCP( size_type size, const T& val = T() );
00261 
00280   inline ArrayRCP(const ArrayRCP<T>& r_ptr);
00281 
00292   inline ~ArrayRCP();
00293 
00321   inline ArrayRCP<T>& operator=(const ArrayRCP<T>& r_ptr);
00322 
00324 
00325 
00326 
00328   inline bool is_null() const;
00329 
00337   inline T* operator->() const;
00338 
00346   inline T& operator*() const;
00347 
00353   inline T* get() const;
00354 
00360   inline T* getRawPtr() const;
00361 
00367   inline T& operator[](size_type offset) const;
00368 
00370 
00371 
00372 
00381   inline ArrayRCP<T>& operator++();
00382 
00391   inline ArrayRCP<T> operator++(int);
00392 
00401   inline ArrayRCP<T>& operator--();
00402 
00411   inline ArrayRCP<T> operator--(int);
00412 
00421   inline ArrayRCP<T>& operator+=(size_type offset);
00422 
00431   inline ArrayRCP<T>& operator-=(size_type offset);
00432 
00445   inline ArrayRCP<T> operator+(size_type offset) const;
00446 
00459   inline ArrayRCP<T> operator-(size_type offset) const;
00460 
00462 
00463 
00464 
00475   inline iterator begin() const;
00476 
00487   inline iterator end() const;
00488 
00490 
00491 
00492 
00498   inline ArrayRCP<const T> getConst() const;
00499 
00513   inline ArrayRCP<T> persistingView( size_type lowerOffset, size_type size ) const;
00514 
00516 
00517 
00518 
00520   inline size_type lowerOffset() const;
00521 
00523   inline size_type upperOffset() const;
00524 
00529   inline size_type size() const;
00530 
00532 
00533 
00534 
00548   inline ArrayView<T> view( size_type lowerOffset, size_type size ) const;
00549 
00554   inline ArrayView<T> operator()( size_type lowerOffset, size_type size ) const;
00555 
00560   inline ArrayView<T> operator()() const;
00561 
00563 
00564 
00565 
00572   inline operator ArrayRCP<const T>() const;
00573 
00575 
00576 
00577 
00582   inline void assign(size_type n, const T &val);
00583 
00591   template<class Iter>
00592   inline void assign(Iter first, Iter last);
00593 
00599   inline void deepCopy(const ArrayView<const T>& av);
00600 
00602   inline void resize(const size_type n, const T &val = T());
00603 
00608   inline void clear();
00609 
00611 
00612 
00613 
00625   inline ERCPStrength strength() const;
00626 
00636   inline bool is_valid_ptr() const;
00637 
00643   inline int strong_count() const;
00644 
00650   inline int weak_count() const;
00651 
00653   inline int total_count() const;
00654 
00672   inline void set_has_ownership();
00673 
00685   inline bool has_ownership() const;
00686 
00707   inline T* release();
00708 
00723   inline ArrayRCP<T> create_weak() const;
00724 
00740   inline ArrayRCP<T> create_strong() const;
00741 
00748   template<class T2>
00749   inline bool shares_resource(const ArrayRCP<T2>& r_ptr) const;
00750 
00752 
00753 
00754 
00758   inline const ArrayRCP<T>& assert_not_null() const;
00759 
00765   inline const ArrayRCP<T>& assert_in_range( size_type lowerOffset, size_type size ) const;
00766 
00776   inline const ArrayRCP<T>& assert_valid_ptr() const;
00777 
00779 
00781 
00783   inline TEUCHOS_DEPRECATED int count() const;
00784 
00786 
00787 private:
00789   T *ptr_; 
00791   RCPNodeHandle node_;
00793   size_type lowerOffset_;
00795   size_type upperOffset_; 
00796 
00797   inline void debug_assert_not_null () const {
00798 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
00799     assert_not_null();
00800 #endif
00801   }
00802 
00803   inline void 
00804   debug_assert_in_range (size_type lowerOffset_in,
00805        size_type size_in) const
00806   {
00807     (void) lowerOffset_in; 
00808     (void) size_in;
00809 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00810     assert_in_range (lowerOffset_in, size_in);
00811 #endif
00812   }
00813 
00814   inline void debug_assert_valid_ptr() const {
00815 #ifdef TEUCHOS_DEBUG
00816     assert_valid_ptr ();
00817 #endif
00818   }
00819 
00820 public:
00821 
00822 #ifndef DOXYGEN_COMPILE
00823   // These constructors should be private but I have not had good luck making
00824   // this portable (i.e. using friendship etc.) in the past
00825   // This is a very bad breach of encapsulation that is needed since MS VC++
00826   // 5.0 will not allow me to declare template functions as friends.
00827   ArrayRCP( T* p, size_type lowerOffset, size_type size,
00828     const RCPNodeHandle& node );
00829   T* access_private_ptr() const;
00830   RCPNodeHandle& nonconst_access_private_node();
00831   const RCPNodeHandle& access_private_node() const;
00832 #endif
00833 
00834 };
00835 
00836 
00844 template<class T>
00845 class ArrayRCP<const T> {
00846 public:
00847   typedef Teuchos_Ordinal Ordinal;
00848   typedef Ordinal size_type;
00849   typedef Ordinal difference_type;
00850   typedef std::random_access_iterator_tag iterator_category;
00851   typedef const T* iterator_type;
00852   typedef const T  value_type;
00853   typedef const T& reference;
00854   typedef const T& const_reference;
00855   typedef const T* pointer;
00856   typedef const T* const_pointer;
00857   typedef const T  element_type;
00858 
00859 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00860   typedef ArrayRCP<const T> iterator;
00861   typedef ArrayRCP<const T> const_iterator;
00862 #else
00863   typedef const T* iterator;
00864   typedef const T* const_iterator;
00865 #endif
00866 
00867   inline ArrayRCP (ENull null_arg = null);
00868   inline ArrayRCP (const T* p, size_type lowerOffset, 
00869        size_type size, bool has_ownership,
00870        const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP);
00871   template<class Dealloc_T>
00872   inline ArrayRCP (const T* p, size_type lowerOffset, size_type size, 
00873        Dealloc_T dealloc, bool has_ownership);
00874   inline explicit ArrayRCP (size_type size, const T& val = T ());
00875   inline ArrayRCP (const ArrayRCP<const T>& r_ptr);
00876   inline ~ArrayRCP();
00877 
00878   inline ArrayRCP<const T>& operator= (const ArrayRCP<const T>& r_ptr);
00879   inline bool is_null() const;
00880   inline const T* operator->() const;
00881   inline const T& operator*() const;
00882   inline const T* get() const;
00883   inline const T* getRawPtr() const;
00884   inline const T& operator[] (size_type offset) const;
00885 
00886   inline ArrayRCP<const T>& operator++ ();
00887   inline ArrayRCP<const T> operator++ (int);
00888   inline ArrayRCP<const T>& operator-- ();
00889   inline ArrayRCP<const T> operator-- (int);
00890   inline ArrayRCP<const T>& operator+= (size_type offset);
00891   inline ArrayRCP<const T>& operator-= (size_type offset);
00892   inline ArrayRCP<const T> operator+ (size_type offset) const;
00893   inline ArrayRCP<const T> operator- (size_type offset) const;
00894 
00895   inline iterator begin() const;
00896   inline iterator end() const;
00897 
00903   inline ArrayRCP<const T> getConst () const;
00904   inline ArrayRCP<const T> persistingView (size_type lowerOffset, size_type size) const;
00905 
00906   inline size_type lowerOffset() const;
00907   inline size_type upperOffset() const;
00908   inline size_type size() const;
00909 
00910   inline ArrayView<const T> view (size_type lowerOffset, size_type size) const;
00911   inline ArrayView<const T> operator() (size_type lowerOffset, size_type size) const;
00912   inline ArrayView<const T> operator() () const;
00913 
00914   inline void resize (const size_type n, const T& val = T ());
00915   inline void clear ();
00916 
00917   inline ERCPStrength strength() const;
00918   inline bool is_valid_ptr() const;
00919   inline int strong_count() const;
00920   inline int weak_count() const;
00921   inline int total_count() const;
00922   inline void set_has_ownership();
00923   inline bool has_ownership() const;
00924   inline const T* release();
00925   inline ArrayRCP<const T> create_weak() const;
00926   inline ArrayRCP<const T> create_strong() const;
00927 
00928   template<class T2>
00929   inline bool shares_resource (const ArrayRCP<T2>& r_ptr) const;
00930 
00931   inline const ArrayRCP<const T>& assert_not_null () const;
00932   inline const ArrayRCP<const T>& assert_in_range (size_type lowerOffset, size_type size) const;
00933   inline const ArrayRCP<const T>& assert_valid_ptr() const;
00934 
00935   inline TEUCHOS_DEPRECATED int count() const;
00936 
00937 private:
00938   const T* ptr_; // NULL if this pointer is null
00939   RCPNodeHandle node_; // NULL if this pointer is null
00940   size_type lowerOffset_; // 0 if this pointer is null
00941   size_type upperOffset_; // -1 if this pointer is null
00942 
00943   inline void debug_assert_not_null() const {
00944 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
00945     assert_not_null ();
00946 #endif
00947   }
00948 
00949   inline void 
00950   debug_assert_in_range (size_type lowerOffset_in,
00951        size_type size_in) const
00952   {
00953     (void) lowerOffset_in; (void) size_in;
00954 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00955     assert_in_range (lowerOffset_in, size_in);
00956 #endif
00957   }
00958 
00959   inline void debug_assert_valid_ptr() const {
00960 #ifdef TEUCHOS_DEBUG
00961     assert_valid_ptr ();
00962 #endif
00963   }
00964 
00965 public:
00966 
00967 #ifndef DOXYGEN_COMPILE
00968   // These constructors should be private but I have not had good luck making
00969   // this portable (i.e. using friendship etc.) in the past
00970   // This is a very bad breach of encapsulation that is needed since MS VC++
00971   // 5.0 will not allow me to declare template functions as friends.
00972   ArrayRCP (const T* p, size_type lowerOffset, 
00973       size_type size, const RCPNodeHandle& node);
00974   const T* access_private_ptr() const;
00975   RCPNodeHandle& nonconst_access_private_node();
00976   const RCPNodeHandle& access_private_node() const;
00977 #endif
00978 };
00979 
00980 
00989 template<>
00990 class ArrayRCP<void> {
00991 public:
00992   typedef Teuchos_Ordinal Ordinal;
00993   typedef Ordinal size_type;
00994   typedef Ordinal difference_type;
00995   typedef std::random_access_iterator_tag iterator_category;
00996   typedef  void* iterator_type;
00997   typedef  void value_type;
00999   // typedef T& reference;              // these are not valid
01001   // typedef const T& const_reference;  // these are not valid
01002   typedef void* pointer;
01003   typedef void* const_pointer;
01004   typedef void  element_type;
01005 
01007   inline ArrayRCP ();
01008 };
01009 
01014 template<>
01015 class ArrayRCP<const void> {
01016 public:
01017   typedef Teuchos_Ordinal Ordinal;
01018   typedef Ordinal size_type;
01019   typedef Ordinal difference_type;
01020   typedef std::random_access_iterator_tag iterator_category;
01021   typedef  const void* iterator_type;
01022   typedef  const void value_type;
01024   // typedef T& reference;              // these are not valid
01026   // typedef const T& const_reference;  // these are not valid
01027   typedef const void* pointer;
01028   typedef const void* const_pointer;
01029   typedef const void  element_type;
01030 
01032   inline ArrayRCP ();
01033 };
01034 
01035 // 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<ArrayRCP<T> >
01036 // specialization since I want to be able to print the type name of an
01037 // ArrayRCP that does not have the type T fully defined!
01038 
01039 
01044 template<typename T>
01045 class NullIteratorTraits<ArrayRCP<T> > {
01046 public:
01047   static ArrayRCP<T> getNull() { return null; }
01048 };
01049 
01050 
01056 template<class T>
01057 ArrayRCP<T> arcp(
01058   T* p,
01059   typename ArrayRCP<T>::size_type lowerOffset,
01060   typename ArrayRCP<T>::size_type size,
01061   bool owns_mem = true
01062   );
01063 
01064 
01070 template<class T, class Dealloc_T>
01071 ArrayRCP<T> arcp(
01072   T* p,
01073   typename ArrayRCP<T>::size_type lowerOffset,
01074   typename ArrayRCP<T>::size_type size,
01075   Dealloc_T dealloc, bool owns_mem
01076   );
01077 
01078 
01089 template<class T>
01090 ArrayRCP<T> arcp( typename ArrayRCP<T>::size_type size );
01091 
01092 
01106 template<class T>
01107 ArrayRCP<T> arcpCloneNode( const ArrayRCP<T> &a );
01108 
01109 
01114 template<class T>
01115 ArrayRCP<T> arcpClone( const ArrayView<const T> &v );
01116 
01117 
01128 template<class T, class Embedded>
01129 ArrayRCP<T>
01130 arcpWithEmbeddedObjPreDestroy(
01131   T* p,
01132   typename ArrayRCP<T>::size_type lowerOffset,
01133   typename ArrayRCP<T>::size_type size,
01134   const Embedded &embedded,
01135   bool owns_mem = true
01136   );
01137 
01138 
01149 template<class T, class Embedded>
01150 ArrayRCP<T>
01151 arcpWithEmbeddedObjPostDestroy(
01152   T* p,
01153   typename ArrayRCP<T>::size_type lowerOffset,
01154   typename ArrayRCP<T>::size_type size,
01155   const Embedded &embedded,
01156   bool owns_mem = true
01157   );
01158 
01159 
01171 template<class T, class Embedded>
01172 ArrayRCP<T>
01173 arcpWithEmbeddedObj(
01174   T* p,
01175   typename ArrayRCP<T>::size_type lowerOffset,
01176   typename ArrayRCP<T>::size_type size,
01177   const Embedded &embedded,
01178   bool owns_mem = true
01179   );
01180 
01181 
01187 template<class T>
01188 ArrayRCP<T> arcp( const RCP<std::vector<T> > &v );
01189 
01190 
01196 template<class T>
01197 ArrayRCP<const T> arcp( const RCP<const std::vector<T> > &v );
01198 
01199 
01208 template<class T>
01209 ArrayRCP<T> arcpFromArrayView(const ArrayView<T> &av);
01210 
01211 
01218 template<class T>
01219 RCP<std::vector<T> > get_std_vector( const ArrayRCP<T> &ptr );
01220 
01221 
01228 template<class T>
01229 RCP<const std::vector<T> > get_std_vector( const ArrayRCP<const T> &ptr );
01230 
01231 
01236 template<class T>
01237 bool is_null( const ArrayRCP<T> &p );
01238 
01239 
01244 template<class T>
01245 bool nonnull( const ArrayRCP<T> &p );
01246 
01247 
01252 template<class T>
01253 bool operator==( const ArrayRCP<T> &p, ENull );
01254 
01255 
01260 template<class T>
01261 bool operator!=( const ArrayRCP<T> &p, ENull );
01262 
01263 
01268 template<class T1, class T2>
01269 bool operator==( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01270 
01271 
01276 template<class T1, class T2>
01277 bool operator!=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01278 
01279 
01284 template<class T1, class T2>
01285 bool operator<( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01286 
01287 
01292 template<class T1, class T2>
01293 bool operator<=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01294 
01295 
01300 template<class T1, class T2>
01301 bool operator>( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01302 
01303 
01308 template<class T1, class T2>
01309 bool operator>=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01310 
01311 
01316 template<class T>
01317 typename ArrayRCP<T>::difference_type
01318 operator-( const ArrayRCP<T> &p1, const ArrayRCP<T> &p2 );
01319 
01320 
01331 template<class T2, class T1>
01332 inline
01333 ArrayRCP<T2> arcp_const_cast(const ArrayRCP<T1>& p1);
01334 
01335 
01347 template<class T2, class T1>
01348 ArrayRCP<T2> arcp_reinterpret_cast(const ArrayRCP<T1>& p1);
01349 
01350 
01367 template<class T2, class T1>
01368 ArrayRCP<T2> arcp_reinterpret_cast_nonpod(const ArrayRCP<T1>& p1, const T2& val=T2());
01369 
01370 
01396 template<class T2, class T1>
01397 inline
01398 ArrayRCP<T2> arcp_implicit_cast(const ArrayRCP<T1>& p1);
01399 
01400 
01459 template<class T1, class T2>
01460 void set_extra_data(
01461   const T1 &extra_data, const std::string& name,
01462   const Ptr<ArrayRCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
01463   bool force_unique = true );
01464 
01465 
01485 template<class T1, class T2>
01486 T1& get_extra_data( ArrayRCP<T2>& p, const std::string& name );
01487 
01488 
01514 template<class T1, class T2>
01515 const T1& get_extra_data( const ArrayRCP<T2>& p, const std::string& name );
01516 
01517 
01542 template<class T1, class T2>
01543 T1* get_optional_extra_data( ArrayRCP<T2>& p, const std::string& name );
01544 
01545 
01575 template<class T1, class T2>
01576 const T1* get_optional_extra_data( const ArrayRCP<T2>& p, const std::string& name );
01577 
01578 
01589 template<class Dealloc_T, class T>
01590 Dealloc_T& get_nonconst_dealloc( const ArrayRCP<T>& p );
01591 
01592 
01610 template<class Dealloc_T, class T>
01611 const Dealloc_T& get_dealloc( const ArrayRCP<T>& p );
01612 
01613 
01628 template<class Dealloc_T, class T>
01629 const Dealloc_T* get_optional_dealloc( const ArrayRCP<T>& p );
01630 
01631 
01653 template<class Dealloc_T, class T>
01654 Dealloc_T* get_optional_nonconst_dealloc( const ArrayRCP<T>& p );
01655 
01656 
01663 template<class TOrig, class Embedded, class T>
01664 const Embedded& getEmbeddedObj( const ArrayRCP<T>& p );
01665 
01666 
01673 template<class TOrig, class Embedded, class T>
01674 Embedded& getNonconstEmbeddedObj( const ArrayRCP<T>& p );
01675 
01676 
01684 template<class T>
01685 std::ostream& operator<<( std::ostream& out, const ArrayRCP<T>& p );
01686 
01687 
01688 } // end namespace Teuchos
01689 
01690 
01691 #endif  // TEUCHOS_ARRAY_RCP_DECL_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines