Teuchos - Trilinos Tools Package  Version of the Day
Teuchos_ArrayViewDecl.hpp
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #ifndef TEUCHOS_ARRAY_VIEW_DECL_HPP
43 #define TEUCHOS_ARRAY_VIEW_DECL_HPP
44 
45 
46 #include "Teuchos_RCPNode.hpp"
47 #include "Teuchos_ENull.hpp"
48 #include "Teuchos_NullIteratorTraits.hpp"
49 #include "Teuchos_ConstTypeTraits.hpp"
50 
51 
52 namespace Teuchos {
53 
54 // Forward declaration; ArrayView uses ArrayRCP in debug mode.
55 template<class T> class ArrayRCP;
56 
122 template<class T>
123 class ArrayView {
124 public:
126 
127 
129  typedef Teuchos_Ordinal Ordinal;
130 
132  typedef Ordinal size_type;
133 
135  typedef Ordinal difference_type;
136 
138  typedef T value_type;
139 
143  typedef T* pointer;
144 
146  typedef const T* const_pointer;
147 
151  typedef T& reference;
152 
154  typedef const T& const_reference;
155 
156 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
157  typedef ArrayRCP<T> iterator;
161 #else
162  typedef pointer iterator;
165  typedef const_pointer const_iterator;
166 #endif
167 
169 
171 
173  ArrayView( ENull null_arg = null );
174 
190  ArrayView (T* p, size_type size,
191  const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP);
192 
203  ArrayView (const ArrayView<T>& array);
204 
206  ArrayView (std::vector<typename ConstTypeTraits<T>::NonConstType>& vec);
207 
209  ArrayView (const std::vector<typename ConstTypeTraits<T>::NonConstType>& vec);
210 
212  ArrayView<T>& operator= (const ArrayView<T>& array);
213 
215  ~ArrayView();
216 
218 
220 
222  bool is_null() const;
223 
225  size_type size() const;
226 
228  std::string toString() const;
229 
231 
233 
235  inline T* getRawPtr() const;
236 
244  T& operator[](size_type i) const;
245 
247  T& front() const;
248 
250  T& back() const;
251 
253 
255 
270  ArrayView<T> view( size_type offset, size_type size ) const;
271 
275  ArrayView<T> operator()( size_type offset, size_type size ) const;
276 
278  const ArrayView<T>& operator() () const;
279 
282 
290  operator ArrayView<const T>() const;
291 
293 
295 
314  void assign (const ArrayView<const T>& array) const;
315 
317 
319 
332  iterator begin() const;
333 
346  iterator end() const;
347 
349 
351 
355  const ArrayView<T>& assert_not_null() const;
356 
361  const ArrayView<T>& assert_in_range( size_type offset, size_type size ) const;
362 
364 
365 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
366 
367  // I should make these private but templated friends are not very portable.
368  // Besides, if a client directly calls this it will not compile in an
369  // optimized build.
370 
371  explicit ArrayView( const ArrayRCP<T> &arcp );
372 
373  explicit ArrayView( T* p, size_type size, const ArrayRCP<T> &arcp );
374 
375 #endif
376 
377 private:
378  T *ptr_; //<! Pointer to the data
379  int size_; //<! Number of entries in the view
380 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
381  ArrayRCP<T> arcp_;
382 #endif
383 
384  void setUpIterators(const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP);
385 
386  void debug_assert_not_null() const {
387 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
388  assert_not_null();
389 #endif
390  }
391 
392  void debug_assert_in_range( size_type offset, size_type size_in ) const {
393  (void)offset; (void)size_in;
394 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
395  assert_in_range(offset, size_in);
396 #endif
397  }
398 
399  void debug_assert_valid_ptr() const {
400 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
401  arcp_.access_private_node().assert_valid_ptr(*this);
402 #endif
403  }
404 
405 public: // Bad bad bad
406 
407  // This is a very bad breach of encapsulation but it exists to avoid
408  // problems with portability of tempalted friends
409  T* access_private_ptr() const
410  { return ptr_; }
411 
412 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
413  ArrayRCP<T> access_private_arcp() const
414  { return arcp_; }
415 #endif
416 
417 };
418 
419 
427 template<class T>
428 class ArrayView<const T> {
429 public:
430  typedef Teuchos_Ordinal Ordinal;
431  typedef Ordinal size_type;
432  typedef Ordinal difference_type;
433  typedef const T value_type;
434  typedef const T* pointer;
435  typedef const T* const_pointer;
436  typedef const T& reference;
437  typedef const T& const_reference;
438 
439 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
440  typedef ArrayRCP<const T> iterator;
442 #else
443  typedef pointer iterator;
444  typedef const_pointer const_iterator;
445 #endif
446 
447  ArrayView( ENull null_arg = null );
448 
449  ArrayView (const T* p, size_type size,
450  const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP );
451 
452  ArrayView (const ArrayView<const T>& array);
453 
454  ArrayView (std::vector<typename ConstTypeTraits<T>::NonConstType>& vec);
455 
456  ArrayView (const std::vector<typename ConstTypeTraits<T>::NonConstType>& vec);
457 
459 
460  ~ArrayView();
461 
462  bool is_null() const;
463 
464  size_type size() const;
465 
466  std::string toString() const;
467 
468  inline const T* getRawPtr() const;
469 
470  const T& operator[] (size_type i) const;
471 
472  const T& front() const;
473 
474  const T& back() const;
475 
476  ArrayView<const T> view( size_type offset, size_type size ) const;
477 
478  ArrayView<const T> operator()( size_type offset, size_type size ) const;
479 
480  const ArrayView<const T>& operator()() const;
481 
488 
489  iterator begin() const;
490 
491  iterator end() const;
492 
493  const ArrayView<const T>& assert_not_null() const;
494 
495  const ArrayView<const T>& assert_in_range( size_type offset, size_type size ) const;
496 
497 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
498 
499  // I should make these private but templated friends are not very
500  // portable. Besides, if a client directly calls this it will not
501  // compile in an optimized build.
502 
503  explicit ArrayView (const ArrayRCP<const T> &arcp );
504 
505  explicit ArrayView (const T* p, size_type size, const ArrayRCP<const T> &arcp );
506 
507 #endif
508 
509 private:
510  const T* ptr_;
511  int size_;
512 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
513  ArrayRCP<const T> arcp_;
514 #endif
515 
516  void setUpIterators(const ERCPNodeLookup rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP);
517 
518  void debug_assert_not_null() const {
519 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
520  assert_not_null();
521 #endif
522  }
523 
524  void debug_assert_in_range( size_type offset, size_type size_in ) const {
525  (void)offset; (void)size_in;
526 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
527  assert_in_range(offset, size_in);
528 #endif
529  }
530 
531  void debug_assert_valid_ptr() const {
532 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
533  arcp_.access_private_node().assert_valid_ptr(*this);
534 #endif
535  }
536 
537 public: // Bad bad bad
538 
539  // This is a very bad breach of encapsulation but it exists to avoid
540  // problems with portability of templated friends
541  const T* access_private_ptr() const { return ptr_; }
542 
543 #ifdef HAVE_TEUCHOS_ARRAY_BOUNDSCHECK
544  ArrayRCP<const T> access_private_arcp() const { return arcp_; }
545 #endif
546 };
547 
548 
549 
554 template<class T>
556 
557 
562 template<class T>
563 ArrayView<T> arrayViewFromVector( std::vector<T>& vec );
564 
565 
570 template<class T>
571 ArrayView<const T> arrayViewFromVector( const std::vector<T>& vec );
572 
573 
574 #ifndef __sun
575 
576 
577 // 2007/11/30: From some reason, the Sun C++ compile on sass9000 compains that
578 // a call to this function below is ambiguous. However, if you just comment
579 // the function out, then the code on g++ (3.4.6 at least) will not compile.
580 // Therefore, I have no choice but to put in a hacked ifdef for the sun.
581 
582 
590 template<class T>
591 std::vector<T> createVector( const ArrayView<T> &av );
592 
593 
594 #endif // __sun
595 
596 
604 template<class T>
605 std::vector<T> createVector( const ArrayView<const T> &av );
606 
607 
612 template<class T>
613 bool is_null( const ArrayView<T> &av );
614 
615 
620 template<class T>
621 bool nonnull( const ArrayView<T> &av );
622 
623 
631 template<class T>
632 std::ostream& operator<<( std::ostream& out, const ArrayView<T>& av );
633 
634 
643 template<class T2, class T1>
645 
646 
659 template<class T2, class T1>
661 
662 
663 } // end namespace Teuchos
664 
665 
666 //
667 // Inline members
668 //
669 
670 
671 // ToDo: Fill in!
672 
673 
674 #endif // TEUCHOS_ARRAY_VIEW_DECL_HPP
T & reference
Type of a reference to an array element.
ArrayView< T > arrayView(T *p, typename ArrayView< T >::size_type size)
Construct a const or non-const view to const or non-const data.
std::string toString() const
Convert an ArrayView<T> to an std::string
T & front() const
Get the first element.
const T * const_pointer
Type of a const pointer to an array element.
pointer iterator
Type of a nonconst iterator.
bool is_null() const
Returns true if the underlying pointer is null.
const ArrayView< T > & assert_in_range(size_type offset, size_type size) const
Throws NullReferenceError if this->get()==NULL orthis->get()!=NULL, throws RangeError if (offset < 0 ...
Partial specialization of ArrayRCP for const T.
std::vector< T > createVector(const ArrayView< T > &av)
Get a new std::vector<T> object out of an ArrayView<T> object.
const T & const_reference
Type of a const reference to an array element.
iterator begin() const
Return an iterator to beginning of the array of data.
const_pointer const_iterator
Type of a const iterator.
Ordinal size_type
Type representing the number of elements in an ArrayRCP or view thereof.
size_type size() const
The total number of items in the managed array.
ArrayView< T > arrayViewFromVector(std::vector< T > &vec)
Construct a non-const view of an std::vector.
bool nonnull(const ArrayView< T > &av)
Returns true if av.get()!=NULL.
ArrayView< T2 > av_reinterpret_cast(const ArrayView< T1 > &p1)
Reinterpret cast of underlying ArrayView type from T1* to T2*.
ArrayView< T2 > av_const_cast(const ArrayView< T1 > &p1)
Const cast of underlying ArrayView type from const T* to T*.
void assign(const ArrayView< const T > &array) const
Copy the data from one array view object to this array view object.
Teuchos_Ordinal Ordinal
Integer index type used throughout ArrayView.
T * pointer
Type of a pointer to an array element.
T * getRawPtr() const
Return a raw pointer to beginning of array or NULL if unsized.
const ArrayView< T > & assert_not_null() const
Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this.
T value_type
Type of each array element.
const ArrayView< T > & operator()() const
Return *this (just for compatibility with Array and ArrayPtr).
Nonowning array view.
The Teuchos namespace contains all of the classes, structs and enums used by Teuchos, as well as a number of utility routines.
ERCPNodeLookup
Used to determine if RCPNode lookup is performed or not.
ArrayView(ENull null_arg=null)
Constructor that initializes to NULL (implicitly or explicitly).
iterator end() const
Return an iterator to past the end of the array of data.
ArrayView< T > view(size_type offset, size_type size) const
Return a view of a contiguous range of elements.
Partial specialization of ArrayView for const T.
T & operator[](size_type i) const
Random object access.
Reference-counted pointer node classes.
Ordinal difference_type
Type representing the difference between two size_type values.
ArrayView< T > & operator=(const ArrayView< T > &array)
Shallow copy assignment operator.
const ArrayRCP< T > & assert_valid_ptr() const
If the object pointer is non-null, assert that it is still valid.
ArrayView< const T > getConst() const
Return a const view of a possibly nonconst view.
T & back() const
Get the last element.
Reference-counted smart pointer for managing arrays.