vtkCollectionRange.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
// SPDX-License-Identifier: BSD-3-Clause

#ifndef vtkCollectionRange_h
#define vtkCollectionRange_h

#include "vtkCollection.h"
#include "vtkMeta.h"
#include "vtkRange.h"
#include "vtkSmartPointer.h"

#include <cassert>

namespace vtk
{
namespace detail
{
VTK_ABI_NAMESPACE_BEGIN

template <typename CollectionType>
struct CollectionRange;
template <typename CollectionType>
struct CollectionIterator;

//------------------------------------------------------------------------------
// Detect vtkCollection types
template <typename T>
struct IsCollection : std::is_base_of<vtkCollection, T>
{
};

template <typename CollectionType, typename T = CollectionType>
using EnableIfIsCollection = typename std::enable_if<IsCollection<CollectionType>::value, T>::type;

//------------------------------------------------------------------------------
// Detect the type of items held by the collection by checking the return type
// of GetNextItem(), or GetNextItemAsObject() as a fallback.
template <typename CollectionType>
struct GetCollectionItemType
{
  static_assert(IsCollection<CollectionType>::value, "Invalid vtkCollection subclass.");

private:
  // The GetType methods are only used in a decltype context and are left
  // unimplemented as we only care about their signatures. They are used to
  // determine the type of object held by the collection.
  //
  // By passing literal 0 as the argument, the overload taking `int` is
  // preferred and returns the same type as CollectionType::GetNextItem, which
  // is usually the exact type held by the collection (e.g.
  // vtkRendererCollection::GetNextItem returns vtkRenderer*).
  //
  // If the collection class does not define GetNextItem, SFINAE removes the
  // preferred `int` overload, and the `...` overload is used instead. This
  // method returns the same type as vtkCollection::GetNextItemAsObject, which
  // is vtkObject*. This lets us define a more derived collection item type
  // when possible, while falling back to the general vtkObject if a more
  // refined type is not known.

  // not implemented
  template <typename T>
  static auto GetType(...) -> decltype(std::declval<T>().GetNextItemAsObject());

  // not implemented
  template <typename T>
  static auto GetType(int) -> decltype(std::declval<T>().GetNextItem());

  using PointerType = decltype(GetType<CollectionType>(0));

public:
  // Just use std::remove pointer, vtk::detail::StripPointer is overkill.
  using Type = typename std::remove_pointer<PointerType>::type;
};

//------------------------------------------------------------------------------
// Collection iterator. Reference, value, and pointer types are all ItemType
// pointers, since:
// a) values: ItemType* instead of ItemType because vtkObjects can't be
//    copied/assigned.
// b) references: No good usecase to change the pointers held by the collection
//    by returning ItemType*&, nor would returning ItemType& be useful, since
//    it'd have to be dereferenced anyway to pass it anywhere, and vtkObjects
//    are conventionally held by address.
// c) pointers: Returning ItemType** from operator-> would be useless.
//
// There are no const_reference, etc, since VTK is not const correct and marking
// vtkObjects consts makes them unusable.
template <typename CollectionType>
struct CollectionIterator
{
  static_assert(IsCollection<CollectionType>::value, "Invalid vtkCollection subclass.");

private:
  using ItemType = typename GetCollectionItemType<CollectionType>::Type;

public:
  using iterator_category = std::forward_iterator_tag;
  using value_type = typename GetCollectionItemType<CollectionType>::Type*;
  using difference_type = int;
  using pointer = typename GetCollectionItemType<CollectionType>::Type*;
  using reference = typename GetCollectionItemType<CollectionType>::Type*;

  CollectionIterator(std::vector<vtkObject*>::iterator iterator) noexcept
    : Iterator(iterator)
  {
  }

  CollectionIterator(const CollectionIterator& o) noexcept = default;
  CollectionIterator& operator=(const CollectionIterator& o) noexcept = default;

  CollectionIterator& operator++() noexcept // prefix
  {
    this->Increment();
    return *this;
  }

  CollectionIterator operator++(int) noexcept // postfix
  {
    auto it = this->Iterator;
    this->Increment();
    return CollectionIterator{ it };
  }

  reference operator*() const noexcept { return this->GetItem(); }

  pointer operator->() const noexcept { return this->GetItem(); }

  friend bool operator==(const CollectionIterator& lhs, const CollectionIterator& rhs) noexcept
  {
    return lhs.Iterator == rhs.Iterator;
  }

  friend bool operator!=(const CollectionIterator& lhs, const CollectionIterator& rhs) noexcept
  {
    return lhs.Iterator != rhs.Iterator;
  }

  friend void swap(CollectionIterator& lhs, CollectionIterator& rhs) noexcept
  {
    using std::swap;
    swap(lhs.Iterator, rhs.Iterator);
  }

  friend struct CollectionRange<CollectionType>;

protected:
private:
  void Increment() noexcept
  { // incrementing an invalid iterator is UB, no need to check for non-null.
    this->Iterator++;
  }

  ItemType* GetItem() const noexcept { return static_cast<ItemType*>(*this->Iterator); }

  std::vector<vtkObject*>::iterator Iterator;
};

//------------------------------------------------------------------------------
// Collection range proxy.
// The const_iterators/references are the same as the non-const versions, since
// vtkObjects marked const are unusable.
template <typename CollectionType>
struct CollectionRange
{
  static_assert(IsCollection<CollectionType>::value, "Invalid vtkCollection subclass.");

  using ItemType = typename GetCollectionItemType<CollectionType>::Type;

  // NOTE: The const items are the same as the mutable ones, since const
  // vtkObjects are generally unusable.
  using size_type = int; // int is used by the vtkCollection API.
  using iterator = CollectionIterator<CollectionType>;
  using const_iterator = CollectionIterator<CollectionType>;
  using reference = ItemType*;
  using const_reference = ItemType*;
  using value_type = ItemType*;

  CollectionRange(CollectionType* coll) noexcept
    : Collection(coll)
  {
    assert(this->Collection);
  }

  CollectionType* GetCollection() const noexcept { return this->Collection; }

  size_type size() const noexcept { return this->Collection->GetNumberOfItems(); }

  iterator begin() const { return iterator{ this->Collection->begin() }; }

  iterator end() const { return iterator{ this->Collection->end() }; }

  // Note: These return mutable objects because const vtkObject are unusable.
  const_iterator cbegin() const { return const_iterator{ this->Collection->begin() }; }

  // Note: These return mutable objects because const vtkObjects are unusable.
  const_iterator cend() const { return const_iterator{ this->Collection->end() }; }

private:
  vtkSmartPointer<CollectionType> Collection;
};

VTK_ABI_NAMESPACE_END
}
} // end namespace vtk::detail

#endif // vtkCollectionRange_h

// VTK-HeaderTest-Exclude: vtkCollectionRange.h