Teuchos - Trilinos Tools Package Version of the Day
Teuchos_ArrayRCPDecl.hpp
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 
00103 template<class T>
00104 class ArrayRCP {
00105 public:
00106 
00108 
00109 
00111   typedef Teuchos_Ordinal Ordinal;
00112 
00114   typedef Ordinal size_type;
00115 
00117   typedef Ordinal difference_type;
00118 
00120   typedef std::random_access_iterator_tag iterator_category;
00121 
00123   typedef  T* iterator_type;
00124 
00126   typedef  T value_type;
00127 
00129   typedef T& reference; 
00130 
00132   typedef const T& const_reference; 
00133 
00135   typedef T* pointer;
00136 
00138   typedef T* const_pointer;
00139 
00141   typedef T  element_type;
00142 
00143 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00144 
00145   typedef ArrayRCP<T> iterator;
00147   typedef ArrayRCP<const T> const_iterator;
00148 #else
00149 
00150   typedef T* iterator;
00152   typedef const T* const_iterator;
00153 #endif
00154 
00156 
00158 
00159 
00172   inline ArrayRCP( ENull null_arg = null );
00173 
00195   inline ArrayRCP( T* p, size_type lowerOffset, size_type size,
00196     bool has_ownership, const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP );
00197 
00220   template<class Dealloc_T>
00221   inline ArrayRCP( T* p, size_type lowerOffset, size_type size, Dealloc_T dealloc,
00222     bool has_ownership );
00223 
00239   inline explicit ArrayRCP( size_type size, const T& val = T() );
00240 
00259   inline ArrayRCP(const ArrayRCP<T>& r_ptr);
00260 
00271   inline ~ArrayRCP();
00272 
00300   inline ArrayRCP<T>& operator=(const ArrayRCP<T>& r_ptr);
00301 
00303 
00305 
00306 
00308   inline bool is_null() const;
00309 
00317   inline T* operator->() const;
00318 
00326   inline T& operator*() const;
00327 
00333   inline T* get() const;
00334 
00340   inline T* getRawPtr() const;
00341 
00347   inline T& operator[](size_type offset) const;
00348 
00350 
00352 
00353 
00362   inline ArrayRCP<T>& operator++();
00363 
00372   inline ArrayRCP<T> operator++(int);
00373 
00382   inline ArrayRCP<T>& operator--();
00383 
00392   inline ArrayRCP<T> operator--(int);
00393 
00402   inline ArrayRCP<T>& operator+=(size_type offset);
00403 
00412   inline ArrayRCP<T>& operator-=(size_type offset);
00413 
00426   inline ArrayRCP<T> operator+(size_type offset) const;
00427 
00440   inline ArrayRCP<T> operator-(size_type offset) const;
00441 
00443 
00445 
00446 
00457   inline iterator begin() const;
00458 
00469   inline iterator end() const;
00470 
00472 
00474 
00475 
00481   inline ArrayRCP<const T> getConst() const;
00482 
00496   inline ArrayRCP<T> persistingView( size_type lowerOffset, size_type size ) const;
00497 
00499 
00501 
00502 
00504   inline size_type lowerOffset() const;
00505 
00507   inline size_type upperOffset() const;
00508 
00512   inline size_type size() const;
00513 
00515 
00517 
00518 
00532   inline ArrayView<T> view( size_type lowerOffset, size_type size ) const;
00533 
00538   inline ArrayView<T> operator()( size_type lowerOffset, size_type size ) const;
00539 
00544   inline ArrayView<T> operator()() const;
00545 
00547 
00548 
00549 
00551   inline operator ArrayRCP<const T>() const;
00552 
00554 
00556 
00557 
00562   inline void assign(size_type n, const T &val);
00563 
00571   template<class Iter>
00572   inline void assign(Iter first, Iter last);
00573 
00579   inline void deepCopy(const ArrayView<const T>& av);
00580 
00582   inline void resize(const size_type n, const T &val = T());
00583 
00588   inline void clear();
00589 
00591 
00592 
00593 
00605   inline ERCPStrength strength() const;
00606 
00616   inline bool is_valid_ptr() const;
00617 
00623   inline int strong_count() const;
00624 
00630   inline int weak_count() const;
00631 
00633   inline int total_count() const;
00634 
00652   inline void set_has_ownership();
00653 
00665   inline bool has_ownership() const;
00666 
00687   inline T* release();
00688 
00703   inline ArrayRCP<T> create_weak() const;
00704 
00720   inline ArrayRCP<T> create_strong() const;
00721 
00728   template<class T2>
00729   inline bool shares_resource(const ArrayRCP<T2>& r_ptr) const;
00730 
00732 
00733 
00734 
00738   inline const ArrayRCP<T>& assert_not_null() const;
00739 
00745   inline const ArrayRCP<T>& assert_in_range( size_type lowerOffset, size_type size ) const;
00746 
00756   inline const ArrayRCP<T>& assert_valid_ptr() const;
00757 
00759 
00760 
00763 
00765   inline TEUCHOS_DEPRECATED int count() const;
00766 
00768 
00769 private:
00770 
00771   // //////////////////////////////////////////////////////////////
00772   // Private data members
00773 
00774   T *ptr_; // NULL if this pointer is null
00775   RCPNodeHandle node_; // NULL if this pointer is null
00776   size_type lowerOffset_; // 0 if this pointer is null
00777   size_type upperOffset_; // -1 if this pointer is null
00778 
00779   inline void debug_assert_not_null() const
00780     {
00781 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
00782       assert_not_null();
00783 #endif
00784     }
00785 
00786   inline void debug_assert_in_range( size_type lowerOffset_in,
00787     size_type size_in ) const
00788     {
00789       (void)lowerOffset_in; (void)size_in;
00790 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
00791       assert_in_range(lowerOffset_in, size_in);
00792 #endif
00793     }
00794 
00795   inline void debug_assert_valid_ptr() const
00796     {
00797 #ifdef TEUCHOS_DEBUG
00798       assert_valid_ptr();
00799 #endif
00800     }
00801 
00802 public:
00803 
00804 
00805 #ifndef DOXYGEN_COMPILE
00806   // These constructors should be private but I have not had good luck making
00807   // this portable (i.e. using friendship etc.) in the past
00808   // This is a very bad breach of encapsulation that is needed since MS VC++
00809   // 5.0 will not allow me to declare template functions as friends.
00810   ArrayRCP( T* p, size_type lowerOffset, size_type size,
00811     const RCPNodeHandle& node );
00812   T* access_private_ptr() const;
00813   RCPNodeHandle& nonconst_access_private_node();
00814   const RCPNodeHandle& access_private_node() const;
00815 #endif
00816 
00817 };  // end class ArrayRCP<...>
00818 
00819 
00829 template<>
00830 class ArrayRCP<void> {
00831 public:
00832 
00834 
00835 
00837   typedef Teuchos_Ordinal Ordinal;
00838 
00840   typedef Ordinal size_type;
00842   typedef Ordinal difference_type;
00844   typedef std::random_access_iterator_tag iterator_category;
00846   typedef  void* iterator_type;
00848   typedef  void value_type;
00850   // typedef T& reference;              // these are not valid
00852   // typedef const T& const_reference;  // these are not valid
00854   typedef void* pointer;
00856   typedef void* const_pointer;
00858   typedef void  element_type;
00859 
00862   inline ArrayRCP( );
00863 
00865 
00866 };  // end class ArrayRCP<void>
00867 
00872 template<>
00873 class ArrayRCP<const void> {
00874 public:
00875 
00877 
00878 
00880   typedef Teuchos_Ordinal Ordinal;
00881 
00883   typedef Ordinal size_type;
00885   typedef Ordinal difference_type;
00887   typedef std::random_access_iterator_tag iterator_category;
00889   typedef  const void* iterator_type;
00891   typedef  const void value_type;
00893   // typedef T& reference;              // these are not valid
00895   // typedef const T& const_reference;  // these are not valid
00897   typedef const void* pointer;
00899   typedef const void* const_pointer;
00901   typedef const void  element_type;
00902 
00905   inline ArrayRCP( );
00906 
00908 
00909 };  // end class ArrayRCP<void>
00910 
00911 // 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<ArrayRCP<T> >
00912 // specialization since I want to be able to print the type name of an
00913 // ArrayRCP that does not have the type T fully defined!
00914 
00915 
00920 template<typename T>
00921 class NullIteratorTraits<ArrayRCP<T> > {
00922 public:
00923   static ArrayRCP<T> getNull() { return null; }
00924 };
00925 
00926 
00932 template<class T>
00933 ArrayRCP<T> arcp(
00934   T* p,
00935   typename ArrayRCP<T>::size_type lowerOffset,
00936   typename ArrayRCP<T>::size_type size,
00937   bool owns_mem = true
00938   );
00939 
00940 
00946 template<class T, class Dealloc_T>
00947 ArrayRCP<T> arcp(
00948   T* p,
00949   typename ArrayRCP<T>::size_type lowerOffset,
00950   typename ArrayRCP<T>::size_type size,
00951   Dealloc_T dealloc, bool owns_mem
00952   );
00953 
00954  
00965 template<class T>
00966 ArrayRCP<T> arcp( typename ArrayRCP<T>::size_type size );
00967 
00968  
00982 template<class T>
00983 ArrayRCP<T> arcpCloneNode( const ArrayRCP<T> &a );
00984 
00985  
00990 template<class T>
00991 ArrayRCP<T> arcpClone( const ArrayView<const T> &v );
00992 
00993 
01004 template<class T, class Embedded>
01005 ArrayRCP<T>
01006 arcpWithEmbeddedObjPreDestroy(
01007   T* p,
01008   typename ArrayRCP<T>::size_type lowerOffset,
01009   typename ArrayRCP<T>::size_type size,
01010   const Embedded &embedded,
01011   bool owns_mem = true
01012   );
01013 
01014 
01025 template<class T, class Embedded>
01026 ArrayRCP<T>
01027 arcpWithEmbeddedObjPostDestroy(
01028   T* p,
01029   typename ArrayRCP<T>::size_type lowerOffset,
01030   typename ArrayRCP<T>::size_type size,
01031   const Embedded &embedded,
01032   bool owns_mem = true
01033   );
01034 
01035 
01047 template<class T, class Embedded>
01048 ArrayRCP<T>
01049 arcpWithEmbeddedObj(
01050   T* p,
01051   typename ArrayRCP<T>::size_type lowerOffset,
01052   typename ArrayRCP<T>::size_type size,
01053   const Embedded &embedded,
01054   bool owns_mem = true
01055   );
01056 
01057 
01063 template<class T>
01064 ArrayRCP<T> arcp( const RCP<std::vector<T> > &v );
01065 
01066 
01072 template<class T>
01073 ArrayRCP<const T> arcp( const RCP<const std::vector<T> > &v );
01074 
01075 
01084 template<class T>
01085 ArrayRCP<T> arcpFromArrayView(const ArrayView<T> &av);
01086 
01087 
01094 template<class T>
01095 RCP<std::vector<T> > get_std_vector( const ArrayRCP<T> &ptr );
01096 
01097 
01104 template<class T>
01105 RCP<const std::vector<T> > get_std_vector( const ArrayRCP<const T> &ptr );
01106 
01107 
01112 template<class T>
01113 bool is_null( const ArrayRCP<T> &p );
01114 
01115 
01120 template<class T>
01121 bool nonnull( const ArrayRCP<T> &p );
01122 
01123 
01128 template<class T>
01129 bool operator==( const ArrayRCP<T> &p, ENull );
01130 
01131 
01136 template<class T>
01137 bool operator!=( const ArrayRCP<T> &p, ENull );
01138 
01139 
01144 template<class T1, class T2>
01145 bool operator==( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01146 
01147 
01152 template<class T1, class T2>
01153 bool operator!=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01154 
01155 
01160 template<class T1, class T2>
01161 bool operator<( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01162 
01163 
01168 template<class T1, class T2>
01169 bool operator<=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01170 
01171 
01176 template<class T1, class T2>
01177 bool operator>( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01178 
01179 
01184 template<class T1, class T2>
01185 bool operator>=( const ArrayRCP<T1> &p1, const ArrayRCP<T2> &p2 );
01186 
01187 
01192 template<class T>
01193 typename ArrayRCP<T>::difference_type
01194 operator-( const ArrayRCP<T> &p1, const ArrayRCP<T> &p2 );
01195 
01196 
01205 template<class T2, class T1>
01206 inline
01207 ArrayRCP<T2> arcp_const_cast(const ArrayRCP<T1>& p1);
01208 
01209 
01222 template<class T2, class T1>
01223 ArrayRCP<T2> arcp_reinterpret_cast(const ArrayRCP<T1>& p1);
01224 
01225 
01244 template<class T2, class T1>
01245 ArrayRCP<T2> arcp_reinterpret_cast_nonpod(const ArrayRCP<T1>& p1, const T2& val=T2());
01246 
01247 
01273 template<class T2, class T1>
01274 inline
01275 ArrayRCP<T2> arcp_implicit_cast(const ArrayRCP<T1>& p1);
01276 
01277 
01336 template<class T1, class T2>
01337 void set_extra_data(
01338   const T1 &extra_data, const std::string& name,
01339   const Ptr<ArrayRCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
01340   bool force_unique = true );
01341 
01342 
01362 template<class T1, class T2>
01363 T1& get_extra_data( ArrayRCP<T2>& p, const std::string& name );
01364 
01365 
01391 template<class T1, class T2>
01392 const T1& get_extra_data( const ArrayRCP<T2>& p, const std::string& name );
01393 
01394 
01419 template<class T1, class T2>
01420 T1* get_optional_extra_data( ArrayRCP<T2>& p, const std::string& name );
01421 
01422 
01452 template<class T1, class T2>
01453 const T1* get_optional_extra_data( const ArrayRCP<T2>& p, const std::string& name );
01454 
01455 
01466 template<class Dealloc_T, class T>
01467 Dealloc_T& get_nonconst_dealloc( const ArrayRCP<T>& p );
01468 
01469 
01487 template<class Dealloc_T, class T>
01488 const Dealloc_T& get_dealloc( const ArrayRCP<T>& p );
01489 
01490 
01505 template<class Dealloc_T, class T>
01506 const Dealloc_T* get_optional_dealloc( const ArrayRCP<T>& p );
01507 
01508 
01530 template<class Dealloc_T, class T>
01531 Dealloc_T* get_optional_nonconst_dealloc( const ArrayRCP<T>& p );
01532 
01533 
01540 template<class TOrig, class Embedded, class T>
01541 const Embedded& getEmbeddedObj( const ArrayRCP<T>& p );
01542 
01543 
01550 template<class TOrig, class Embedded, class T>
01551 Embedded& getNonconstEmbeddedObj( const ArrayRCP<T>& p );
01552 
01553 
01561 template<class T>
01562 std::ostream& operator<<( std::ostream& out, const ArrayRCP<T>& p );
01563 
01564 
01565 } // end namespace Teuchos
01566 
01567 
01568 #endif  // TEUCHOS_ARRAY_RCP_DECL_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines