DataVector.icc

Go to the documentation of this file.

// Dear emacs, this is -*- c++ -*-
 
/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
*/
/**
 * @file  AthContainers/DataVector.icc
 * @author scott snyder, Paolo Calafiura, etc
 * @date May 2005; rewritten from earlier version.
 * @brief An STL vector of pointers that by default owns its pointed-to
 *        elements.
 *        Implementation file.
 */
 
 
#include "AthContainers/tools/CompareAndPrint.h"
#include "AthContainers/tools/ATHCONTAINERS_ASSERT.h"
#include "CxxUtils/releasing_iterator.h"
#include "CxxUtils/throw_out_of_range.h"
#include <limits>
#include <functional>
 
 
//****************************************************************************
// VirtBases
//
 
namespace ROOT { namespace Meta { namespace Selection {
  namespace DataVector_detail {
    template <class B1, class B2, class B3> class VirtBases;
  }
}}} // ROOT namespace
 
 
namespace DataVector_detail {
 
/* #define DO_REMOVE_DUPLICATES to activate for debugging purposes (Slow) */
// Note: this name should be distinct from the corresponding one in DataList,
// even though they're in different namespaces.  This due to an apparent
// Koenig lookup bug in gccxml 0.9.0.
template <class FI>
void optimizeMeAway_DV(FI, bool){}
/**
 * @brief Remove duplicates from a @c DataVector before deleting elements.
 * @param b Start of range to scan.
 * @param e One past end of range to scan.
 * @param quiet If true, complain if duplicates are found.
 * @return One past the last unique elements.
 *
 * The elements within the range are sorted, then duplicate elements
 * are moved to the end.  If duplicate elements are found and
 * @a quiet is @c true, then a complaint will be printed.
 */
template <class ForwIter>
ForwIter remove_duplicates(ForwIter b, ForwIter e, bool quiet=false)
{
#ifdef DO_REMOVE_DUPLICATES
  std::sort(b, e);
  return std::unique(b, e, DataModel_detail::CompareAndPrint(quiet));
#else
  optimizeMeAway_DV(b, quiet);
  return e;
#endif
}
 
/**
 * @brief VirtBases for one class.
 *
 * @c DataVector<T> derives from this for the case of
 * @c T deriving virtually from a single class.
 * It in turn derives from @c B1.
 */
template <class B1>
struct VirtBases<B1, DataModel_detail::NoBase, DataModel_detail::NoBase>
  : virtual public DataVector<B1>
{
  // Make these types available to the derived @c DataVector.
  typedef typename DataVector<B1>::PtrVector PtrVector;
  typedef typename DataVector<B1>::size_type size_type;
  typedef typename DataVector<B1>::difference_type difference_type;
  typedef typename DataVector<B1>::allocator_type allocator_type;
  typedef typename DataVector<B1>::Deleter Deleter;
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool must_own = DataVector<B1>::must_own;
 
  // We're using virtual derivation.
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool has_virtual = true;
 
  // We need to delete the move ctor; otherwise, we get warnings about
  // a virtual base having a non-trivial move ctor.  Then we also need
  // to explicitly default the ordinary ctors so that they remain visible.
  VirtBases () = default;
  VirtBases (const VirtBases&) = default;
  // default doesn't work here with gcc 4.7; it does with 4.9.
  VirtBases& operator= (VirtBases&) { return *this; }
  VirtBases& operator= (VirtBases&&) = delete;
 
 
protected:
  // Pass this down to base classes.
  void clearMostDerived()
  {
    DataVector<B1>::clearMostDerived();
  }
 
  // We need these here to prevent ambiguities,
  // but they shouldn't actually be called.
  virtual const std::type_info& dv_typeid() const override
  {
    return typeid(VirtBases);
  }
  virtual const DataModel_detail::DVLInfoBase& dvlinfo_v() const override
  {
    return DataVector<B1>::dvlinfo();
  }
  virtual void setMostDerived() override
  {
    std::abort();
  }
 
 
  static
  int baseOffset1 (const char* p, const VirtBases& dv,
                   const std::type_info& ti)
  {
    return DataVector<B1>::baseOffset1 (p, dv, ti);
  }
 
 
private:
  typedef typename
  ROOT::Meta::Selection::
    DataVector_detail::VirtBases<B1,
                                 DataModel_detail::NoBase,
                                 DataModel_detail::NoBase>::self self;
};
 
 
/**
 * @brief VirtBases for two classes.
 *
 * @c DataVector<T> derives from this for the case of
 * @c T deriving from two classes.
 * It in turn derives from @c B1 and @c B2.
 */
template <class B1, class B2>
struct VirtBases<B1, B2, DataModel_detail::NoBase>
  : virtual public DataVector<B1>,
    virtual public DataVector<B2>
{
  // Check to be sure that @c B1 and @c B2 have the same ultimate base type.
  static_assert (std::is_same_v<typename DataVector<B1>::PtrVector,
                                typename DataVector<B2>::PtrVector>);
 
  // Make these types available to the derived @c DataVector.
  typedef typename DataVector<B1>::PtrVector PtrVector;
  typedef typename DataVector<B1>::size_type size_type;
  typedef typename DataVector<B1>::difference_type difference_type;
  typedef typename DataVector<B1>::allocator_type allocator_type;
  typedef typename DataVector<B1>::Deleter Deleter;
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool must_own = DataVector<B1>::must_own;
 
  // We're using virtual derivation.
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool has_virtual = true;
 
 
  // We need to delete the move ctor; otherwise, we get warnings about
  // a virtual base having a non-trivial move ctor.  Then we also need
  // to explicitly default the ordinary ctors so that they remain visible.
  VirtBases () = default;
  VirtBases (const VirtBases&) = default;
  // default doesn't work here with gcc 4.7; it does with 4.9.
  VirtBases& operator= (VirtBases&) { return *this; }
  VirtBases& operator= (VirtBases&&) = delete;
 
 
protected:
  // Pass this down to base classes.
  void clearMostDerived()
  {
    DataVector<B1>::clearMostDerived();
    DataVector<B2>::clearMostDerived();
  }
 
  // We need these here to prevent ambiguities,
  // but they shouldn't actually be called.
  virtual const std::type_info& dv_typeid() const override
  {
    return typeid(VirtBases);
  }
  virtual const DataModel_detail::DVLInfoBase& dvlinfo_v() const override
  {
    return DataVector<B1>::dvlinfo();
  }
  virtual void setMostDerived() override
  {
    std::abort();
  }
 
 
  static
  int baseOffset1 (const char* p, const VirtBases& dv,
                   const std::type_info& ti)
  {
    int ret = DataVector<B1>::baseOffset1 (p, dv, ti);
    if (ret >= 0)
      return ret;
    return DataVector<B2>::baseOffset1 (p, dv, ti);
  }
 
 
private:
  typedef typename
  ROOT::Meta::Selection::
    DataVector_detail::VirtBases<B1, B2,
                                 DataModel_detail::NoBase>::self self;
};
 
 
/**
 * @brief VirtBases for three classes.
 *
 * @c DataVector<T> derives from this for the case of
 * @c T deriving from three classes.
 * It in turn derives from @c B1, @c B2, and @c B3.
 */
template <class B1, class B2, class B3>
struct VirtBases
  : virtual public DataVector<B1>,
    virtual public DataVector<B2>,
    virtual public DataVector<B3>
{
  // Check to be sure that @c B1, @c B2, and @c B3 have the same
  // ultimate base type.
  static_assert (std::is_same_v<typename DataVector<B1>::PtrVector,
                                typename DataVector<B2>::PtrVector>);
  static_assert (std::is_same_v<typename DataVector<B1>::PtrVector,
                                typename DataVector<B3>::PtrVector>);
 
 
  // Make these types available to the derived @c DataVector.
  typedef typename DataVector<B1>::PtrVector PtrVector;
  typedef typename DataVector<B1>::size_type size_type;
  typedef typename DataVector<B1>::difference_type difference_type;
  typedef typename DataVector<B1>::allocator_type allocator_type;
  typedef typename DataVector<B1>::Deleter Deleter;
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool must_own = DataVector<B1>::must_own;
 
  // We're using virtual derivation.
  // cppcheck-suppress duplInheritedMember; deliberate
  static constexpr bool has_virtual = true;
 
 
  // We need to delete the move ctor; otherwise, we get warnings about
  // a virtual base having a non-trivial move ctor.  Then we also need
  // to explicitly default the ordinary ctors so that they remain visible.
  VirtBases () = default;
  VirtBases (const VirtBases&) = default;
  // default doesn't work here with gcc 4.7; it does with 4.9.
  VirtBases& operator= (VirtBases&) { return *this; }
  VirtBases& operator= (VirtBases&&) = delete;
 
 
protected:
  // Pass this down to base classes.
  void clearMostDerived()
  {
    DataVector<B1>::clearMostDerived();
    DataVector<B2>::clearMostDerived();
    DataVector<B3>::clearMostDerived();
  }
 
  // We need these here to prevent ambiguities,
  // but they shouldn't actually be called.
  virtual const std::type_info& dv_typeid() const override
  {
    return typeid(VirtBases);
  }
  virtual const DataModel_detail::DVLInfoBase& dvlinfo_v() const override
  {
    return DataVector<B1>::dvlinfo();
  }
  virtual void setMostDerived() override
  {
    std::abort();
  }
 
 
  static
  int baseOffset1 (const char* p, const VirtBases& dv,
                   const std::type_info& ti)
  {
    int ret = DataVector<B1>::baseOffset1 (p, dv, ti);
    if (ret >= 0)
      return ret;
    ret = DataVector<B2>::baseOffset1 (p, dv, ti);
    if (ret >= 0)
      return ret;
    return DataVector<B3>::baseOffset1 (p, dv, ti);
  }
 
 
private:
  typedef typename
  ROOT::Meta::Selection::DataVector_detail::VirtBases<B1, B2, B3>::self
  self;
};
 
 
} // namespace DataVector_detail
 
 
namespace ROOT { namespace Meta { namespace Selection {
namespace DataVector_detail {
 
template< class B1, class B2, class B3 >
class VirtBases : KeepFirstTemplateArguments< 1 >, SelectNoInstance
{
 
public:
   /// A helper typedef
   typedef DataVector_detail::VirtBases< B1, B2, B3 > self;
 
};
 
}
}}}  // ROOT namespace
 
 
//****************************************************************************
// Generic (derived) DataVector implementation.
//
 
 
//=== Constructors, destructors, assignment.
 
 
/**
 * @brief Default constructor.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 *
 * By default, a @c DataVector will own its elements.
 * To avoid this, pass @c SG::VIEW_ELEMENTS for @a ownPolicy.
 *
 * Note that we do the complete initialization here in the derived class,
 * using the default constructors for the base classes.  The reason
 * for this is to be able to deal nicely with the virtual derivation
 * case.  We can arrange to call the proper base class from here to get
 * things initialized in the virtual derivation case.  But then anyone
 * who derives from us must also know to explicitly reference that base
 * class.  Doing the initialization explicitly here means that other classes
 * who derive from us need only know about the most derived DataVector
 * class.
 */
template <class T, class BASE>
inline
DataVector<T, BASE>::DataVector
  (SG::OwnershipPolicy ownPolicy /*= SG::OWN_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_TRACK_INDICES*/)
{
  this->m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
  BASE::clearMostDerived();
}
 
 
/**
 * @brief Sized constructor.
 * @param n The size of the container.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 *
 * Note that unlike the standard vector constructor, you can't specify
 * an initial value here.  The container will be initialized with 0's.
 *
 * By default, a @c DataVector will own its elements.
 * To avoid this, pass @c SG::VIEW_ELEMENTS for @a ownPolicy.
 *
 * Note that we do the complete initialization here in the derived class,
 * using the default constructors for the base classes.  The reason
 * for this is to be able to deal nicely with the virtual derivation
 * case.  We can arrange to call the proper base class from here to get
 * things initialized in the virtual derivation case.  But then anyone
 * who derives from us must also know to explicitly reference that base
 * class.  Doing the initialization explicitly here means that other classes
 * who derive from us need only know about the most derived DataVector
 * class.
 */
