iterator.hpp

In debug-build (when SCTL_MEMDEBUG is defined), this header file provides the ConstIterator and Iterator classes, which offer iterator functionalities with additional memory debugging capabilities. In a regular build, these types are aliases for regular pointers.

Classes and Types

template<class ValueType> class ConstIterator

A constant iterator with additional functionalities for memory debugging. It is enabled by defining the macro SCTL_MEMDEBUG, otherwise it is an alias for a raw pointer.

Template Parameters:: ValueType – The type of elements pointed to by the iterator.

Subclassed by sctl::Iterator< sctl::FFT< Real > >, sctl::Iterator< T >, sctl::Iterator< ValueType >

Methods:

ConstIterator(): Default constructor.

ConstIterator(const ConstIterator&): Copy constructor.

ConstIterator& operator=(const ConstIterator&): Copy assignment operator.

explicit ConstIterator(pointer base_, difference_type len_, bool dynamic_alloc = false): Constructor with base pointer and length.

template <class AnotherType> explicit ConstIterator(const ConstIterator<AnotherType>& I): Template copy constructor.

reference operator*() const: Dereference operator.

pointer operator->() const: Member access operator.

reference operator[](difference_type off) const: Subscript operator.

ConstIterator& operator++(): Pre-increment operator.

ConstIterator operator++(int): Post-increment operator.

ConstIterator& operator--(): Pre-decrement operator.

ConstIterator operator--(int): Post-decrement operator.

ConstIterator& operator+=(difference_type i): Addition assignment operator.

ConstIterator operator+(difference_type i) const: Addition operator.

template <class T> friend ConstIterator<T> operator+(typename ConstIterator<T>::difference_type i, const ConstIterator<T>& right): Addition operator for constant iterator.

ConstIterator& operator-=(difference_type i): Subtraction assignment operator.

ConstIterator operator-(difference_type i) const: Subtraction operator.

difference_type operator-(const ConstIterator& I) const: Difference operator.

bool operator==(const ConstIterator& I) const: Equality comparison operator.

bool operator!=(const ConstIterator& I) const: Inequality comparison operator.

bool operator<(const ConstIterator& I) const: Less-than comparison operator.

bool operator<=(const ConstIterator& I) const: Less-than-or-equal comparison operator.

bool operator>(const ConstIterator& I) const: Greater-than comparison operator.

bool operator>=(const ConstIterator& I) const: Greater-than-or-equal comparison operator.

friend std::ostream& operator<<(std::ostream& out, const ConstIterator& I): Output stream operator.

template<class ValueType> class Iterator : public sctl::ConstIterator<ValueType>

An iterator with additional functionalities for memory debugging.

Template Parameters:: ValueType – The type of elements pointed to by the iterator.

Methods:

Iterator(): Default constructor.

Iterator(const Iterator&): Copy constructor.

Iterator& operator=(const Iterator&): Copy assignment operator.

explicit Iterator(pointer base_, difference_type len_, bool dynamic_alloc = false): Constructor with base pointer and length.

template <class AnotherType> explicit Iterator(const ConstIterator<AnotherType>& I): Template copy constructor.

reference operator*() const: Dereference operator.

pointer operator->() const: Member access operator.

reference operator[](difference_type off) const: Subscript operator.

Iterator& operator++(): Pre-increment operator.

Iterator operator++(int): Post-increment operator.

Iterator& operator--(): Pre-decrement operator.

Iterator operator--(int): Post-decrement operator.

Iterator& operator+=(difference_type i): Addition assignment operator.

Iterator operator+(difference_type i) const: Addition operator.

template <class T> friend Iterator<T> operator+(typename Iterator<T>::difference_type i, const Iterator<T>& right): Addition operator for iterator.

Iterator& operator-=(difference_type i): Subtraction assignment operator.

Iterator operator-(difference_type i) const: Subtraction operator.

difference_type operator-(const ConstIterator<ValueType>& I) const: Difference operator.

Functions

template<class ValueType> Iterator<ValueType> sctl::NullIterator()

Returns a null iterator.