template <class T, class BASE>
inline
DataVector<T, BASE>::DataVector
  (size_type n,
   SG::OwnershipPolicy ownPolicy /*= SG::OWN_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*=SG::DEFAULT_TRACK_INDICES*/)
{
  this->m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
  BASE::clearMostDerived();
  this->m_pCont.resize (n);
}
 
 
/**
 * @brief Move constructor.
 * @param rhs The container from which to move.
 *
 * Any auxiliary data will be moved along with the container contents.
 */
template <class T, class BASE>
DataVector<T, BASE>::DataVector (DataVector&& rhs) noexcept
{
  SG::AuxVectorBase::operator= (std::move (rhs));
  this->m_ownPolicy = rhs.m_ownPolicy;
  this->m_pCont = std::move (rhs.m_pCont);
  this->m_deleter = std::move(rhs.m_deleter);
  rhs.m_deleter = nullptr;
 
  // Need to reset the container pointer on elements.
  this->setIndices (this->begin(), this->end());
  this->m_isMostDerived = true;
}
 
 
/**
 * @brief Constructor from iterators.
 * @param first The start of the range to put in the new container.
 * @param last The end of the range to put in the new container.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 * @param store An associated auxiliary data store.
 *
 * By default, a view container is made, which does not own its elements.
 * To have the container take ownership of the pointers passed
 * to this constructor, pass @c SG::OWN_ELEMENTS for @a ownPolicy.
 *
 * Note that we do the complete initialization here in the derived class,
 * using the default constructors for the base classes.  The reason
 * for this is to be able to deal nicely with the virtual derivation
 * case.  We can arrange to call the proper base class from here to get
 * things initialized in the virtual derivation case.  But then anyone
 * who derives from us must also know to explicitly reference that base
 * class.  Doing the initialization explicitly here means that other classes
 * who derive from us need only know about the most derived DataVector
 * class.
 */
template <class T, class BASE>
template <class InputIterator>
inline
DataVector<T, BASE>::DataVector
  (InputIterator first,
   InputIterator last,
   SG::OwnershipPolicy ownPolicy /*= SG::VIEW_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_INDEX_TRACKING*/,
   SG::IAuxStore* store /*= 0*/)
{
  // Make sure that the input iterator can actually be converted
  // to a T*.  Lets us give a compilation error for this:
  //   DATAVECTOR_BASE(D, B);
  //   B* bb[] = ...
  //   DataVector<D> d (bb, bb+1);
  // which would otherwise compile.
  //FIXME: Rewrite using concepts once we're using c++20.
  using ittype = typename std::iterator_traits<InputIterator>::value_type;
  static_assert (std::is_convertible_v<ittype, const T*> ||
                 std::is_convertible_v<ittype, std::unique_ptr<T> >);
  
  this->m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
  BASE::clearMostDerived();
  if (store)
    this->setStore (store);
  insert (this->begin(), first, last);
}
 
 
/**
 * @brief Constructor from an initializer list.
 * @param l An initializer list.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 * @param store An associated auxiliary data store.
 *
 *
 * A @c DataVector constructed this way will *not* own its elements
 * by default.  To change this, pass @c SG::OWN_ELEMENTS for @a ownPolicy.
 *
 * Note that we do the complete initialization here in the derived class,
 * using the default constructors for the base classes.  The reason
 * for this is to be able to deal nicely with the virtual derivation
 * case.  We can arrange to call the proper base class from here to get
 * things initialized in the virtual derivation case.  But then anyone
 * who derives from us must also know to explicitly reference that base
 * class.  Doing the initialization explicitly here means that other classes
 * who derive from us need only know about the most derived DataVector
 * class.
 */
template <class T, class BASE>
inline
DataVector<T, BASE>::DataVector
  (std::initializer_list<value_type> l,
   SG::OwnershipPolicy ownPolicy /*= SG::VIEW_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_INDEX_TRACKING*/,
   SG::IAuxStore* store /*= 0*/)
    : DataVector (l.begin(), l.end(), ownPolicy, trackIndices, store)
{
}
 
 
/**
 * @brief Assignment operator.
 * @param rhs The DataVector from which to assign.
 * @return This object.
 *
 * This is a `shallow' copy; after the completion of this, the DataVector
 * will not own its elements.  Any elements it owned prior to this call
 * will be released.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
inline
DataVector<T, BASE>& DataVector<T, BASE>::operator= (const DataVector& rhs)
{
  if (&rhs != this) {
    // Ensure we're not being called via a base class.
    testInsert ("assignment operator");
    this->clear();                // Release any currently-owned elements.
    this->m_ownPolicy = SG::VIEW_ELEMENTS;
    this->setStore ((SG::IConstAuxStore*)0);
    this->template initAuxVectorBase<DataVector>(this->m_ownPolicy,
                                                 SG::DEFAULT_TRACK_INDICES);
    this->m_pCont = rhs.m_pCont;
  }
  return *this;
}
 
 
/**
 * @brief Move assignment.
 * @param rhs The container from which to move.
 *
 * Any auxiliary data will be moved along with the container contents.
 *
 * (Can't be noexcept because testInsert() can throw.)
 */
template <class T, class BASE>
DataVector<T, BASE>&
DataVector<T, BASE>::operator= (DataVector<T, BASE>&& rhs)
{
  if (this != &rhs) {
    // Ensure we're not being called via a base class.
    testInsert ("assignment operator");
 
    this->clear();                // Release any currently-owned elements.
 
    SG::AuxVectorBase::operator= (std::move (rhs));
    this->m_ownPolicy = rhs.m_ownPolicy;
    this->m_pCont = std::move (rhs.m_pCont);
 
    delete this->m_deleter;
    this->m_deleter = std::move(rhs.m_deleter);
    rhs.m_deleter = nullptr;
 
    // Need to reset the container pointer on elements.
    this->setIndices (this->begin(), this->end());
  }
  return *this;
}
 
 
/**
 * @brief Assignment operator, from an initializer list.
 * @param l An initializer list.
 * @return This object.
 *
 * This is equivalent to @c assign.
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T, class BASE>
inline
DataVector<T, BASE>&
DataVector<T, BASE>::operator= (std::initializer_list<value_type> l)
{
  this->assign (l.begin(), l.end());
  return *this;
}
 
 
/**
 * @brief Assign from iterators.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T, class BASE>
template <class InputIterator>
void DataVector<T, BASE>::assign(InputIterator first, InputIterator last)
{
  // Ensure we're not being called via a base class.
  testInsert ("assign");
  this->clear();                // Release any currently-owned elements.
  insert(begin(), first, last);
}
 
 
/**
 * @brief Assign from an initializer list.
 * @param l An initializer list.
 *
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T, class BASE>
void DataVector<T, BASE>::assign(std::initializer_list<value_type> l)
{
  this->assign (l.begin(), l.end());
}
 
 
//=== Size and capacity.
 
 
/**
 * @fn size_type size() const
 * @brief Returns the number of elements in the collection.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::size_type
DataVector<T, BASE>::size() const noexcept
{
  return this->m_pCont.size();
}
 
 
/**
 * @brief Resizes the collection to the specified number of elements.
 * @param sz The new size of the collection.
 *
 * Note that this function differs from the standard in that it does
 * not allow specifying the value of any inserted elements.
 * They will always be 0.
 *
 * If the container is shrunk, elements will be deleted as with @c erase().
 */
template <class T, class BASE>
void DataVector<T, BASE>::resize(size_type sz)
{ 
  if (sz < this->size()) {
    this->erase (this->begin()+sz, this->end());
  } else {
    this->m_pCont.insert(this->m_pCont.end(), sz - this->m_pCont.size(), 0);
    SG::AuxVectorBase::resize<DataVector> (sz);
  }
} 
 
 
/**
 * @brief Attempt to preallocate enough memory for a specified number
 *        of elements.
 * @param n Number of elements required.
 */
template <class T, class BASE>
inline
void DataVector<T, BASE>::reserve (size_type n)
{
  this->m_pCont.reserve (n);
  SG::AuxVectorBase::reserve<DataVector> (n);
}
 
 
//=== Element access.
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 *
 * No bounds checking is done.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T, class BASE>