Template Parameters:: ValueType – The type of elements pointed to by the iterator.
Returns:: An iterator pointing to null.

template<class ValueType> Iterator<ValueType> sctl::Ptr2Itr(void *ptr, Long len)

Converts a pointer to an iterator.

Template Parameters:

ValueType – The type of elements pointed to by the iterator.

Parameters:

ptr – The pointer to convert.
len – The number of ValueType elements in the array (not bytes). Used to bounds-check accesses through the returned iterator when SCTL_MEMDEBUG is defined; ignored in release builds.

Returns:

An iterator pointing to the given pointer.

template<class ValueType> ConstIterator<ValueType> sctl::Ptr2ConstItr(const void *ptr, Long len)

Converts a const pointer to a const iterator.

Template Parameters:

ValueType – The type of elements pointed to by the iterator.

Parameters:

ptr – The const pointer to convert.
len – The number of ValueType elements in the array (not bytes). Used to bounds-check accesses through the returned iterator when SCTL_MEMDEBUG is defined; ignored in release builds.

Returns:

A const iterator pointing to the given pointer.

Warning

doxygenfunction: Cannot find function “sctl::memcopy” in doxygen xml output for project “SCTL” from directory: _doxygen/xml

template<class ValueType> Iterator<ValueType> sctl::memset(Iterator<ValueType> ptr, int value, Long num)

Wrapper for memset.

Template Parameters:

ValueType – The type of elements to set.

Parameters:

ptr – The iterator pointing to the memory block.
value – The value to set.
num – The number of elements to set.

Returns:

An iterator pointing to the memory block after setting.

#ifndef _SCTL_ITERATOR_HPP_
#define _SCTL_ITERATOR_HPP_

#include <iterator>         // for random_access_iterator_tag
#include <ostream>          // for operator<<, basic_ostream

#include "sctl/common.hpp"  // for Long, sctl