inline
const T* DataVector<T, BASE>::operator[] (size_type n) const
{
  return do_cast(this->m_pCont[n]);
}
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 * 
 * This is a synonym for operator[] const, to be used when calling from root
 * (where we can't readily call just the const version of a method).
 */
template <class T, class BASE>
inline
const T* DataVector<T, BASE>::get (size_type n) const
{
  return do_cast(this->m_pCont[n]);
}
 
 
/**
 * @brief Access an element, as an lvalue.
 * @param n Array index to access.
 * @return Proxy to the element at @a n.
 *
 * No bounds checking is done.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::ElementProxy
DataVector<T, BASE>::operator[] (size_type n)
{
  return ElementProxy (this->m_pCont.begin() + n, this);
}
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 *
 * Will raise @c std::out_of_range if the index is out-of-bounds.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T, class BASE>
inline
const T* DataVector<T, BASE>::at (size_type n) const
{
  return do_cast(this->m_pCont.at(n));
}
 
 
/**
 * @brief Access an element, as an lvalue.
 * @param n Array index to access.
 * @return Proxy to the element at @a n.
 *
 * Will raise @c std::out_of_range if the index is out-of-bounds.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::ElementProxy
DataVector<T, BASE>::at (size_type n)
{
  // Can't use m_pCont's at here, because we need an iterator.
  // So we have to do the bounds check ourselves.
  if (n >= this->size())
    CxxUtils::throw_out_of_range  (__PRETTY_FUNCTION__, n, this->size(), this);
  return ElementProxy (this->m_pCont.begin() + n, this);
}
 
 
/**
 * @brief Access the first element in the collection as an rvalue.
 * @return The first element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T, class BASE>
inline
const T* DataVector<T, BASE>::front() const
{
  return do_cast (this->m_pCont.front());
}
 
 
/**
 * @brief Access the last element in the collection as an rvalue.
 * @return The last element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T, class BASE>
inline
const T* DataVector<T, BASE>::back() const
{
  return do_cast (this->m_pCont.back());
}
 
 
/**
 * @brief Access the first element in the collection as an lvalue.
 * @return Proxy to the first element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::ElementProxy
DataVector<T, BASE>::front ()
{
  return ElementProxy (this->m_pCont.begin(), this);
}
 
 
/**
 * @brief Access the last element in the collection as an lvalue.
 * @return Proxy to the last element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::ElementProxy
DataVector<T, BASE>::back ()
{
  return ElementProxy (this->m_pCont.end()-1, this);
}
 
 
//=== Iterator creation.
 
 
/**
 * @brief Return a @c const_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_iterator
DataVector<T, BASE>::begin() const noexcept
{
  return const_iterator (this->m_pCont.begin());
}
 
 
/**
 * @brief Return a @c const_iterator pointing past the end
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_iterator
DataVector<T, BASE>::end() const noexcept
{
  return const_iterator (this->m_pCont.end());
}
 
 
/**
 * @brief Return an @c iterator pointing at the beginning
 *        of the collection.
 * @return An @c iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::begin() noexcept
{
  return iterator (this->m_pCont.begin(), this);
}
 
 
/**
 * @brief Return an @c iterator pointing past the end
 *        of the collection.
 * @return An @c iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::end() noexcept
{
  return iterator (this->m_pCont.end(), this);
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_reverse_iterator
DataVector<T, BASE>::rbegin() const noexcept
{
  return const_reverse_iterator (end());
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_reverse_iterator
DataVector<T, BASE>::rend() const noexcept
{
  return const_reverse_iterator (begin());
}
 
 
/**
 * @brief Return a @c reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::reverse_iterator
DataVector<T, BASE>::rbegin() noexcept
{
  return reverse_iterator (iterator (this->m_pCont.end(), this));
}
 
 
/**
 * @brief Return a @c reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::reverse_iterator
DataVector<T, BASE>::rend() noexcept
{
  return reverse_iterator (iterator (this->m_pCont.begin(), this));
}
 
 
/**
 * @brief Return a @c const_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_iterator
DataVector<T, BASE>::cbegin() const noexcept
{
  return const_iterator (this->m_pCont.begin());
}
 
 
/**
 * @brief Return a @c const_iterator pointing past the end
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_iterator
DataVector<T, BASE>::cend() const noexcept
{
  return const_iterator (this->m_pCont.end());
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_reverse_iterator
DataVector<T, BASE>::crbegin() const noexcept
{
  return const_reverse_iterator (cend());
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::const_reverse_iterator
DataVector<T, BASE>::crend() const noexcept
{
  return const_reverse_iterator (cbegin());
}
 
 
//=== Insertion operations.
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the pushed pointer.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::value_type
DataVector<T, BASE>::push_back(value_type pElem)
{
  // Ensure we're not being called via a base class.
  testInsert ("push_back");
  this->m_pCont.push_back(static_cast<typename PtrVector::value_type>(pElem));
  SG::AuxVectorBase::resize<DataVector> (this->size());
  if (pElem && this->trackIndices())
    this->moveAuxNoClear (this->size()-1, pElem);
  return pElem;
}
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container must be an owning container.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the pushed pointer.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::value_type
DataVector<T, BASE>::push_back(std::unique_ptr<base_value_type> pElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  // Ensure we're not being called via a base class.
  testInsert ("push_back");
  value_type ptr = pElem.release();
  this->m_pCont.push_back(ptr);
  SG::AuxVectorBase::resize<DataVector> (this->size());
  if (ptr && this->trackIndices())
    this->moveAuxNoClear (this->size()-1, ptr);
  return ptr;
}
 
 
/**
 * @brief Create and add a number of new elements to the end of the container.
 * @param n The number of new elements to add.
 * @param alloc Functional to call to allocate a new element to push.
 *              Should be callable like <code>T* = alloc();</code>
 *              For example:
 *@code
 *                dv.push_new (n, [](){ return new Foo; });
 @endcode
 *              It may also be useful to allocate from a @c DataPool.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the original size of the vector.
 */
template <class T, class BASE>
template <CxxUtils::detail::AllocationFunction<T> F>
auto
DataVector<T, BASE>::push_new(size_type n, F alloc) -> size_type
{
  // Ensure we're not being called via a base class.
  testInsert ("push_new");
  bool trackIndices = this->trackIndices();
 
  size_t sz = this->m_pCont.size();
  this->m_pCont.resize (sz + n);
  SG::AuxVectorBase::resize<DataVector> (this->size());
  for (size_t i = 0; i < n; i++) {
    T* p = alloc();
    if (!p) std::abort();
    this->m_pCont[sz+i] = p;
    if (trackIndices) {
      this->moveAuxNoClear (sz+i, p);
    }
  }
  return sz;
}
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * For @c DataVector, this is like the same as @c push_back, and
 * it returns the pushed element.
 * It's included just for interface compatibility with `std::vector`.
 */
template <class T, class BASE>
inline
typename DataVector<T, BASE>::value_type
DataVector<T, BASE>::emplace_back(value_type pElem)
{
  return this->push_back (pElem);
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::insert(iterator position, value_type pElem)
{
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  iterator ret (this->m_pCont.insert(position.base(), pElem), this);
  this->shift (ret - this->begin(), 1);
  this->moveAux (ret-this->begin(), pElem, false, true);
  return ret;
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container must be an owning container.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::insert(iterator position,
                            std::unique_ptr<base_value_type> pElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  value_type ptr = pElem.release();
  iterator ret (this->m_pCont.insert(position.base(), ptr), this);
  this->shift (ret - this->begin(), 1);
  if (this->trackIndices())
    this->moveAuxNoClear (ret-this->begin(), ptr);
  return ret;
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * For @c DataVector, this is just the same as @c insert.
 * It's included just for interface compatibility with `std::vector`.
 */
template <class T, class BASE>
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::emplace(iterator position, value_type pElem)
{
  return this->insert (position, pElem);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * This overload is for the case where the iterator value type
 * is convertible to T*.
 */
template <class T, class BASE>
template <class InputIterator,
          DataVector_detail::enable_if_ptr_itr<InputIterator, T> >
void DataVector<T, BASE>::insert(iterator position,
                                 InputIterator first,
                                 InputIterator last)
{
  // Make sure that the input iterator can actually be converted
  // to a T*.  Lets us give a compilation error for this:
  //   DATAVECTOR_BASE(D, B);
  //   B* bb[] = ...
  //   DataVector<D> d;
  //   d.insert (d.begin(), bb, bb+1);
  // which would otherwise compile.
  using ittype = typename std::iterator_traits<InputIterator>::value_type;
  static_assert (std::is_convertible_v<ittype, const T*>);
 
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  size_t idx = position - this->begin();
  size_t old_sz = this->m_pCont.size();
  this->m_pCont.insert(position.base(), first, last);
  size_t n = this->m_pCont.size() - old_sz;
  this->shift (idx, n);
  this->moveAux (idx, first, last, false, true);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * This overload is for the case where the iterator value type
 * is convertible to unique_ptr<T>.
 */
template <class T, class BASE>
template <class InputIterator,
          DataVector_detail::enable_if_up_itr<InputIterator, T> >
void DataVector<T, BASE>::insert(iterator position,
                                 InputIterator first,
                                 InputIterator last)
{
  // Make sure that the input iterator can actually be converted
  // to a T*.  Lets us give a compilation error for this:
  //   DATAVECTOR_BASE(D, B);
  //   B* bb[] = ...
  //   DataVector<D> d;
  //   d.insert (d.begin(), bb, bb+1);
  // which would otherwise compile.
  using ittype = typename std::iterator_traits<InputIterator>::value_type;
  static_assert (std::is_convertible_v<typename ittype::pointer, const T*>);
 
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  size_t idx = position - this->begin();
  size_t old_sz = this->m_pCont.size();
  using CxxUtils::releasing_iterator;
  this->m_pCont.insert(position.base(), releasing_iterator(first), releasing_iterator(last));
  size_t n = this->m_pCont.size() - old_sz;
  this->shift (idx, n);
  this->moveAux (idx, this->begin()+idx, this->begin()+idx+n);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param l An initializer list.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void DataVector<T, BASE>::insert(iterator position,
                                 std::initializer_list<value_type> l)
{
  insert (position, l.begin(), l.end());
}
 
 
/**
 * @brief Insert the contents of another @c DataVector,
 *        with auxiliary data copied via move semantics.
 * @param position Iterator before which the new elements will be added.
 * @param other The vector to add.
 *
 * The ownership mode of this vector must be the same as @c other;
 * otherwise, an exception will be thrown.
 *
 * If both vectors are view vectors, then this is the same
 * as <code> insert (position, other.begin(), other.end()) </code>.
 *
 * Otherwise, the elements from @c other will be inserted into this vector.
 * This vector will take ownership of the elements, and the ownership
 * mode of @c other will be changed to @c VIEW_ELEMENTS.
 * Auxiliary data for these elements will be transferred,
 * using move semantics if possible.  (Thus, the auxiliary store
 * for @c other may be modified and must not be locked.)
 * Finally, the auxiliary store pointer for @c other will be cleared
 * (but the store itself will not be deleted since it's not owned
 * by the vector).
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void
DataVector<T, BASE>::insertMove (iterator position, DataVector& other)
{
  if (this->m_ownPolicy != other.ownPolicy())
    throw SG::ExcInsertMoveOwnershipMismatch();
 
  if (this->m_ownPolicy == SG::VIEW_ELEMENTS) {
    this->insert (position, other.begin(), other.end());
    return;
  }
 
  testInsert ("insertMove");
  size_t pos = position.base() - this->m_pCont.begin();
  this->m_pCont.insert (position.base(), other.begin(), other.end());
  this->setIndices (this->begin()+pos, this->end(), pos);
  other.m_ownPolicy = SG::VIEW_ELEMENTS;
 
  SG::IAuxStore* otherStore = other.getStore();
  if (otherStore) {
    SG::IAuxStore* store = this->getStore();
    if (store) {
      if (!store->insertMove (pos, *otherStore))
        this->clearCache();
    }
    else if (this->hasStore())
      throw SG::ExcConstAuxData ("insertMove");
    other.setStore (static_cast<SG::IAuxStore*>(nullptr));
  }
  else if (other.hasStore())
    throw SG::ExcConstAuxData ("insertMove");
}
 
 
//=== Erasure operations.
 
 
/**
 * @brief Remove element at a given position.
 * @param position Iterator pointing to the element to be removed.
 * @return An iterator pointing to the next element (or @c end()).
 *
 * If the container owns its elements, then the pointed-to element
 * will be deleted.
 */
template <class T, class BASE>
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::erase(iterator position)
{ 
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndex (position);
  iterator ret (this->erase_base (position.base()), this);
  this->shift (ret - this->begin() + 1, -1);
  return ret;
}
 
 
/**
 * @brief Remove a range of elements.
 * @param first Iterator pointing to the first element to be removed.
 * @param last Iterator pointing one past the last element to be removed.
 * @return An iterator pointing to the element pointed to by @a last
 *         prior to erasing (or @c end()).
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T, class BASE>
typename DataVector<T, BASE>::iterator
DataVector<T, BASE>::erase(iterator first, iterator last)
{
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndices (first, last);
  iterator ret (this->erase_base (first.base(), last.base()), this);
  this->shift (ret - this->begin() + (last-first), -(last-first));
  return ret;
}
 
 
/**
 * @brief Remove the last element from the collection.
 *
 * If the container owns its elements, then the removed element
 * will be deleted.
 */
template <class T, class BASE>
void DataVector<T, BASE>::pop_back()
{
  if (!this->m_pCont.empty()) {
    if (this->m_ownPolicy == SG::OWN_ELEMENTS)
      this->doDelete (this->m_pCont.back());
    else
      this->clearIndex (iterator (this->m_pCont.end() - 1, this));
    this->m_pCont.pop_back();
    SG::AuxVectorBase::resize<DataVector> (this->m_pCont.size());
  }
}
 
 
/**
 * @brief Erase all the elements in the collection.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T, class BASE>
inline
void DataVector<T, BASE>::clear()
{
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndices (begin(), end());
  this->erase_base (this->m_pCont.begin(), this->m_pCont.end());
  SG::AuxVectorBase::resize<DataVector> (0);
}
 
 
//=== Swap and sort.
 
 
/**
 * @brief Swap this collection with another.
 * @param rhs The collection with which to swap.
 *
 * Ownership is swapped along with the collection content.
 *
 * Note: this method may only be called using the most-derived
 * @c DataVector in the hierarchy.  The @a rhs must also be
 * referenced using the most-derived @c DataVector.
 *
 * Warning: If this container has auxiliary data, then this
 * is an O(N) operation, not O(1).
 */
template <class T, class BASE>
void DataVector<T, BASE>::swap(DataVector& rhs)
{
  testInsert ("swap");
  rhs.testInsert ("swap");
  std::swap(this->m_ownPolicy, rhs.m_ownPolicy);
  SG::AuxVectorBase::swap (rhs);
  this->m_pCont.swap(rhs.m_pCont);
  std::swap (this->m_deleter, rhs.m_deleter);
  this->setIndices (this->begin(), this->end());
  rhs.setIndices (rhs.begin(), rhs.end());
}
 
 
/**
 * @brief Swap the referents of two @c DataVector iterators.
 * @param a The first iterator for the swap.
 * @param b The second iterator for the swap.
 */
template <class T, class BASE>
void DataVector<T, BASE>::iter_swap (iterator a, iterator b)
{
  if (a.ownPolicy() != b.ownPolicy()) {
    throw SG::ExcBadIterSwap();
  }
  a.testInsert ("iter_swap");
  b.testInsert ("iter_swap");
  std::iter_swap (a.base(), b.base());
  DataVector* acont = a.container();
  DataVector* bcont = b.container();
  if (typename SG::AuxStore_traits<DataVector>::flag())
    acont->swapElementsAux (a.base() - acont->stdcont().begin(),
                            b.base() - bcont->stdcont().begin(),
                            DataModel_detail::DVLCast<DataVector>::cast(*a.base()),
                            DataModel_detail::DVLCast<DataVector>::cast(*b.base()),
                            bcont);
}
 
 
/**
 * @brief Sort the container.
 *
 * This just sorts by pointer value, so it's probably not very useful.
 */
template <class T, class BASE>
void DataVector<T, BASE>::sort()
{
  typedef std::less<typename PtrVector::value_type> less;
  std::sort (this->m_pCont.begin(), this->m_pCont.end(),
             DataModel_detail::Compwrapper<DataVector, less> (less()));
  this->resortAux (this->begin(), this->end());
}
 
 
/**
 * @brief Sort the container with a user-specified comparison operator.
 * @param comp Functional to compare two values.
 */
template <class T, class BASE>
template <class COMPARE>
void DataVector<T, BASE>::sort(COMPARE comp)
{
  std::sort (this->m_pCont.begin(), this->m_pCont.end(),
             DataModel_detail::Compwrapper<DataVector, COMPARE> (comp));
  this->resortAux (this->begin(), this->end());
}
 
 
//=== Non-standard operations.
 
 
/**
 * @brief Swap one element out of the container.
 * @param index Index of the element in the container to swap.
 * @param newElement New element to put in the container.
 *                   May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a index of the
 * collection (no bounds checking).  Then element @a index is set
 * to @newElem.  If the collection owns its elements, then it will
 * take ownership of @a newElem and release (without deleting)
 * the element returned through @a oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void DataVector<T, BASE>::swapElement(size_type index,
                                      value_type newElem,
                                      reference oldElem)
{
  testInsert ("swapElement");
  oldElem =
    DataModel_detail::DVLCast<DataVector>::cast(this->m_pCont[index]);
  this->clearIndex (iterator (this->m_pCont.begin() + index, this));
  this->m_pCont[index] = newElem;
  this->moveAux (index, newElem);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param pos The element in the container to swap.
 * @param newElem New element to put in the container.
 *                May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a pos of the
 * collection (no bounds checking).  Then element @a index is set
 * to @c newElem.  If the collection owns its elements, then it will
 * take ownership of @a newElem and release (without deleting)
 * the element returned through @a oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void DataVector<T, BASE>::swapElement(iterator pos,
                                      value_type newElem,
                                      reference oldElem)
{
  testInsert ("swapElement");
  oldElem =
    DataModel_detail::DVLCast<DataVector>::cast(*pos.base());
  this->clearIndex (pos);
  *pos.base() = newElem;
  this->moveAux (pos.base() - this->m_pCont.begin(), newElem);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param index Index of the element in the container to swap.
 * @param newElement New element to put in the container.
 *                   May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a index of the
 * collection (no bounds checking).  Then element @a index is set
 * to @newElem.
 *
 * The collection must own its elements to use its interface.
 * The collection will take ownership of @c newElem and will return
 * ownership of @c oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void DataVector<T, BASE>::swapElement(size_type index,
                                      std::unique_ptr<base_value_type> newElem,
                                      std::unique_ptr<base_value_type>& oldElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("swapElement");
  oldElem = std::unique_ptr<base_value_type>
    (DataModel_detail::DVLCast<DataVector>::cast(this->m_pCont[index]));
  this->clearIndex (iterator (this->m_pCont.begin() + index, this));
  value_type ptr = newElem.release();
  this->m_pCont[index] = ptr;
  this->moveAux (index, ptr);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param pos The element in the container to swap.
 * @param newElem New element to put in the container.
 *                May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a pos of the
 * collection (no bounds checking).  Then element @a index is set
 * to @c newElem.
 *
 * The collection must own its elements to use its interface.
 * The collection will take ownership of @c newElem and will return
 * ownership of @c oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T, class BASE>
void DataVector<T, BASE>::swapElement(iterator pos,
                                      std::unique_ptr<base_value_type> newElem,
                                      std::unique_ptr<base_value_type>& oldElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("swapElement");
  oldElem = std::unique_ptr<base_value_type>
    (DataModel_detail::DVLCast<DataVector>::cast(*pos.base()));
  this->clearIndex (pos);
  value_type ptr = newElem.release();
  *pos.base() = ptr;
  this->moveAux (pos.base() - this->m_pCont.begin(), ptr);
}
 
 
/**
 * @brief Erase all the elements in the collection, and reset
 *        the ownership mode.
 * @param ownPolicy The new ownership policy of the container.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T, class BASE>
void DataVector<T, BASE>::clear (SG::OwnershipPolicy ownPolicy)
{
  this->clear();
  this->m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy,
                                                SG::DEFAULT_TRACK_INDICES);
}
 
 
/**
 * @brief Erase all the elements in the collection, and reset
 *        the ownership mode.
 * @param ownPolicy The new ownership policy of the container.
 * @param trackIndices The index tracking policy.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T, class BASE>
void DataVector<T, BASE>::clear (SG::OwnershipPolicy ownPolicy,
                                 SG::IndexTrackingPolicy trackIndices)
{
  this->clear();
  this->m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
}
 
 
/**
 * @brief Return the DV/DL info struct for this class.
 *
 * This can be used to make sure that it's instantiated.
 */
template <class T, class BASE>
const DataModel_detail::DVLInfoBase& DataVector<T, BASE>::dvlinfo()
{
  static const DataModel_detail::DVLInfo<DataVector<T, BASE> > info;
  return info;
}
 
 
/**
 * @brief Erase all the elements in the collection, and change 
 *        how elements are to be deleted.
 * @param deleter Object to be used to delete object.
 *                Passing nullptr will change back to the default.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 * After the current elements are deleted, the Deleter object is changed.
 */
template <class T, class BASE>
void DataVector<T, BASE>::clear (std::unique_ptr<Deleter> deleter)
{
  this->clear();
  delete this->m_deleter;
  this->m_deleter = deleter.release();
}
 
 
/**
 * @brief Return the DV/DL info struct for this class.
 *
 * This can be used to make sure that it's instantiated.
 */
template <class T, class BASE>
const DataModel_detail::DVLInfoBase& DataVector<T, BASE>::dvlinfo_v() const
{
  return DataVector<T, BASE>::dvlinfo();
}
 
 
/**
 * @brief Return the offset of a base @c DataVector class.
 * @param ti @c std::type_info of the desired class.
 *
 * If @c ti represents a @c DataVector base class of this one,
 * then return the offset of that base class.  Otherwise, return -1.
 *
 * This function is here due to limitations of root 6, which can't
 * calculate these offsets correctly from the dictionary if
 * virtual derivation is used.
 */
template <class T, class BASE>
int DataVector<T, BASE>::baseOffset (const std::type_info& ti)
{
  DataVector dv;
  return baseOffset1 (reinterpret_cast<const char*>(&dv), dv, ti);
}
 
 
/**
 * @brief Convert to @c AuxVectorBase.
 *
 * Needed to get @x AuxVectorBase from a @c ConstDataVector.
 * Present in @c DataVector as well for consistency.
 * We only really need it in the base class; however, root6 fails
 * constructing a @c TMethodCall for this if there is virtual
 * derivation.  A workaround is to redeclare this in the derived
 * classes too.
 */
template <class T, class BASE>
const SG::AuxVectorBase& DataVector<T, BASE>::auxbase() const
{
  return *this;
}
 
 
//=== Internal operations.
 
 
/**
 * @brief Helper for @c baseOffset.
 * @param p Pointer to the start of the top-level object.
 * @param dv Reference to the DataVector object.
 * @param ti @c std::type_info of the desired class.
 *
 * If @c ti represents a @c DataVector base class of this one,
 * then return the offset of that base class.  Otherwise, return -1.
 *
 */
template <class T, class BASE>
int DataVector<T, BASE>::baseOffset1 (const char* p, const DataVector& dv,
                                      const std::type_info& ti)
{
  if (typeid(DataVector) == ti)
    return reinterpret_cast<const char*>(&dv) - p;
  return BASE::baseOffset1 (p, dv, ti);
}
 
 
/**
 * @brief Reset indices / reorder aux data after elements have been permuted.
 * @param beg Start of the range of elements to process.
 * @param end End of the range of elements to process.
 *
 * Call this after some operation that has permuted the elements in the
 * container (such as sort).  The index information in the elements
 * will be used to permute all auxiliary data in the same way.
 * Finally, all the indices will be reset in the correct order.
 */
template <class T, class BASE>
void DataVector<T, BASE>::resortAux (iterator beg, iterator end)
{
  if (typename SG::AuxStore_traits<DataVector>::flag() &&
      beg >= this->begin() && end <= this->end())
  {
    SG::AuxVectorBase::resortAux (beg-begin(), beg, end);
  }
}
 
 
/**
 * @brief Test if we can insert; raise an exception if not.
 * @param op Description of the attempted operation.
 *
 * In order to maintain type-safety, we can only allow insertions
 * using the most-derived instance of @c DataVector.  This checks
 * this by testing the @c m_isMostDerived, which is set by the constructors
 * to true only for the most-derived instance.
 * If the test fails, we call to potentially out-of-line code to continue.
 */
template <class T, class BASE>
inline
void DataVector<T, BASE>::testInsert (const char* op)
{
  if (ATHCONTAINERS_LIKELY (m_isMostDerived))
    return;
  this->testInsertOol (op);
}
 
 
/**
 * @brief Test if we can insert; raise an exception if not.
 * @param op Description of the attempted operation.
 *
 * This continues the test of @c testInsert.  There is one case
 * where @c m_isMostDerived may not be set correctly.  If this container
 * was made via copy construction, then all the @c m_isMostDerived flags
 * will be false.  So we call @c setMostDerived to set the flags correctly
 * and test again.  If the test fails again, then we raise an exception.
 */
template <class T, class BASE>
void DataVector<T, BASE>::testInsertOol (const char* op)
{
  this->setMostDerived();
  if (!m_isMostDerived)
    throw SG::ExcInsertionInBaseClass (op, typeid(DataVector), dv_typeid());
}
 
 
/**
 * @brief Handle element assignment.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The old element is freed if this container owns elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T, class BASE>
void DataVector<T, BASE>::assignElement (typename BaseContainer::iterator pos,
                                         value_type newElem)
{
  testInsert ("assignElement");
  if (this->m_ownPolicy == SG::OWN_ELEMENTS)
    this->doDelete (*pos);
  else
    this->clearIndex (iterator (pos, this));
  *pos = newElem;
  this->moveAux (pos - this->m_pCont.begin(), newElem);
}
 
 
/**
 * @brief Handle element assignment.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The container must own its elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T, class BASE>
void
DataVector<T, BASE>::assignElement (typename BaseContainer::iterator pos,
                                    std::unique_ptr<base_value_type> newElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("assignElement");
  this->doDelete (*pos);
  value_type ptr = newElem.release();
  *pos = ptr;
  this->moveAux (pos - this->m_pCont.begin(), ptr);
}
 
 
/**
 * @brief Handle element assignment from a base pointer.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The old element is freed if this container owns elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T, class BASE>
void
DataVector<T, BASE>::assignBaseElement (typename BaseContainer::iterator pos,
                                        typename BaseContainer::value_type newElem)
{
  testInsert ("assignBaseElement");
  if (this->m_ownPolicy == SG::OWN_ELEMENTS)
    this->doDelete (*pos);
  else
    this->clearIndex (iterator (pos, this));
  *pos = newElem;
  if (typename SG::AuxStore_traits<DataVector>::flag())
    this->moveAux (pos - this->m_pCont.begin(),
                   DataModel_detail::DVLCast<DataVector>::cast(newElem));
}
 
 
/**
 * @brief Shift the auxiliary elements of the container.
 * @param pos The starting index for the shift.
 * @param offs The (signed) amount of the shift.
 *
 * The elements in the container should have already been shifted;
 * this operation will then adjust the element indices and also shift
 * the elements in the vectors for all aux data items.
 * @c offs may be either positive or negative.
 *
 * If @c offs is positive, then the container is growing.
 * The container size should be increased by @c offs,
 * the element at @c pos moved to @c pos + @c offs,
 * and similarly for following elements.
 * The elements between @c pos and @c pos + @c offs should
 * be default-initialized.
 *
 * If @c offs is negative, then the container is shrinking.
 * The element at @c pos should be moved to @c pos + @c offs,
 * and similarly for following elements.
 * The container should then be shrunk by @c -offs elements
 * (running destructors as appropriate).
 */
template <class T, class BASE>
void DataVector<T, BASE>::shift (size_t pos, ptrdiff_t offs)
{
  SG::AuxVectorBase::shift (*this, pos, offs);
}
 
 
/**
 * @brief Helper to shorten calls to @c DataVector_detail::DVLCast.
 * @param p The value to convert.
 * @return The value as a @c const @c T*.
 *
 * The conversion will be done with @c static_cast if possible,
 * with @c dynamic_cast otherwise.
 */
template <class T, class BASE>
inline
const T*
DataVector<T, BASE>::do_cast (const typename PtrVector::value_type p)
{
  return DataModel_detail::DVLCast<DataVector>::cast (p);
}
 
 
/**
 * @brief Helper to shorten calls to @c DataVector_detail::DVLCast.
 * @param p The value to convert.
 * @return The value as a @c T*.
 *
 * The conversion will be done with @c static_cast if possible,
 * with @c dynamic_cast otherwise.
 */
template <class T, class BASE>
inline
T*
DataVector<T, BASE>::do_cast_nc (typename PtrVector::value_type p)
{
  return DataModel_detail::DVLCast<DataVector>::cast (p);
}
 
 
/**
 * @brief Find the most-derived @c DataVector class in the hierarchy.
 * @return The @c type_info for the class for which this method gets run.
 *
 * This is used to generate a nice error message when the most-derived
 * check for insertions fails.
 * Every @c DataVector defines this virtual method, so when it's
 * called, the one corresponding to the most-derived @c DataVector
 * gets run.
 */
template <class T, class BASE>
const std::type_info& DataVector<T, BASE>::dv_typeid() const
{
  return typeid(DataVector);
}
 
 
/**
 * @brief Clear @c m_isMostDerived for this instance and for all bases.
 *
 * Called from the constructor after setting @c m_isMostDerived.
 */
template <class T, class BASE>
inline
void DataVector<T, BASE>::clearMostDerived()
{
  this->m_isMostDerived = false;
  BASE::clearMostDerived();
}
 
 
/**
 * @brief Set @c m_isMostDerived for this instance and clear it for all bases.
 *
 * Called from @c testInsert if the test fails.  The flag may not have
 * been set if this container was made via copy construction, so set
 * it appropriately now so we can test again.
 */
template <class T, class BASE>
void DataVector<T, BASE>::setMostDerived()
{
  m_isMostDerived = true;
  BASE::clearMostDerived();
}
 
 
//****************************************************************************
// Specialized (base) DataVector implementation.
//
 
 
// An abbreviation for the DataVector specialization to try to make
// things a little more readable.
#define DATAVECTOR DataVector<T, DataModel_detail::NoBase>
 
 
//=== Constructors, destructors, assignment.
 
/**
 * @brief Default constructor.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 *
 * By default, a @c DataVector will own its elements.
 * To avoid this, pass @c SG::VIEW_ELEMENTS for @a ownPolicy.
 */
template <class T>
inline
DATAVECTOR::DataVector
  (SG::OwnershipPolicy ownPolicy /*= SG::OWN_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*=SG::DEFAULT_TRACK_INDICES*/)
  : m_ownPolicy(ownPolicy)
{
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
}
 
 
/**
 * @brief Sized constructor.
 * @param n The size of the container.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 *
 * Note that unlike the standard vector constructor, you can't specify
 * an initial value here.  The container will be initialized with 0's.
 *
 * By default, a @c DataVector will own its elements.
 * To avoid this, pass @c SG::VIEW_ELEMENTS for @a ownPolicy.
 */
template <class T>
inline
DATAVECTOR::DataVector
  (size_type n,
   SG::OwnershipPolicy ownPolicy /*= SG::OWN_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_TRACK_INDICES*/)
  : m_ownPolicy(ownPolicy),
    m_pCont (n)
{
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
}
 
 
/**
 * @brief Copy constructor.
 * @param rhs The container from which to copy.
 *
 * This is a `shallow' copy; the new container will not own its elements.
 */
template <class T>
inline
DATAVECTOR::DataVector(const DataVector& rhs)
  : AuxVectorBase(),
    m_ownPolicy(SG::VIEW_ELEMENTS),
    m_pCont(rhs.m_pCont)
{
  this->template initAuxVectorBase<DataVector> (m_ownPolicy,
                                                SG::DEFAULT_TRACK_INDICES);
  // Leave m_isMostDerived false here, because we may be being called
  // from a derived class implicit copy constructor.  The flags will get
  // set correctly when @c testInsert gets called.
}
 
 
/**
 * @brief Move constructor.
 * @param rhs The container from which to move.
 *
 * Any auxiliary data will be moved along with the container contents.
 */
template <class T>
inline
DATAVECTOR::DataVector(DataVector&& rhs) noexcept
  : AuxVectorBase (std::move (rhs)),
    m_ownPolicy(rhs.m_ownPolicy),
    m_pCont(std::move (rhs.m_pCont))
{
  m_deleter = std::move(rhs.m_deleter);
  rhs.m_deleter = nullptr;
 
  // Need to reset the container pointer on elements.
  // Functions called from here can throw GaudiException.
  // However, logically that should not actually happen; so leave this
  // declared as noexcept.
  this->setIndices (this->begin(), this->end());
 
  // This doesn't get called from derived classes.
  // Go ahead and set this flag now.
  m_isMostDerived = true;
}
 
 
/**
 * @brief Constructor from iterators.
 * @param first The start of the range to put in the new container.
 * @param last The end of the range to put in the new container.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 * @param store An associated auxiliary data store.
 *
 * By default, a view container is made, which does not own its elements.
 * To have the container take ownership of the pointers passed
 * to this constructor, pass @c SG::OWN_ELEMENTS for @a ownPolicy.
 */
template <class T>
template <class InputIterator>
inline
DATAVECTOR::DataVector
  (InputIterator first,
   InputIterator last,
   SG::OwnershipPolicy ownPolicy /*= SG::VIEW_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_TRACK_INDICES*/,
   SG::IAuxStore* store /*= 0*/)
  : m_ownPolicy(ownPolicy)
{
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
  this->m_isMostDerived = true;
  if (store)
    this->setStore (store);
  insert (this->begin(), first, last);
}
 
 
/**
 * @brief Constructor from an initializer list.
 * @param l An initializer list.
 * @param last The end of the range to put in the new container.
 * @param ownPolicy The ownership mode for the container.
 * @param trackIndices The index tracking policy.
 * @param store An associated auxiliary data store.
 *
 *
 * A @c DataVector constructed this way will *not* own its elements
 * by default.  To change this, pass @c SG::OWN_ELEMENTS for @a ownPolicy.
 */
template <class T>
inline
DATAVECTOR::DataVector
  (std::initializer_list<value_type> l,
   SG::OwnershipPolicy ownPolicy /*= SG::VIEW_ELEMENTS*/,
   SG::IndexTrackingPolicy trackIndices /*= SG::DEFAULT_TRACK_INDICES*/,
   SG::IAuxStore* store /*= 0*/)
    : DataVector (l.begin(), l.end(), ownPolicy, trackIndices, store)
{
}
 
 
/**
 * @brief Assignment operator.
 * @param rhs The DataVector from which to assign.
 * @return This object.
 *
 * This is a `shallow' copy; after the completion of this, the @c DataVector
 * will not own its elements.  Any elements it owned prior to this call
 * will be released.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
inline
DATAVECTOR& DATAVECTOR::operator= (const DataVector& rhs)
{
  if (&rhs != this) {
    // Ensure we're not being called via a base class.
    // This can throw an exception, so this method should not be noexcept.
    testInsert ("assignment operator");
    clear();                // Release any currently-owned elements.
    m_ownPolicy = SG::VIEW_ELEMENTS;
    this->setStore ((SG::IConstAuxStore*)0);
    this->template initAuxVectorBase<DataVector> (m_ownPolicy,
                                                  SG::DEFAULT_TRACK_INDICES);
    m_pCont = rhs.m_pCont;
  }
  return *this;
}
 
 
/**
 * @brief Move assignment.
 * @param rhs The container from which to move.
 *
 * Any auxiliary data will be moved along with the container contents.
 */
template <class T>
DATAVECTOR& DATAVECTOR::operator= (DATAVECTOR&& rhs)
{
  if (this != &rhs) {
    // Ensure we're not being called via a base class.
    // This can throw an exception, so this method should not be noexcept.
    testInsert ("assignment operator");
 
    this->clear();                // Release any currently-owned elements.
 
    SG::AuxVectorBase::operator= (std::move (rhs));
    this->m_ownPolicy = rhs.m_ownPolicy;
    this->m_pCont = std::move (rhs.m_pCont);
 
    delete this->m_deleter;
    this->m_deleter = std::move(rhs.m_deleter);
    rhs.m_deleter = nullptr;
 
    // Need to reset the container pointer on elements.
    this->setIndices (this->begin(), this->end());
  }
  return *this;
}
 
 
/**
 * @brief Assignment operator, from an initializer list.
 * @param l An initializer list.
 * @return This object.
 *
 * This is equivalent to @c assign.
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T>
inline
DATAVECTOR& DATAVECTOR::operator= (std::initializer_list<value_type> l)
{
  this->assign (l.begin(), l.end());
  return *this;
}
 
 
/**
 * @brief Assign from iterators.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T>
template <class InputIterator>
void DATAVECTOR::assign (InputIterator first,
                         InputIterator last)
{
  // Ensure we're not being called via a base class.
  testInsert ("assign");
  clear();                 // Release any currently-owned elements.
  insert(begin(), first, last);
}
 
 
/**
 * @brief Assign from an initializer list.
 * @param l An initializer list.
 *
 * Any existing owned elements will be released.
 * The @c DataVector's ownership policy determines whether it will take
 * ownership of the new elements.
 */
template <class T>
void DATAVECTOR::assign (std::initializer_list<value_type> l)
{
  this->assign (l.begin(), l.end());
}
 
 
/**
 * @brief Destructor.
 *
 * If this container owns its elements, the contained elements will
 * be deleted as well.  Before doing this, the destructor will scan
 * for duplicate pointers (takes @f$n \log n@f$ time); duplicates are only
 * destroyed once.  Duplicates should, however, be considered an error;
 * don't rely on this behavior.
 */
template <class T>
DATAVECTOR::~DataVector()
{
  if (m_ownPolicy == SG::OWN_ELEMENTS) {
    typename PtrVector::iterator new_end =
      DataVector_detail::remove_duplicates(m_pCont.begin(), m_pCont.end());
    this->doDelete (m_pCont.begin(), new_end);
  }
  delete m_deleter;
}
 
 
//=== Size and capacity.
 
 
/**
 * @brief Returns the number of elements in the collection.
 */
template <class T>
inline
typename DATAVECTOR::size_type DATAVECTOR::size() const noexcept
{
  return m_pCont.size();
}
 
 
/**
 * @brief Returns the number of elements in the collection.
 *
 *        This version is virtual, to be callable from the AuxData
 *        base class.
 */
template <class T>
inline
typename DATAVECTOR::size_type DATAVECTOR::size_v() const
{
  return this->size();
}
 
 
/**
 * @brief Returns the @c size() of the largest possible collection.
 */
template <class T>
inline
typename DATAVECTOR::size_type DATAVECTOR::max_size() const noexcept
{
  return m_pCont.max_size();
}
 
 
/**
 * @brief Resizes the collection to the specified number of elements.
 * @param sz The new size of the collection.
 *
 * Note that this function differs from the standard in that it does
 * not allow specifying the value of any inserted elements.
 * They will always be 0.
 *
 * If the container is shrunk, elements will be deleted as with @c erase().
 */
template <class T>
void DATAVECTOR::resize(size_type sz)
{ 
  if (sz < this->size()) {
    this->erase (this->begin()+sz, this->end());
  } else {
    this->m_pCont.insert(this->m_pCont.end(), sz - this->m_pCont.size(), 0);
    SG::AuxVectorBase::resize<DataVector> (sz);
  }
} 
 
 
/**
 * @brief Returns the total number of elements that the collection can hold
 *        before needing to allocate more memory.
 */
template <class T>
inline
typename DATAVECTOR::size_type DATAVECTOR::capacity() const noexcept
{
  return m_pCont.capacity();
}
 
 
/**
 * @brief Returns the total number of elements that the collection can hold
 *        before needing to allocate more memory.
 *
 *        This version is virtual, to be callable from the AuxData
 *        base class.
 */
template <class T>
inline
typename DATAVECTOR::size_type DATAVECTOR::capacity_v() const
{
  return capacity();
}
 
 
/**
 * @brief Returns @c true if the collection is empty.
 */
template <class T>
inline
bool DATAVECTOR::empty() const noexcept
{
  return m_pCont.empty();
}
 
 
/**
 * @brief Attempt to preallocate enough memory for a specified number
 *        of elements.
 * @param n Number of elements required.
 */
template <class T>
inline
void DATAVECTOR::reserve (size_type n)
{
  m_pCont.reserve (n);
  SG::AuxVectorBase::reserve<DataVector> (n);
}
 
 
/**
 * @brief Change the vector capacity to match the current size.
 *
 * Note: this does not affect auxiliary data.
 */
template <class T>
inline
void DATAVECTOR::shrink_to_fit()
{
  m_pCont.shrink_to_fit();
}
 
 
//=== Element access.
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 *
 * No bounds checking is done.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T>
inline
const T* DATAVECTOR::operator[] (size_type n) const
{
  return m_pCont[n];
}
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 * 
 * This is a synonym for operator[] const, to be used when calling from root
 * (where we can't readily call just the const version of a method).
 */
template <class T>
inline
const T* DATAVECTOR::get (size_type n) const
{
  return do_cast(this->m_pCont[n]);
}
 
 
/**
 * @brief Access an element, as an lvalue.
 * @param n Array index to access.
 * @return Proxy to the element at @a n.
 *
 * No bounds checking is done.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::ElementProxy DATAVECTOR::operator[] (size_type n)
{
  return ElementProxy (m_pCont.begin() + n, this);
}
 
 
/**
 * @brief Access an element, as an rvalue.
 * @param n Array index to access.
 * @return The element at @a n.
 *
 * Will raise @c std::out_of_range if the index is out-of-bounds.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T>
inline
const T* DATAVECTOR::at (size_type n) const
{
  return m_pCont.at(n);
}
 
 
/**
 * @brief Access an element, as an lvalue.
 * @param n Array index to access.
 * @return Proxy to the element at @a n.
 *
 * Will raise @c std::out_of_range if the index is out-of-bounds.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::ElementProxy DATAVECTOR::at (size_type n)
{
  // Can't use m_pCont's at here, because we need an iterator.
  // So we have to do the bounds check ourselves.
  if (n >= size())
    CxxUtils::throw_out_of_range (__PRETTY_FUNCTION__, n, this->size(), this);
  return ElementProxy (m_pCont.begin() + n, this);
}
 
 
/**
 * @brief Access the first element in the collection as an rvalue.
 * @return The first element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T>
inline
const T* DATAVECTOR::front() const
{
  return m_pCont.front();
}
 
 
/**
 * @brief Access the last element in the collection as an rvalue.
 * @return The last element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a @c const @c T* rather than a reference.
 */
template <class T>
inline
const T* DATAVECTOR::back() const
{
  return m_pCont.back();
}
 
 
/**
 * @brief Access the first element in the collection as an lvalue.
 * @return Proxy to the first element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::ElementProxy DATAVECTOR::front ()
{
  return ElementProxy (m_pCont.begin(), this);
}
 
 
/**
 * @brief Access the last element in the collection as an lvalue.
 * @return Proxy to the last element in the collection.
 *
 * No checking is done to ensure that the container is not empty.
 * Note that we return a proxy object rather than a reference;
 * the proxy will handle deleting an owned element if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::ElementProxy DATAVECTOR::back ()
{
  return ElementProxy (m_pCont.end()-1, this);
}
 
 
//=== Iterator creation.
 
 
/**
 * @brief Return a @c const_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_iterator DATAVECTOR::begin() const noexcept
{
  return m_pCont.begin();
}
 
 
/**
 * @brief Return a @c const_iterator pointing past the end
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_iterator DATAVECTOR::end() const noexcept
{
  return m_pCont.end();
}
 
 
/**
 * @brief Return an @c iterator pointing at the beginning
 *        of the collection.
 * @return An @c iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::iterator DATAVECTOR::begin() noexcept
{
  return iterator (m_pCont.begin(), this);
}
 
 
/**
 * @brief Return an @c iterator pointing past the end
 *        of the collection.
 * @return An @c iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::iterator DATAVECTOR::end() noexcept
{
  return iterator (m_pCont.end(), this);
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_reverse_iterator DATAVECTOR::rbegin() const noexcept
{
  return const_reverse_iterator (m_pCont.end());
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_reverse_iterator DATAVECTOR::rend() const noexcept
{
  return const_reverse_iterator (const_iterator (m_pCont.begin()));
}
 
 
/**
 * @brief Return a @c reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::reverse_iterator DATAVECTOR::rbegin() noexcept
{
  return reverse_iterator(iterator (m_pCont.end(), this));
}
 
 
/**
 * @brief Return a @c reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a proxy rather
 * than a reference; the proxy will handle deleting an owned element
 * if it's assigned to.
 */
template <class T>
inline
typename DATAVECTOR::reverse_iterator DATAVECTOR::rend() noexcept
{
  return reverse_iterator(iterator (m_pCont.begin(), this));
}
 
 
/**
 * @brief Return a @c const_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_iterator DATAVECTOR::cbegin() const noexcept
{
  return m_pCont.begin();
}
 
 
/**
 * @brief Return a @c const_iterator pointing past the end
 *        of the collection.
 * @return A @c const_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_iterator DATAVECTOR::cend() const noexcept
{
  return m_pCont.end();
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing past the end
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_reverse_iterator DATAVECTOR::crbegin() const noexcept
{
  return const_reverse_iterator (m_pCont.end());
}
 
 
/**
 * @brief Return a @c const_reverse_iterator pointing at the beginning
 *        of the collection.
 * @return A @c const_reverse_iterator.
 *
 * Note that dereferencing the iterator will yield a @c const @c T* rather
 * than a reference.
 */
template <class T>
inline
typename DATAVECTOR::const_reverse_iterator DATAVECTOR::crend() const noexcept
{
  return const_reverse_iterator (const_iterator (m_pCont.begin()));
}
 
 
//=== Insertion operations.
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the pushed pointer.
 */
template <class T>
inline
typename DATAVECTOR::value_type
DATAVECTOR::push_back(value_type pElem)
{
  // Ensure we're not being called via a base class.
  testInsert ("push_back");
  m_pCont.push_back(pElem);
  SG::AuxVectorBase::resize<DataVector> (this->size());
  if (pElem && this->trackIndices())
    this->moveAuxNoClear (this->size()-1, pElem);
  return pElem;
}
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container must be an owning container.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the pushed pointer.
 */
template <class T>
inline
typename DATAVECTOR::value_type
DATAVECTOR::push_back(std::unique_ptr<base_value_type> pElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  // Ensure we're not being called via a base class.
  testInsert ("push_back");
  value_type ptr = pElem.release();
  m_pCont.push_back(ptr);
  SG::AuxVectorBase::resize<DataVector> (this->size());
  if (ptr && this->trackIndices())
    this->moveAuxNoClear (this->size()-1, ptr);
  return ptr;
}
 
 
/**
 * @brief Create and add a number of new elements to the end of the container.
 * @param n The number of new elements to add.
 * @param alloc Functional to call to allocate a new element to push.
 *              Should be callable like <code>T* = alloc();</code>
 *              For example:
 *@code
 *                dv.push_new (n, [](){ return new Foo; });
 @endcode
 *              It may also be useful to allocate from a @c DataPool.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * Returns the original size of the vector.
 */
template <class T>
template <CxxUtils::detail::AllocationFunction<T> F>
auto
DATAVECTOR::push_new(size_type n, F alloc) -> size_type
{
  // Ensure we're not being called via a base class.
  testInsert ("push_new");
  bool trackIndices = this->trackIndices();
 
  size_t sz = this->m_pCont.size();
  this->m_pCont.resize (sz + n);
  SG::AuxVectorBase::resize<DataVector> (this->size());
  for (size_t i = 0; i < n; i++) {
    T* p = alloc();
    if (!p) std::abort();
    this->m_pCont[sz+i] = p;
    if (trackIndices) {
      this->moveAuxNoClear (sz+i, p);
    }
  }
  return sz;
}
 
 
/**
 * @brief Add an element to the end of the collection.
 * @param pElem The element to add to the collection.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * For @c DataVector, this is like the same as @c push_back, and
 * it returns the pushed element.
 * It's included just for interface compatibility with `std::vector`.
 */
template <class T>
inline
typename DATAVECTOR::value_type
DATAVECTOR::emplace_back(value_type pElem)
{
  return this->push_back (pElem);
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
inline
typename DATAVECTOR::iterator
DATAVECTOR::insert(iterator position, value_type pElem)
{
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  iterator ret (m_pCont.insert(position.base(), pElem), this);
  this->shift (ret - this->begin(), 1);
  if (this->trackIndices())
    this->moveAuxNoClear (ret-this->begin(), pElem);
  return ret;
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container must be an owning container.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
inline
typename DATAVECTOR::iterator
DATAVECTOR::insert(iterator position, std::unique_ptr<base_value_type> pElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  value_type ptr = pElem.release();
  iterator ret (m_pCont.insert(position.base(), ptr), this);
  this->shift (ret - this->begin(), 1);
  if (this->trackIndices())
    this->moveAuxNoClear (ret-this->begin(), ptr);
  return ret;
}
 
 
/**
 * @brief Add a new element to the collection.
 * @param position Iterator before which the element will be added.
 * @param pElem The element to add to the collection.
 * @return An iterator that points to the inserted data.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * For @c DataVector, this is just the same as @c insert.
 * It's included just for interface compatibility with `std::vector`.
 */
template <class T>
inline
typename DATAVECTOR::iterator
DATAVECTOR::emplace(iterator position, value_type pElem)
{
  return this->insert (position, pElem);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * This overload is for the case where the iterator value type
 * is convertible to T*.
 */
template <class T>
template <class InputIterator,
          DataVector_detail::enable_if_ptr_itr<InputIterator, T> >
inline
void
DATAVECTOR::insert (iterator position, InputIterator first, InputIterator last)
{
  static_assert (std::is_same_v<T*, typename DATAVECTOR::value_type>);
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  size_t idx = position - this->begin();
  size_t old_sz = this->m_pCont.size();
  m_pCont.insert(position.base(), first, last);
  size_t n = this->m_pCont.size() - old_sz;
  this->shift (idx, n);
  this->moveAux (idx, first, last, false, true);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param first The start of the range to put in the container.
 * @param last The end of the range to put in the container.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 *
 * This overload is for the case where the iterator value type
 * is convertible to unique_ptr<T>.
 */
template <class T>
template <class InputIterator,
          DataVector_detail::enable_if_up_itr<InputIterator, T> >
inline
void
DATAVECTOR::insert (iterator position, InputIterator first, InputIterator last)
{
  // Ensure we're not being called via a base class.
  testInsert ("insert");
  size_t idx = position - this->begin();
  size_t old_sz = this->m_pCont.size();
  using CxxUtils::releasing_iterator;
  m_pCont.insert(position.base(), releasing_iterator(first), releasing_iterator(last));
  size_t n = this->m_pCont.size() - old_sz;
  this->shift (idx, n);
  this->moveAux (idx, this->begin()+idx, this->begin()+idx+n);
}
 
 
/**
 * @brief Add a group of new elements to the collection.
 * @param position Iterator before which the element will be added.
 * @param l An initializer list.
 *
 * The container's ownership policy will determine if it takes ownership
 * of the new element.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
inline
void
DATAVECTOR::insert (iterator position, std::initializer_list<value_type> l)
{
  this->insert (position, l.begin(), l.end());
}
 
 
/**
 * @brief Insert the contents of another @c DataVector,
 *        with auxiliary data copied via move semantics.
 * @param position Iterator before which the new elements will be added.
 * @param other The vector to add.
 *
 * The ownership mode of this vector must be the same as @c other;
 * otherwise, an exception will be thrown.
 *
 * If both vectors are view vectors, then this is the same
 * as <code> insert (position, other.begin(), other.end()) </code>.
 *
 * Otherwise, the elements from @c other will be inserted into this vector.
 * This vector will take ownership of the elements, and the ownership
 * mode of @c other will be changed to @c VIEW_ELEMENTS.
 * Auxiliary data for these elements will be transferred,
 * using move semantics if possible.  (Thus, the auxiliary store
 * for @c other may be modified and must not be locked.)
 * Finally, the auxiliary store pointer for @c other will be cleared
 * (but the store itself will not be deleted since it's not owned
 * by the vector).
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
void
DATAVECTOR::insertMove (iterator position, DataVector& other)
{
  if (this->m_ownPolicy != other.ownPolicy())
    throw SG::ExcInsertMoveOwnershipMismatch();
 
  if (this->m_ownPolicy == SG::VIEW_ELEMENTS) {
    this->insert (position, other.begin(), other.end());
    return;
  }
 
  testInsert ("insertMove");
  size_t pos = position.base() - this->m_pCont.begin();
  this->m_pCont.insert (position.base(), other.begin(), other.end());
  this->setIndices (this->begin()+pos, this->end(), pos);
  other.m_ownPolicy = SG::VIEW_ELEMENTS;
 
  SG::IAuxStore* otherStore = other.getStore();
  if (otherStore) {
    SG::IAuxStore* store = this->getStore();
    if (store) {
      if (!store->insertMove (pos, *otherStore))
        this->clearCache();
    }
    else if (this->hasStore())
      throw SG::ExcConstAuxData ("insertMove");
    other.setStore (static_cast<SG::IAuxStore*>(nullptr));
  }
  else if (other.hasStore())
    throw SG::ExcConstAuxData ("insertMove");
}
 
 
//=== Erasure operations.
 
 
/**
 * @brief Remove element at a given position.
 * @param position Iterator pointing to the element to be removed.
 * @return An iterator pointing to the next element (or @c end()).
 *
 * If the container owns its elements, then the pointed-to element
 * will be deleted.
 */
template <class T>
inline
typename DATAVECTOR::iterator DATAVECTOR::erase(iterator position)
{ 
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndex (position);
  iterator ret (this->erase_base (position.base()), this);
  this->shift (ret - this->begin() + 1, -1);
  return ret;
}
 
 
/**
 * @brief Remove a range of elements.
 * @param first Iterator pointing to the first element to be removed.
 * @param last Iterator pointing one past the last element to be removed.
 * @return An iterator pointing to the element pointed to by @a last
 *         prior to erasing (or @c end()).
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T>
inline
typename DATAVECTOR::iterator DATAVECTOR::erase(iterator first, iterator last)
{
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndices (first, last);
  iterator ret (this->erase_base (first.base(), last.base()), this);
  this->shift (ret - this->begin() + (last-first), -(last-first));
  return ret;
}
 
 
/**
 * @brief Remove the last element from the collection.
 *
 * If the container owns its elements, then the removed element
 * will be deleted.
 */
template <class T>
void DATAVECTOR::pop_back()
{
  if (!m_pCont.empty()) {
    if (m_ownPolicy == SG::OWN_ELEMENTS)
      this->doDelete (m_pCont.back());
    else
      this->clearIndex (m_pCont.end() - 1);
    m_pCont.pop_back();
    SG::AuxVectorBase::resize<DataVector> (this->m_pCont.size());
  }
}
 
 
/**
 * @brief Erase all the elements in the collection.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T>
inline
void DATAVECTOR::clear()
{
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    this->clearIndices (begin(), end());
  this->erase_base (m_pCont.begin(), m_pCont.end());
  SG::AuxVectorBase::resize<DataVector> (0);
}
 
 
//=== Swap and sort.
 
 
/**
 * @brief Swap this collection with another.
 * @param rhs The collection with which to swap.
 *
 * Ownership is swapped along with the collection content.
 *
 * Note: this method may only be called using the most-derived
 * @c DataVector in the hierarchy.  The @a rhs must also be
 * referenced using the most-derived @c DataVector.
 *
 * Warning: If this container has auxiliary data, then this
 * is an O(N) operation, not O(1).
 */
template <class T>
void DATAVECTOR::swap(DataVector& rhs)
{
  testInsert ("swap");
  rhs.testInsert ("swap");
  std::swap(m_ownPolicy, rhs.m_ownPolicy);
  SG::AuxVectorBase::swap (rhs);
  m_pCont.swap(rhs.m_pCont);
  std::swap (this->m_deleter, rhs.m_deleter);
  this->setIndices (this->begin(), this->end());
  rhs.setIndices (rhs.begin(), rhs.end());
}
 
 
/**
 * @brief Swap the referents of two @c DataVector iterators.
 * @param a The first iterator for the swap.
 * @param b The second iterator for the swap.
 */
template <class T>
void DATAVECTOR::iter_swap (iterator a, iterator b)
{
  if (a.ownPolicy() != b.ownPolicy()) {
    throw SG::ExcBadIterSwap();
  }
  a.testInsert ("iter_swap");
  b.testInsert ("iter_swap");
  std::iter_swap (a.base(), b.base());
  DataVector* acont = a.container();
  DataVector* bcont = b.container();
  if (typename SG::AuxStore_traits<DataVector>::flag())
    acont->swapElementsAux (a.base() - acont->stdcont().begin(),
                            b.base() - bcont->stdcont().begin(),
                            *a.base(),
                            *b.base(),
                            bcont);
}
 
 
/**
 * @brief Sort the container.
 *
 * This just sorts by pointer value, so it's probably not very useful.
 */
template <class T>
void DATAVECTOR::sort()
{
  std::sort(m_pCont.begin(), m_pCont.end());
  this->resortAux (this->begin(), this->end());
}
 
 
/**
 * @brief Sort the container with a user-specified comparison operator.
 * @param comp Functional to compare two values.
 */
template <class T>
template <class COMPARE>
void DATAVECTOR::sort(COMPARE comp)
{
  std::sort(m_pCont.begin(), m_pCont.end(), comp);
  this->resortAux (this->begin(), this->end());
}
 
 
//=== Non-standard operations.
 
 
/**
 * @brief Swap one element out of the container.
 * @param index Index of the element in the container to swap.
 * @param newElement New element to put in the container.
 *                   May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a index of the
 * collection (no bounds checking).  Then element @a index is set
 * to @newElem.  If the collection owns its elements, then it will
 * take ownership of @a newElem and release (without deleting)
 * the element returned through @a oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
void
DATAVECTOR::swapElement (size_type index,
                         value_type newElem,
                         reference oldElem)
{
  testInsert ("swapElement");
  oldElem = m_pCont[index];
  this->clearIndex (iterator (m_pCont.begin() + index, this));
  m_pCont[index] = newElem;
  this->moveAux (index, newElem);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param pos The element in the container to swap.
 * @param newElem New element to put in the container.
 *                May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a pos of the
 * collection (no bounds checking).  Then element @a index is set
 * to @c newElem.  If the collection owns its elements, then it will
 * take ownership of @a newElem and release (without deleting)
 * the element returned through @a oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
void
DATAVECTOR::swapElement (iterator pos,
                         value_type newElem,
                         reference oldElem)
{
  testInsert ("swapElement");
  oldElem = *pos.base();
  this->clearIndex (pos);
  *pos.base() = newElem;
  this->moveAux (pos.base() - this->m_pCont.begin(), newElem);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param index Index of the element in the container to swap.
 * @param newElement New element to put in the container.
 *                   May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a index of the
 * collection (no bounds checking).  Then element @a index is set
 * to @newElem.
 *
 * The collection must own its elements to use its interface.
 * The collection will take ownership of @c newElem and will return
 * ownership of @c oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
void
DATAVECTOR::swapElement (size_type index,
                         std::unique_ptr<base_value_type> newElem,
                         std::unique_ptr<base_value_type>& oldElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("swapElement");
  oldElem = std::unique_ptr<base_value_type> (m_pCont[index]);
  this->clearIndex (iterator (m_pCont.begin() + index, this));
  value_type ptr = newElem.release();
  m_pCont[index] = ptr;
  this->moveAux (index, ptr);
}
 
 
/**
 * @brief Swap one element out of the container.
 * @param pos The element in the container to swap.
 * @param newElem New element to put in the container.
 *                May be 0.
 * @param oldElem Reference to receive the element removed from the
 *                container.
 *
 * Reference @a oldElem is initialized with element @a pos of the
 * collection (no bounds checking).  Then element @a index is set
 * to @c newElem.
 *
 * The collection must own its elements to use its interface.
 * The collection will take ownership of @c newElem and will return
 * ownership of @c oldElem.
 *
 * Note: this method may only be called using the most derived
 * @c DataVector in the hierarchy.
 */
template <class T>
void
DATAVECTOR::swapElement (iterator pos,
                         std::unique_ptr<base_value_type> newElem,
                         std::unique_ptr<base_value_type>& oldElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("swapElement");
  oldElem = std::unique_ptr<base_value_type> (*pos.base());
  this->clearIndex (pos);
  value_type ptr = newElem.release();
  *pos.base() = ptr;
  this->moveAux (pos.base() - this->m_pCont.begin(), ptr);
}
 
 
/**
 * @brief Return the underlying @c std::vector of the container.
 * @return Reference to the @c std::vector actually holding the collection.
 *
 * Note that @c DataVector<T>::stdcont does not necessarily return
 * a @c std::vector<T*> if @c DataVector inheritance is being used.
 */
template <class T>
inline
const typename DATAVECTOR::PtrVector& DATAVECTOR::stdcont() const
{
  return m_pCont;
}
 
 
/**
 * @brief Return the ownership policy setting for this container.
 */
template <class T>
inline
SG::OwnershipPolicy DATAVECTOR::ownPolicy() const
{
  return m_ownPolicy;
}
 
 
/**
 * @brief Erase all the elements in the collection, and reset
 *        the ownership mode.
 * @param ownPolicy The new ownership policy of the container.
 * @param trackIndices The index tracking policy.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T>
void DATAVECTOR::clear (SG::OwnershipPolicy ownPolicy)
{
  clear();
  m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy,
                                                SG::DEFAULT_TRACK_INDICES);
}
 
 
/**
 * @brief Erase all the elements in the collection, and reset
 *        the ownership mode.
 * @param ownPolicy The new ownership policy of the container.
 * @param trackIndices The index tracking policy.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 */
template <class T>
void DATAVECTOR::clear (SG::OwnershipPolicy ownPolicy,
                        SG::IndexTrackingPolicy trackIndices)
{
  clear();
  m_ownPolicy = ownPolicy;
  this->template initAuxVectorBase<DataVector> (ownPolicy, trackIndices);
}
 
 
/**
 * @brief Return the DV/DL info struct for this class.
 *
 * This can be used to make sure that it's instantiated.
 */
template <class T>
const DataModel_detail::DVLInfoBase& DATAVECTOR::dvlinfo()
{
  static const DataModel_detail::DVLInfo<DataVector<T, DataModel_detail::NoBase> > info;
  return info;
}
 
 
/**
 * @brief Erase all the elements in the collection, and change 
 *        how elements are to be deleted.
 * @param deleter Object to be used to delete object.
 *                (The DataVector does not take ownership.)
 *                Passing nullptr will change back to the default.
 *
 * If the container owns its elements, then the removed elements
 * will be deleted.  Any duplicates will be removed in this process,
 * but don't rely on this.
 * After the current elements are deleted, the Deleter object is changed.
 */
template <class T>
void DATAVECTOR::clear (std::unique_ptr<Deleter> deleter)
{
  this->clear();
  delete this->m_deleter;
  this->m_deleter = deleter.release();
}
 
 
/**
 * @brief Return the DV/DL info struct for this class.
 *
 * This can be used to make sure that it's instantiated.
 */
template <class T>
const DataModel_detail::DVLInfoBase& DATAVECTOR::dvlinfo_v() const
{
  return DATAVECTOR::dvlinfo();
}
 
 
/**
 * @brief Return the offset of a base @c DataVector class.
 * @param ti @c std::type_info of the desired class.
 *
 * If @c ti represents a @c DataVector base class of this one,
 * then return the offset of that base class.  Otherwise, return -1.
 *
 * This function is here due to limitations of root 6, which can't
 * calculate these offsets correctly from the dictionary if
 * virtual derivation is used.
 */
template <class T>
int DATAVECTOR::baseOffset (const std::type_info& ti)
{
  if (typeid(DataVector) == ti)
    return 0;
  return -1;
}
 
 
/**
 * @brief Convert to @c AuxVectorBase.
 *
 * Needed to get @x AuxVectorBase from a @c ConstDataVector.
 * Present in @c DataVector as well for consistency.
 */
template <class T>
inline
const SG::AuxVectorBase& DATAVECTOR::auxbase() const
{
  return *this;
}
 
 
//=== Internal operations.
 
 
/**
 * @brief Helper for @c baseOffset.
 * @param p Pointer to the start of the top-level object.
 * @param dv Reference to the DataVector object.
 * @param ti @c std::type_info of the desired class.
 *
 * If @c ti represents a @c DataVector base class of this one,
 * then return the offset of that base class.  Otherwise, return -1.
 *
 */
template <class T>
int DATAVECTOR::baseOffset1 (const char* p, const DataVector& dv,
                             const std::type_info& ti)
{
  if (typeid(DataVector) == ti)
    return reinterpret_cast<const char*>(&dv) - p;
  return -1;
}
 
 
/**
 * @brief Reset indices / reorder aux data after elements have been permuted.
 * @param beg Start of the range of elements to process.
 * @param end End of the range of elements to process.
 *
 * Call this after some operation that has permuted the elements in the
 * container (such as sort).  The index information in the elements
 * will be used to permute all auxiliary data in the same way.
 * Finally, all the indices will be reset in the correct order.
 */
template <class T>
void DATAVECTOR::resortAux (iterator beg, iterator end)
{
  if (typename SG::AuxStore_traits<DataVector>::flag() &&
      beg >= this->begin() && end <= this->end())
  {
    SG::AuxVectorBase::resortAux (beg-begin(), beg, end);
  }
}
 
 
/**
 * @brief Handle element assignment.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The old element is freed if this container owns elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T>
void DATAVECTOR::assignElement (typename BaseContainer::iterator pos,
                                value_type newElem)
{
  testInsert ("assignElement");
  if (this->m_ownPolicy == SG::OWN_ELEMENTS)
    this->doDelete (*pos);
  else
    this->clearIndex (iterator (pos, this));
  *pos = newElem;
  this->moveAux (pos - this->m_pCont.begin(), newElem);
}
 
 
/**
 * @brief Handle element assignment.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The container must own its elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T>
void
DATAVECTOR::assignElement (typename BaseContainer::iterator pos,
                           std::unique_ptr<base_value_type> newElem)
{
  // Container must own its elements.
  if (this->m_ownPolicy != SG::OWN_ELEMENTS)
    SG::throwExcNonowningContainer();
 
  testInsert ("assignElement");
  this->doDelete (*pos);
  value_type ptr = newElem.release();
  *pos = ptr;
  this->moveAux (pos - this->m_pCont.begin(), ptr);
}
 
 
/**
 * @brief Handle element assignment from a base pointer.
 * @param pos Position in the container to assign.
 * @param newElem The new element to assign.
 *
 * The old element is freed if this container owns elements.
 * Auxiliary data are copied if appropriate.
 */
template <class T>
void DATAVECTOR::assignBaseElement (typename BaseContainer::iterator pos,
                                    typename BaseContainer::value_type newElem)
{
  testInsert ("assignBaseElement");
  if (this->m_ownPolicy == SG::OWN_ELEMENTS)
    this->doDelete (*pos);
  else
    this->clearIndex (iterator (pos, this));
  *pos = newElem;
  if (typename SG::AuxStore_traits<DataVector>::flag())
    this->moveAux (pos - this->m_pCont.begin(), newElem);
}
 
 
/**
 * @brief Shift the auxiliary elements of the container.
 * @param pos The starting index for the shift.
 * @param offs The (signed) amount of the shift.
 *
 * The elements in the container should have already been shifted;
 * this operation will then adjust the element indices and also shift
 * the elements in the vectors for all aux data items.
 * @c offs may be either positive or negative.
 *
 * If @c offs is positive, then the container is growing.
 * The container size should be increased by @c offs,
 * the element at @c pos moved to @c pos + @c offs,
 * and similarly for following elements.
 * The elements between @c pos and @c pos + @c offs should
 * be default-initialized.
 *
 * If @c offs is negative, then the container is shrinking.
 * The element at @c pos should be moved to @c pos + @c offs,
 * and similarly for following elements.
 * The container should then be shrunk by @c -offs elements
 * (running destructors as appropriate).
 */
template <class T>
void DATAVECTOR::shift (size_t pos, ptrdiff_t offs)
{
  SG::AuxVectorBase::shift (*this, pos, offs);
}
 
 
/**
 * @brief Helper to shorten calls to @c DataModel_detail::DVLCast.
 * @param p The value to convert.
 * @return The value as a @c const @c T*.
 *
 * This is a no-op for the base class.
 */
template <class T>
inline
const T* DATAVECTOR::do_cast (const typename PtrVector::value_type p)
{
  return p;
}
 
 
/**
 * @brief Helper to shorten calls to @c DataModel_detail::DVLCast.
 * @param p The value to convert.
 * @return The value as a @c T*.
 *
 * This is a no-op for the base class.
 */
template <class T>
inline
T* DATAVECTOR::do_cast_nc (typename PtrVector::value_type p)
{
  return p;
}
 
 
/**
 * @brief Find the most-derived @c DataVector class in the hierarchy.
 * @return The @c type_info for the class for which this method gets run.
 *
 * This is used to generate a nice error message when the most-derived
 * check for insertions fails.
 * Every @c DataVector defines this virtual method, so when it's
 * called, the one corresponding to the most-derived @c DataVector
 * gets run.
 */
template <class T>
const std::type_info& DATAVECTOR::dv_typeid() const
{
  return typeid(DataVector);
}
 
 
/**
 * @brief Helper for @c erase().  Remove element at a given position.
 * @param position Iterator pointing to the element to be removed.
 * @return An iterator pointing to the next element (or @c end()).
 *
 * This function factors out common code between @c erase() in the
 * base and derived @c DataVector classes.  It deals with the
 * @c std::vector iterators directly.
 */
template <class T>
typename DATAVECTOR::PtrVector::iterator
DATAVECTOR::erase_base(typename PtrVector::iterator position)
{ 
  if (m_ownPolicy == SG::OWN_ELEMENTS && position != m_pCont.end())
    this->doDelete (*position);
  return m_pCont.erase(position);
}
 
 
/**
 * @brief Helper for @c erase().  Remove a range of elements.
 * @param first Iterator pointing to the first element to be removed.
 * @param last Iterator pointing one past the last element to be removed.
 * @return An iterator pointing to the element pointed to by @a last
 *         prior to erasing (or @c end()).
 *
 * This function factors out common code between @c erase() in the
 * base and derived @c DataVector classes.  It deals with the
 * @c std::vector iterators directly.
 */
template <class T>
typename DATAVECTOR::PtrVector::iterator
DATAVECTOR::erase_base(typename PtrVector::iterator first,
                       typename PtrVector::iterator last)
{
  if (first == last) return first;
  if (m_ownPolicy == SG::OWN_ELEMENTS) {
    typename PtrVector::iterator new_end =
      DataVector_detail::remove_duplicates(first, last);
    this->doDelete (first, new_end);
  }
  return m_pCont.erase(first, last);
}
 
 
/**
 * @brief Delete an element
 * @param p The element to delete.
 */
template <class T>
inline
void DATAVECTOR::doDelete (value_type p)
{
  if (m_deleter) {
    m_deleter->doDelete (p);
  }
  else {
    delete p;
  }
}
 
 
/**
 * @brief Delete a range of elements
 * @param first Start of range to delete.
 * @param last End of range to delete.
 */
template <class T>
inline
void DATAVECTOR::doDelete (typename PtrVector::iterator first,
                           typename PtrVector::iterator last)
{
  if (m_deleter) {
    m_deleter->doDelete (first, last);
  }
  else {
    for (; first != last; ++first) {
      delete *first;
    }
  }
}
 
 
/**
 * @brief Test if we can insert; raise an exception if not.
 * @param op Description of the attempted operation.
 *
 * In order to maintain type-safety, we can only allow insertions
 * using the most-derived instance of @c DataVector.  This checks
 * this by testing the @c m_isMostDerived, which is set by the constructors
 * to true only for the most-derived instance.
 * If the test fails, we call to potentially out-of-line code to continue.
 */
template <class T>
inline
void DATAVECTOR::testInsert (const char* op)
{
  if (ATHCONTAINERS_LIKELY (m_isMostDerived))
    return;
  this->testInsertOol (op);
}
 
 
/**
 * @brief Test if we can insert; raise an exception if not.
 * @param op Description of the attempted operation.
 *
 * This continues the test of @c testInsert.  There is one case
 * where @c m_isMostDerived may not be set correctly.  If this container
 * was made via copy construction, then all the @c m_isMostDerived flags
 * will be false.  So we call @c setMostDerived to set the flags correctly
 * and test again.  If the test fails again, then we raise an exception.
 */
template <class T>
void DATAVECTOR::testInsertOol (const char* op)
{
  this->setMostDerived();
  if (!m_isMostDerived)
    throw SG::ExcInsertionInBaseClass (op, typeid(DataVector), dv_typeid());
}
 
 
/**
 * @brief Clear @c m_isMostDerived for this instance and for all bases.
 *
 * Called from the constructor after setting @c m_isMostDerived.
 */
template <class T>
inline
void DATAVECTOR::clearMostDerived()
{
  this->m_isMostDerived = false;
}
 
 
/**
 * @brief Set @c m_isMostDerived for this instance and clear it for all bases.
 *
 * Called from @c testInsert if the test fails.  The flag may not have
 * been set if this container was made via copy construction, so set
 * it appropriately now so we can test again.
 */
template <class T>
void DATAVECTOR::setMostDerived()
{
  m_isMostDerived = true;
}
 
 
#undef DATAVECTOR
 
 
//****************************************************************************
// Free function implementations.
//
 
 
/**
 * @brief  Vector equality comparison.
 * @param  a  A @c DataVector.
 * @param  b  A @c DataVector of the same type as @a b.
 * @return  True iff the size and elements of the vectors are equal.
 *
 * This is an equivalence relation.  It is linear in the size of the
 * vectors.  Vectors are considered equivalent if their sizes are equal,
 * and if corresponding elements compare equal.
 */
template <class T>
bool operator== (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() == b.stdcont();
}
 
 
/// Based on operator==
template <class T>
bool operator!= (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() != b.stdcont();
}
 
 
/**
 * @brief  Vector ordering relation.
 * @param  a  A @c DataVector.
 * @param  b  A @c DataVector of the same type as @a x.
 * @return  True iff @a a is lexicographically less than @a b.
 *
 * This is a total ordering relation.  It is linear in the size of the
 * vectors.  Comparisons are done on the pointer values of the elements.
 *
 * See @c std::lexicographical_compare() for how the determination is made.
 */
template <class T>
bool operator< (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() < b.stdcont();
}
 
 
/// Based on operator<
template <class T>
bool operator> (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() > b.stdcont();
}
 
 
/// Based on operator<
template <class T>
bool operator<= (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() <= b.stdcont();
}
 
 
/// Based on operator<
template <class T>
bool operator>= (const DataVector<T>& a, const DataVector<T>& b)
{
  return a.stdcont() >= b.stdcont();
}
 
 
/// See @c DataVector<T, BASE>::swap().
template <class T>
void swap (DataVector<T>& a, DataVector<T>& b)
{
  a.swap (b);
}
 
 
/**
 * @brief Specialization of @c ClassName for @c DataVector.
 *
 * This overrides the default implementation of @c ClassName
 * to hide @c DataVector's second template parameter.
 */
template <class T>
std::string ClassName<DataVector<T> >::name()
{
  std::string out = "DataVector<";
  out += ClassName<T>::name();
  if (out[out.size()-1] == '>')
    out += ' ';
  out += '>';
  return out;
}
 
 
#ifndef XAOD_STANDALONE
 
 
// Set up initialization of element type BaseInfo
namespace DataVector_detail {
#define DVLTYPE DataVector
#include "AthContainers/tools/DVLEltBaseInfo.icc"
#undef DVLTYPE
} // namespace DataVector_detail
 
 
#else
 
 
namespace DataVector_detail {
/// Dummy implementation for the DVLEltBaseInit structure
template< class T >
struct DVLEltBaseInit {};
} // namespace DataVector_detail
 
 
#endif // not XAOD_STANDALONE
 
 
 
// We need to specialize the function that DVLInfo uses to create the container
// for DataVector.
/**
 * @brief Construct a new container.
 * @param nreserve Number of elements for which to reserve space.
 *                 (Ignored if not appropriate.)
 * @param cont[out] Pointer to the constructed container.
 *                  (Returned via an argument to allow for template
 *                  argument deduction.)
 *
 * Specialization for DataVector.
 */
template <class T>
void dvl_makecontainer (size_t nreserve, DataVector<T>*& cont)
{
  cont = new DataVector<T> (SG::VIEW_ELEMENTS);
  cont->reserve (nreserve);
}