namespace sctl {

#ifdef SCTL_MEMDEBUG

/**
 * A constant iterator with additional functionalities for memory debugging.  It is enabled by
 * defining the macro `SCTL_MEMDEBUG`, otherwise it is an alias for a raw pointer.
 *
 * @tparam ValueType The type of elements pointed to by the iterator.
 */
template <class ValueType> class ConstIterator {

  template <typename T> friend class ConstIterator;

  template <typename T> friend class Iterator;

  void IteratorAssertChecks(Long j = 0) const;

 public:
  typedef Long difference_type;
  typedef ValueType value_type;
  typedef const ValueType* pointer;
  typedef const ValueType& reference;
  typedef std::random_access_iterator_tag iterator_category;

 protected:
  char* base;                 ///< Base pointer of the array.
  difference_type len;        ///< Length of the array.
  difference_type offset;     ///< Offset from the base pointer.
  Long alloc_ctr;             ///< Allocation counter for memory management.
  void* mem_head;             ///< Pointer to the head of the memory block.
  static const Long ValueSize = sizeof(ValueType);  ///< Size of each element.

 public:
  /**
   * Default constructor.
   */
  ConstIterator();

  /**
   * Constructor with base pointer and length.
   *
   * @param base_ Base pointer of the array.
   * @param len_ Length of the array.
   * @param dynamic_alloc If true, dynamic allocation is used.
   */
  explicit ConstIterator(pointer base_, difference_type len_, bool dynamic_alloc = false);

  /**
   * Template copy constructor.
   *
   * @tparam AnotherType The type of elements in the other iterator.
   * @param I The `ConstIterator` to copy from.
   */
  template <class AnotherType> explicit ConstIterator(const ConstIterator<AnotherType>& I);

  // value_type* like operators
  /**
   * Dereference operator.
   *
   * @return A reference to the element at the current position.
   */
  reference operator*() const;

  /**
   * Member access operator.
   *
   * @return A pointer to the element at the current position.
   */
  pointer operator->() const;

  /**
   * Subscript operator.
   *
   * @param off The offset from the current position.
   * @return A reference to the element at the specified offset.
   */
  reference operator[](difference_type off) const;

  // Increment / Decrement
  /**
   * Pre-increment operator.
   *
   * @return A reference to the updated iterator.
   */
  ConstIterator& operator++();

  /**
   * Post-increment operator.
   *
   * @return A copy of the iterator before incrementing.
   */
  ConstIterator operator++(int);

  /**
   * Pre-decrement operator.
   *
   * @return A reference to the updated iterator.
   */
  ConstIterator& operator--();

  /**
   * Post-decrement operator.
   *
   * @return A copy of the iterator before decrementing.
   */
  ConstIterator operator--(int);

  // Arithmetic
  /**
   * Addition assignment operator.
   *
   * @param i The offset to add.
   * @return A reference to the updated iterator.
   */
  ConstIterator& operator+=(difference_type i);

  /**
   * Addition operator.
   *
   * @param i The offset to add.
   * @return A new iterator pointing to the new position.
   */
  ConstIterator operator+(difference_type i) const;

  /**
   * Addition operator for constant iterator.
   *
   * @tparam T The type of elements pointed to by the iterator.
   * @param i The offset to add.
   * @param right The `ConstIterator` to add the offset to.
   * @return A new iterator pointing to the new position.
   */
  template <class T> friend ConstIterator<T> operator+(typename ConstIterator<T>::difference_type i, const ConstIterator<T>& right);

  /**
   * Subtraction assignment operator.
   *
   * @param i The offset to subtract.
   * @return A reference to the updated iterator.
   */
  ConstIterator& operator-=(difference_type i);

  /**
   * Subtraction operator.
   *
   * @param i The offset to subtract.
   * @return A new iterator pointing to the new position.
   */
  ConstIterator operator-(difference_type i) const;

  /**
   * Difference operator.
   *
   * @param I The iterator to subtract.
   * @return The difference between the current position and the given iterator.
   */
  difference_type operator-(const ConstIterator& I) const;

  // Comparison operators
  /**
   * Equality comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the iterators are equal, `false` otherwise.
   */
  bool operator==(const ConstIterator& I) const;

  /**
   * Inequality comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the iterators are not equal, `false` otherwise.
   */
  bool operator!=(const ConstIterator& I) const;

  /**
   * Less-than comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the current iterator is less than the given iterator, `false` otherwise.
   */
  bool operator<(const ConstIterator& I) const;

  /**
   * Less-than-or-equal comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the current iterator is less than or equal to the given iterator, `false` otherwise.
   */
  bool operator<=(const ConstIterator& I) const;

  /**
   * Greater-than comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the current iterator is greater than the given iterator, `false` otherwise.
   */
  bool operator>(const ConstIterator& I) const;

  /**
   * Greater-than-or-equal comparison operator.
   *
   * @param I The iterator to compare with.
   * @return `true` if the current iterator is greater than or equal to the given iterator, `false` otherwise.
   */
  bool operator>=(const ConstIterator& I) const;

  /**
   * Output stream operator.
   *
   * @param out The output stream.
   * @param I The iterator to output.
   * @return The output stream.
   */
  friend std::ostream& operator<<(std::ostream& out, const ConstIterator& I) {
    out << "(" << (long long)I.base << "+" << I.offset << ":" << I.len << ")";
    return out;
  }
};

/**
 * An iterator with additional functionalities for memory debugging.
 *
 * @tparam ValueType The type of elements pointed to by the iterator.
 */
template <class ValueType> class Iterator : public ConstIterator<ValueType> {

 public:
  typedef Long difference_type;
  typedef ValueType value_type;
  typedef ValueType* pointer;
  typedef ValueType& reference;
  typedef std::random_access_iterator_tag iterator_category;

 public:
  /**
   * Default constructor.
   */
  Iterator();

  /**
   * Constructor with base pointer and length.
   *
   * @param base_ Base pointer of the array.
   * @param len_ Length of the array.
   * @param dynamic_alloc If true, dynamic allocation is used.
   */
  explicit Iterator(pointer base_, difference_type len_, bool dynamic_alloc = false);

  /**
   * Template copy constructor.
   *
   * @tparam AnotherType The type of elements in the other iterator.
   * @param I The `ConstIterator` to copy from.
   */
  template <class AnotherType> explicit Iterator(const ConstIterator<AnotherType>& I);

  // value_type* like operators
  /**
   * Dereference operator.
   *
   * @return A reference to the element at the current position.
   */
  reference operator*() const;

  /**
   * Member access operator.
   *
   * @return A pointer to the element at the current position.
   */
  value_type* operator->() const;

  /**
   * Subscript operator.
   *
   * @param off The offset from the current position.
   * @return A reference to the element at the specified offset.
   */
  reference operator[](difference_type off) const;

  // Increment / Decrement
  /**
   * Pre-increment operator.
   *
   * @return A reference to the updated iterator.
   */
  Iterator& operator++();

  /**
   * Post-increment operator.
   *
   * @return A copy of the iterator before incrementing.
   */
  Iterator operator++(int);

  /**
   * Pre-decrement operator.
   *
   * @return A reference to the updated iterator.
   */
  Iterator& operator--();

  /**
   * Post-decrement operator.
   *
   * @return A copy of the iterator before decrementing.
   */
  Iterator operator--(int);

  // Arithmetic
  /**
   * Addition assignment operator.
   *
   * @param i The offset to add.
   * @return A reference to the updated iterator.
   */
  Iterator& operator+=(difference_type i);

  /**
   * Addition operator.
   *
   * @param i The offset to add.
   * @return A new iterator pointing to the new position.
   */
  Iterator operator+(difference_type i) const;

  /**
   * Addition operator for iterator.
   *
   * @tparam T The type of elements pointed to by the iterator.
   * @param i The offset to add.
   * @param right The `Iterator` to add the offset to.
   * @return A new iterator pointing to the new position.
   */
  template <class T> friend Iterator<T> operator+(typename Iterator<T>::difference_type i, const Iterator<T>& right);

  /**
   * Subtraction assignment operator.
   *
   * @param i The offset to subtract.
   * @return A reference to the updated iterator.
   */
  Iterator& operator-=(difference_type i);

  /**
   * Subtraction operator.
   *
   * @param i The offset to subtract.
   * @return A new iterator pointing to the new position.
   */
  Iterator operator-(difference_type i) const;

  /**
   * Difference operator.
   *
   * @param I The constant iterator to subtract.
   * @return The difference between the current position and the given iterator.
   */
  difference_type operator-(const ConstIterator<ValueType>& I) const;
};

#endif

/**
 * Returns a null iterator.
 *
 * @tparam ValueType The type of elements pointed to by the iterator.
 * @return An iterator pointing to null.
 */
template <class ValueType> Iterator<ValueType> NullIterator();

/**
 * Converts a pointer to an iterator.
 *
 * @tparam ValueType The type of elements pointed to by the iterator.
 * @param ptr The pointer to convert.
 * @param len The number of `ValueType` elements in the array (not bytes).
 * Used to bounds-check accesses through the returned iterator when
 * `SCTL_MEMDEBUG` is defined; ignored in release builds.
 * @return An iterator pointing to the given pointer.
 */
template <class ValueType> Iterator<ValueType> Ptr2Itr(void* ptr, Long len);

/**
 * Converts a const pointer to a const iterator.
 *
 * @tparam ValueType The type of elements pointed to by the iterator.
 * @param ptr The const pointer to convert.
 * @param len The number of `ValueType` elements in the array (not bytes).
 * Used to bounds-check accesses through the returned iterator when
 * `SCTL_MEMDEBUG` is defined; ignored in release builds.
 * @return A const iterator pointing to the given pointer.
 */
template <class ValueType> ConstIterator<ValueType> Ptr2ConstItr(const void* ptr, Long len);

/**
 * Wrapper for memset.
 *
 * @tparam ValueType The type of elements to set.
 * @param ptr The iterator pointing to the memory block.
 * @param value The value to set.
 * @param num The number of elements to set.
 * @return An iterator pointing to the memory block after setting.
 */
template <class ValueType> Iterator<ValueType> memset(Iterator<ValueType> ptr, int value, Long num);

}  // end namespace sctl

#endif // _SCTL_ITERATOR_HPP_