IDatabaseTable_tpl.h

Go to the documentation of this file.

/**
 *
 *   Copyright 2005-2020 Pierre-Henri WUILLEMIN(@LIP6) & Christophe GONZALES(@AMU)
 *   info_at_agrum_dot_org
 *
 *  This library is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this library.  If not, see <http://www.gnu.org/licenses/>.
 *
 */


/** @file
 * @brief The implementation of the common class for tabular databases
 *
 * @author Christophe GONZALES(@AMU) and Pierre-Henri WUILLEMIN(@LIP6)
 */
#include <agrum/tools/database/IDatabaseTable.h>

#ifndef DOXYGEN_SHOULD_SKIP_THIS

namespace gum {

  namespace learning {

    // ===========================================================================
    // Unsafe handlers
    // ===========================================================================

    // default constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::Handler::Handler(
       const IDatabaseTable< T_DATA, ALLOC >& db) :
        DBHandler< T_DATA, ALLOC >(),
        db__(&db), row__(&(db.content())),
        end_index__(std::size_t(row__->size())) {
      GUM_CONSTRUCTOR(IDatabaseTable::Handler);
    }


    // copy constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::Handler::Handler(
       const typename IDatabaseTable< T_DATA, ALLOC >::Handler& h) :
        DBHandler< T_DATA, ALLOC >(),
        db__(h.db__), row__(h.row__), index__(h.index__),
        begin_index__(h.begin_index__), end_index__(h.end_index__) {
      GUM_CONS_CPY(IDatabaseTable::Handler);
    }


    // move constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::Handler::Handler(
       typename IDatabaseTable< T_DATA, ALLOC >::Handler&& h) :
        DBHandler< T_DATA, ALLOC >(),
        db__(h.db__), row__(h.row__), index__(h.index__),
        begin_index__(h.begin_index__), end_index__(h.end_index__) {
      GUM_CONS_MOV(IDatabaseTable::Handler);
    }


    // destructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::Handler::~Handler() {
      GUM_DESTRUCTOR(IDatabaseTable::Handler);
    }


    // copy operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator=(
          const typename IDatabaseTable< T_DATA, ALLOC >::Handler& h) {
      db__          = h.db__;
      row__         = h.row__;
      index__       = h.index__;
      begin_index__ = h.begin_index__;
      end_index__   = h.end_index__;
      return *this;
    }


    // move operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator=(
          typename IDatabaseTable< T_DATA, ALLOC >::Handler&& h) {
      db__          = h.db__;
      row__         = h.row__;
      index__       = h.index__;
      begin_index__ = h.begin_index__;
      end_index__   = h.end_index__;
      return *this;
    }


    // returns the current row pointed to by the handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::const_reference
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator*() const {
      return row__->operator[](index__);
    }


    // Dereferences the value pointed to by the handler (unsafe version)
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::const_pointer
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator->() const {
      return &(row__->operator[](index__));
    }


    // makes the handler point to the next row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator++() {
      ++index__;
      return *this;
    }


    // makes the handler point to the previous row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator--() {
      if (index__ > begin_index__) --index__;
      return *this;
    }


    //  moves the handler by i rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator+=(const std::size_t i) {
      index__ += i;
      return *this;
    }


    //  moves back the handler by i rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::Handler::operator-=(const std::size_t i) {
      if (index__ >= begin_index__ + i)
        index__ -= i;
      else
        index__ = begin_index__;
      return *this;
    }


    // checks whether two handlers point on the same row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::Handler::operator==(
       const Handler& handler) const {
      return index__ == handler.index__;
    }


    // checks whether two handlers point to different rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::Handler::operator!=(
       const Handler& handler) const {
      return index__ != handler.index__;
    }


    // returns the number of rows managed by the handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::Handler::size() const {
      return end_index__ - begin_index__;
    }


    // return the number of rows of the whole database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::Handler::DBSize() const {
      if (row__ != nullptr)
        return row__->size();
      else
        return std::size_t(0);
    }


    // returns the current row pointed to by the handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::const_reference
       IDatabaseTable< T_DATA, ALLOC >::Handler::rowSafe() const {
      if (index__ >= end_index__) {
        GUM_ERROR(OutOfBounds, "the handler has reached its end");
      }

      return row__->operator[](index__);
    }


    // returns the current row pointed to by the handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::reference
       IDatabaseTable< T_DATA, ALLOC >::Handler::rowSafe() {
      if (index__ >= end_index__) {
        GUM_ERROR(OutOfBounds, "the handler has reached its end");
      }

      return const_cast< Matrix< T_DATA >* >(row__)->operator[](index__);
    }


    // returns the current row pointed to by the handler (unsafe version)
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::const_reference
       IDatabaseTable< T_DATA, ALLOC >::Handler::row() const {
      return row__->operator[](index__);
    }


    // returns the current row pointed to by the handler (unsafe version)
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler::reference
       IDatabaseTable< T_DATA, ALLOC >::Handler::row() {
      return const_cast< Matrix< T_DATA >* >(row__)->operator[](index__);
    }


    // makes the handler point to the next row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::Handler::nextRow() {
      ++index__;
    }


    // returns the number of the current row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::Handler::numRow() const {
      return (index__ >= begin_index__) ? index__ - begin_index__ : 0;
    }

    // indicates whether the handler has reached its end or not
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::Handler::hasRows() const {
      return (index__ < end_index__);
    }

    // puts the handler to the beginning of the database area it handles
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::Handler::reset() {
      index__ = begin_index__;
    }


    // returns a new handler that points to the beginning of the
    // database area of the current handler */
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler
       IDatabaseTable< T_DATA, ALLOC >::Handler::begin() const {
      Handler handler(*this);
      handler.reset();
      return handler;
    }


    // returns a new handler that points to the end of the
    // database area of the current handler */
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler
       IDatabaseTable< T_DATA, ALLOC >::Handler::end() const {
      Handler handler(*this);
      handler.index__ = end_index__;
      return handler;
    }


    // sets the area in the database the handler will handle
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void
       IDatabaseTable< T_DATA, ALLOC >::Handler::setRange(std::size_t begin,
                                                          std::size_t end) {
      if (begin > end) std::swap(begin, end);

      // check that the end belongs to the database, else raise an exception
      if (row__ == nullptr) {
        GUM_ERROR(NullElement, "the handler does not point to any database");
      }
      if (end > row__->size()) {
        GUM_ERROR(SizeError,
                  "the database has fewer rows ("
                     << row__->size() << ") than the upper range (" << end
                     << ") specified to the handler");
      }

      begin_index__ = begin;
      end_index__   = end;
      index__       = begin;
    }


    // returns the current range of the handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::pair< std::size_t, std::size_t >
           IDatabaseTable< T_DATA, ALLOC >::Handler::range() const {
      return std::pair< std::size_t, std::size_t >(begin_index__, end_index__);
    }


    // returns the names of the variables
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const typename IDatabaseTable< T_DATA, ALLOC >::Handler::
       template DBVector< std::string >&
       IDatabaseTable< T_DATA, ALLOC >::Handler::variableNames() const {
      return db__->variableNames();
    }


    // returns the number of variables (columns) of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t
           IDatabaseTable< T_DATA, ALLOC >::Handler::nbVariables() const {
      if (db__ != nullptr)
        return db__->variableNames().size();
      else
        return 0;
    }


    // returns a pointer on the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const IDatabaseTable< T_DATA, ALLOC >&
                 IDatabaseTable< T_DATA, ALLOC >::Handler::database() const {
      if (db__ == nullptr) {
        GUM_ERROR(NullElement,
                  "The database handler does not point toward a database");
      }
      return *db__;
    }


    // ===========================================================================
    // Safe handlers
    // ===========================================================================

    // attach a new handler to the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::attachHandler__() {
      if (this->db__ != nullptr) { this->db__->attachHandler__(this); }
    }


    // detach a handler
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::detachHandler__() {
      if (this->db__ != nullptr) { this->db__->detachHandler__(this); }
    }


    // default constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::HandlerSafe(
       const IDatabaseTable< T_DATA, ALLOC >& db) :
        IDatabaseTable< T_DATA, ALLOC >::Handler(db) {
      attachHandler__();
      GUM_CONSTRUCTOR(IDatabaseTable::HandlerSafe);
    }


    // copy constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::HandlerSafe(
       const typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe& h) :
        IDatabaseTable< T_DATA, ALLOC >::Handler(h) {
      attachHandler__();
      GUM_CONS_CPY(IDatabaseTable::HandlerSafe);
    }


    // move constructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::HandlerSafe(
       typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&& h) :
        IDatabaseTable< T_DATA, ALLOC >::Handler(std::move(h)) {
      attachHandler__();
      GUM_CONS_MOV(IDatabaseTable::HandlerSafe);
    }


    // destructor
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::~HandlerSafe() {
      detachHandler__();
      GUM_DESTRUCTOR(IDatabaseTable::HandlerSafe);
    }


    // copy operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&
       IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::operator=(
          const typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe& h) {
      if (this->db__ != h.db__) {
        detachHandler__();
        this->db__ = h.db__;
        attachHandler__();
      }

      IDatabaseTable< T_DATA, ALLOC >::Handler::operator=(h);
      return *this;
    }


    // copy operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&
       IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::operator=(
          const typename IDatabaseTable< T_DATA, ALLOC >::Handler& h) {
      return this->operator=(
         dynamic_cast< const IDatabaseTable< T_DATA, ALLOC >::HandlerSafe& >(h));
    }


    // move operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&
       IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::operator=(
          typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&& h) {
      if (this->db__ != h.db__) {
        detachHandler__();
        this->db__ = h.db__;
        attachHandler__();
      }

      IDatabaseTable< T_DATA, ALLOC >::Handler::operator=(std::move(h));
      return *this;
    }


    // move operator
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&
       IDatabaseTable< T_DATA, ALLOC >::HandlerSafe::operator=(
          typename IDatabaseTable< T_DATA, ALLOC >::Handler&& h) {
      return this->operator=(std::move(
         dynamic_cast< IDatabaseTable< T_DATA, ALLOC >::HandlerSafe& >(h)));
    }


    // ===========================================================================
    // Database Tables
    // ===========================================================================

    // returns the allocator of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE ALLOC< T_DATA > IDatabaseTable< T_DATA, ALLOC >::getAllocator() const {
      return ALLOC< T_DATA >(*this);
    }


    // create the end iterators
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::createEndIterators__() {
      const IDatabaseTable< T_DATA, ALLOC >& db = *this;
      ALLOC< iterator >                      allocator1(*this);
      end__ = allocator1.allocate(1);
      try {
        allocator1.construct(end__, db);
      } catch (...) {
        allocator1.deallocate(end__, 1);
        throw;
      }

      ALLOC< iterator_safe > allocator2(*this);
      try {
        end_safe__ = allocator2.allocate(1);
        try {
          allocator2.construct(end_safe__, *this);
        } catch (...) {
          allocator2.deallocate(end_safe__, 1);
          throw;
        }
      } catch (...) {
        allocator1.destroy(end__);
        allocator1.deallocate(end__, 1);
        throw;
      }
    }


    // default constructor
    template < typename T_DATA, template < typename > class ALLOC >
    template < template < typename > class VARALLOC,
               template < typename >
               class MISSALLOC >
    IDatabaseTable< T_DATA, ALLOC >::IDatabaseTable(
       const typename IDatabaseTable< T_DATA, ALLOC >::template MissingValType<
          MISSALLOC >&                                            missing_symbols,
       const std::vector< std::string, VARALLOC< std::string > >& var_names,
       const ALLOC< T_DATA >&                                     alloc) :
        ALLOC< T_DATA >(alloc),
        variable_names_(alloc), rows_(alloc), missing_symbols_(alloc),
        has_row_missing_val_(alloc), list_of_safe_handlers__(alloc) {
      // copy the names
      variable_names_.reserve(var_names.size());
      for (const auto& name: var_names)
        variable_names_.push_back(name);

      // copy the missing symbols
      missing_symbols_.reserve(missing_symbols.size());
      for (const auto& missing_symbol: missing_symbols)
        missing_symbols_.push_back(missing_symbol);

      // create the end iterators
      createEndIterators__();

      GUM_CONSTRUCTOR(IDatabaseTable);
    }


    // copy constructor with a given allocator
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >::IDatabaseTable(
       const IDatabaseTable< T_DATA, ALLOC >&                          from,
       const typename IDatabaseTable< T_DATA, ALLOC >::allocator_type& alloc) :
        ALLOC< T_DATA >(alloc),
        variable_names_(from.variable_names_, alloc), rows_(from.rows_, alloc),
        missing_symbols_(from.missing_symbols_, alloc),
        has_row_missing_val_(from.has_row_missing_val_, alloc),
        max_nb_threads_(from.max_nb_threads_),
        min_nb_rows_per_thread_(from.min_nb_rows_per_thread_),
        list_of_safe_handlers__(alloc) {
      // create the end iterators
      createEndIterators__();

      GUM_CONS_CPY(IDatabaseTable);
    }


    // copy constructor
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >::IDatabaseTable(
       const IDatabaseTable< T_DATA, ALLOC >& from) :
        IDatabaseTable< T_DATA, ALLOC >(from, from.getAllocator()) {}


    // move constructor with a given allocator
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >::IDatabaseTable(
       IDatabaseTable< T_DATA, ALLOC >&&                               from,
       const typename IDatabaseTable< T_DATA, ALLOC >::allocator_type& alloc) :
        ALLOC< T_DATA >(alloc),
        variable_names_(std::move(from.variable_names_), alloc),
        rows_(std::move(from.rows_), alloc),
        missing_symbols_(std::move(from.missing_symbols_), alloc),
        has_row_missing_val_(std::move(from.has_row_missing_val_), alloc),
        max_nb_threads_(from.max_nb_threads_),
        min_nb_rows_per_thread_(from.min_nb_rows_per_thread_),
        list_of_safe_handlers__(alloc) {
      // create the end iterators
      createEndIterators__();

      GUM_CONS_MOV(IDatabaseTable);
    }


    // move constructor
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >::IDatabaseTable(
       IDatabaseTable< T_DATA, ALLOC >&& from) :
        IDatabaseTable< T_DATA, ALLOC >(std::move(from), from.getAllocator()) {}


    // destructor
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >::~IDatabaseTable() {
      // indicate to all the handlers that we are destructing the database
      safe_handlers_mutex__.lock();
      for (auto handler: list_of_safe_handlers__) {
        handler->db__        = nullptr;
        handler->row__       = nullptr;
        handler->end_index__ = 0;
        handler->index__     = 0;
      }
      safe_handlers_mutex__.unlock();

      ALLOC< iterator > allocator1(this->getAllocator());
      allocator1.destroy(end__);
      allocator1.deallocate(end__, 1);

      ALLOC< iterator_safe > allocator2(this->getAllocator());
      allocator2.destroy(end_safe__);
      allocator2.deallocate(end_safe__, 1);

      GUM_DESTRUCTOR(IDatabaseTable);
    }


    // copy operator
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >& IDatabaseTable< T_DATA, ALLOC >::operator=(
       const IDatabaseTable< T_DATA, ALLOC >& from) {
      if (this != &from) {
        // invalidate the current handlers
        safe_handlers_mutex__.lock();
        for (auto handler: list_of_safe_handlers__) {
          handler->db__        = nullptr;
          handler->row__       = nullptr;
          handler->end_index__ = 0;
          handler->index__     = 0;
        }
        list_of_safe_handlers__.clear();
        safe_handlers_mutex__.unlock();

        rows_                   = from.rows_;
        variable_names_         = from.variable_names_;
        missing_symbols_        = from.missing_symbols_;
        has_row_missing_val_    = from.has_row_missing_val_;
        max_nb_threads_         = from.max_nb_threads_;
        min_nb_rows_per_thread_ = from.min_nb_rows_per_thread_;

        // update the end iterators
        const std::size_t db_size = rows_.size();
        end__->index__            = db_size;
        end__->end_index__        = db_size;
        end_safe__->index__       = db_size;
        end_safe__->end_index__   = db_size;
      }

      return *this;
    }


    // move operator
    template < typename T_DATA, template < typename > class ALLOC >
    IDatabaseTable< T_DATA, ALLOC >& IDatabaseTable< T_DATA, ALLOC >::operator=(
       IDatabaseTable< T_DATA, ALLOC >&& from) {
      if (this != &from) {
        // invalidate the current handlers
        safe_handlers_mutex__.lock();
        for (auto handler: list_of_safe_handlers__) {
          handler->db__        = nullptr;
          handler->row__       = nullptr;
          handler->end_index__ = 0;
          handler->index__     = 0;
        }
        safe_handlers_mutex__.unlock();

        rows_                   = std::move(from.rows_);
        variable_names_         = std::move(from.variable_names_);
        missing_symbols_        = std::move(from.missing_symbols_);
        has_row_missing_val_    = std::move(from.has_row_missing_val_);
        max_nb_threads_         = from.max_nb_threads_;
        min_nb_rows_per_thread_ = from.min_nb_rows_per_thread_;

        // update the end iterators
        const std::size_t db_size = rows_.size();
        end__->index__            = db_size;
        end__->end_index__        = db_size;
        end_safe__->index__       = db_size;
        end_safe__->end_index__   = db_size;
      }

      return *this;
    }


    // returns a new unsafe handler pointing to the beginning of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler
       IDatabaseTable< T_DATA, ALLOC >::begin() const {
      return Handler(*this);
    }


    // returns a new safe handler pointing to the beginning of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe
       IDatabaseTable< T_DATA, ALLOC >::beginSafe() const {
      return HandlerSafe(*this);
    }


    // returns a new unsafe handler pointing to the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const typename IDatabaseTable< T_DATA, ALLOC >::Handler&
       IDatabaseTable< T_DATA, ALLOC >::end() const noexcept {
      return *end__;
    }


    /// returns a new safe handler pointing to the beginning of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe&
       IDatabaseTable< T_DATA, ALLOC >::endSafe() const noexcept {
      return *end_safe__;
    }


    // returns a new unsafe handler on the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::Handler
       IDatabaseTable< T_DATA, ALLOC >::handler() const {
      return Handler(*this);
    }


    // returns a new safe handler on the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE typename IDatabaseTable< T_DATA, ALLOC >::HandlerSafe
       IDatabaseTable< T_DATA, ALLOC >::handlerSafe() const {
      return HandlerSafe(*this);
    }


    // returns the content of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const typename IDatabaseTable< T_DATA,
                                          ALLOC >::template Matrix< T_DATA >&
       IDatabaseTable< T_DATA, ALLOC >::content() const noexcept {
      return rows_;
    }


    /// indicates whether the database contains some missing values
    template < typename T_DATA, template < typename > class ALLOC >
    bool IDatabaseTable< T_DATA, ALLOC >::hasMissingValues() const {
      for (const auto& status: has_row_missing_val_)
        if (status == IsMissing::True) return true;
      return false;
    }


    /// indicates whether the kth row contains some missing values
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::hasMissingValues(
       const std::size_t k) const {
      return has_row_missing_val_[k] == IsMissing::True;
    }


    // returns the variable names for all the columns
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const std::vector< std::string, ALLOC< std::string > >&
                 IDatabaseTable< T_DATA, ALLOC >::variableNames() const noexcept {
      return variable_names_;
    }


    // sets the names of the variables
    template < typename T_DATA, template < typename > class ALLOC >
    template < template < typename > class OTHER_ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::setVariableNames(
       const std::vector< std::string, OTHER_ALLOC< std::string > >& names,
       const bool from_external_object) {
      // copy the variable names into a vector allocated with the allocator
      // used by the database
      const std::size_t       size = names.size();
      DBVector< std::string > variable_names(size);
      for (std::size_t i = 0; i < size; ++i)
        variable_names[i] = names[i];

      this->setVariableNames(variable_names, from_external_object);
    }


    /// returns the name of the kth column of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const std::string&
       IDatabaseTable< T_DATA, ALLOC >::variableName(const std::size_t k) const {
      if (variable_names_.size() <= k)
        GUM_ERROR(OutOfBounds, "the database does not contain Column #" << k);
      return variable_names_[k];
    }


    /// returns the index of the column whose name is passed in argument
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::columnFromVariableName(
       const std::string& name) const {
      const std::size_t size = variable_names_.size();
      for (std::size_t i = 0; i < size; ++i)
        if (variable_names_[i] == name) return i;

      GUM_ERROR(UndefinedElement,
                "the database contains no column whose name is " << name);
    }


    /// returns the indices of the columns whose name is passed in argument
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE
       typename IDatabaseTable< T_DATA, ALLOC >::template DBVector< std::size_t >
       IDatabaseTable< T_DATA, ALLOC >::columnsFromVariableName(
          const std::string& name) const {
      const std::size_t       size = variable_names_.size();
      DBVector< std::size_t > cols;
      for (std::size_t i = 0; i < size; ++i)
        if (variable_names_[i] == name) cols.push_back(i);

      if (cols.empty())
        GUM_ERROR(UndefinedElement,
                  "the database contains no column whose name is " << name);

      return cols;
    }


    // returns the number of variables (columns) of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t
           IDatabaseTable< T_DATA, ALLOC >::nbVariables() const noexcept {
      return variable_names_.size();
    }


    // returns the number of records in the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::size() const noexcept {
      return rows_.size();
    }


    // returns the number of records in the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::nbRows() const noexcept {
      return rows_.size();
    }


    // indicates whether the database contains some records or not
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::empty() const noexcept {
      return rows_.empty();
    }


    // update the handlers when the size of the database changes
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::updateHandlers__(
       std::size_t new_size) const {
      const std::size_t db_size = rows_.size();

      safe_handlers_mutex__.lock();
      for (auto handler: list_of_safe_handlers__) {
        if ((handler->end_index__ == db_size)
            || (handler->end_index__ > new_size)) {
          handler->end_index__ = new_size;
          // there is no need to update the index because, in safe handlers,
          // we always check that the index is less than end_index when trying
          // to access the rows
        }
      }
      safe_handlers_mutex__.unlock();

      // update the end iterators
      end__->index__          = new_size;
      end__->end_index__      = new_size;
      end_safe__->index__     = new_size;
      end_safe__->end_index__ = new_size;
    }


    // attach a new handler to the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::attachHandler__(
       HandlerSafe* handler) const {
      safe_handlers_mutex__.lock();
      list_of_safe_handlers__.push_back(handler);
      safe_handlers_mutex__.unlock();
    }


    // detach a handler
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::detachHandler__(
       HandlerSafe* handler) const {
      safe_handlers_mutex__.lock();

      for (auto iter = list_of_safe_handlers__.rbegin();
           iter != list_of_safe_handlers__.rend();
           ++iter) {
        if (*iter == handler) {
          *iter = list_of_safe_handlers__.back();
          list_of_safe_handlers__.pop_back();
          break;
        }
      }

      safe_handlers_mutex__.unlock();
    }


    // checks whether a new row has the same size as the rest of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE bool IDatabaseTable< T_DATA, ALLOC >::isRowSizeOK_(
       const std::size_t size) const {
      return (size == variable_names_.size());
    }


    // insert a new row at the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    template < template < typename > class OTHER_ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::insertRow(
       const std::vector< std::string, OTHER_ALLOC< std::string > >& new_row) {
      const std::size_t                                size = new_row.size();
      std::vector< std::string, ALLOC< std::string > > good_typed_row(size);
      for (std::size_t i = 0; i < size; ++i)
        good_typed_row[i] = new_row[i];
      this->insertRow(good_typed_row);
    }


    // insert a new DBRow at the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::insertRow(
       typename IDatabaseTable< T_DATA, ALLOC >::template Row< T_DATA >&& new_row,
       const typename IDatabaseTable< T_DATA, ALLOC >::IsMissing
          contains_missing) {
      // check that the size of the row is the same as the rest of the database
      if (!isRowSizeOK_(new_row.size()))
        GUM_ERROR(SizeError,
                  "the new row is of size "
                     << new_row.size()
                     << ", which is different from the number of columns "
                     << "of the database, i.e., " << variable_names_.size());

      updateHandlers__(rows_.size() + 1);
      rows_.push_back(std::move(new_row));
      try {
        has_row_missing_val_.push_back(contains_missing);
      } catch (...) {
        rows_.pop_back();
        throw;
      }
    }


    // insert a new DBRow at the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::insertRow(
       const typename IDatabaseTable< T_DATA, ALLOC >::template Row< T_DATA >& row,
       const typename IDatabaseTable< T_DATA, ALLOC >::IsMissing
          contains_missing) {
      this->insertRow(
         typename IDatabaseTable< T_DATA, ALLOC >::template Row< T_DATA >(row),
         contains_missing);
    }


    // insert a set of new DBRow at the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::insertRows(
       typename IDatabaseTable< T_DATA, ALLOC >::template Matrix< T_DATA >&&
          new_rows,
       const typename IDatabaseTable< T_DATA, ALLOC >::template DBVector<
          typename IDatabaseTable< T_DATA, ALLOC >::IsMissing >&
          rows_have_missing_vals) {
      if (new_rows.empty()) return;

      // check that the missing values indicators vector has the same size
      // as the new rows
      if (rows_have_missing_vals.size() != new_rows.size())
        GUM_ERROR(
           SizeError,
           "the number of new rows (i.e., "
              << new_rows.size()
              << ") is different from the number of missing values indicators ("
              << rows_have_missing_vals.size());

      // check that all the rows have the same size
      const std::size_t new_size = new_rows[0].size();

      for (const auto& row: new_rows) {
        if (row.size() != new_size) {
          GUM_ERROR(SizeError,
                    "all the new rows do not have the same number of columns");
        }
      }

      // check that the sizes of the new rows are the same as the rest of
      // the database
      if (!isRowSizeOK_(new_size)) {
        GUM_ERROR(SizeError,
                  "the new rows have "
                     << new_size
                     << " columns, which is different from the number of columns "
                     << "of the database, i.e., " << variable_names_.size());
      }

      const std::size_t nb_new_rows = new_rows.size();
      const std::size_t new_db_size = rows_.size() + nb_new_rows;

      rows_.reserve(new_db_size);
      has_row_missing_val_.reserve(new_db_size);

      for (std::size_t i = std::size_t(0); i < nb_new_rows; ++i) {
        rows_.push_back(std::move(new_rows[i]));
        has_row_missing_val_.push_back(rows_have_missing_vals[i]);
      }

      updateHandlers__(new_db_size);
    }


    // insert a set of new DBRow at the end of the database
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::insertRows(
       const typename IDatabaseTable< T_DATA, ALLOC >::template Matrix< T_DATA >&
          new_rows,
       const typename IDatabaseTable< T_DATA, ALLOC >::template DBVector<
          typename IDatabaseTable< T_DATA, ALLOC >::IsMissing >&
          rows_have_missing_vals) {
      if (new_rows.empty()) return;

      // check that the missing values indicators vector has the same size
      // as the new rows
      if (rows_have_missing_vals.size() != new_rows.size())
        GUM_ERROR(
           SizeError,
           "the number of new rows (i.e., "
              << new_rows.size()
              << ") is different from the number of missing values indicators ("
              << rows_have_missing_vals.size());

      // check that all the rows have the same size
      const std::size_t new_size = new_rows[0].size();

      for (const auto& row: new_rows) {
        if (row.size() != new_size) {
          GUM_ERROR(SizeError,
                    "all the new rows do not have the same number of columns");
        }
      }

      // check that the sizes of the new rows are the same as the rest of
      // the database
      std::size_t db_size = rows_.size();

      if (!isRowSizeOK_(new_size)) {
        GUM_ERROR(SizeError,
                  "the new rows have "
                     << new_size
                     << " columns, which is different from the number of columns "
                     << "of the database, i.e., " << variable_names_.size());
      }

      const std::size_t nb_new_rows = new_rows.size();
      const std::size_t new_db_size = rows_.size() + nb_new_rows;

      rows_.reserve(new_db_size);
      has_row_missing_val_.reserve(new_db_size);

      for (std::size_t i = std::size_t(0); i < nb_new_rows; ++i) {
        rows_.push_back(new_rows[i]);
        has_row_missing_val_.push_back(rows_have_missing_vals[i]);
      }

      updateHandlers__(db_size);
    }


    // erase a given row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::eraseRow(std::size_t index) {
      const std::size_t db_size = rows_.size();

      if (index < db_size) {
        updateHandlers__(db_size - 1);
        rows_.erase(rows_.begin() + index);
        has_row_missing_val_.erase(has_row_missing_val_.begin() + index);
      }
    }


    // erase the last row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::eraseLastRow() {
      const std::size_t db_size = rows_.size();

      if (db_size) {
        updateHandlers__(db_size - 1);
        rows_.pop_back();
        has_row_missing_val_.pop_back();
      }
    }


    // erase the first row
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::eraseFirstRow() {
      const std::size_t db_size = rows_.size();

      if (db_size) {
        updateHandlers__(db_size - 1);
        rows_.erase(rows_.begin());
        has_row_missing_val_.erase(has_row_missing_val_.begin());
      }
    }


    // erase all the rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::eraseAllRows() {
      updateHandlers__(0);
      rows_.clear();
      has_row_missing_val_.clear();
    }


    // erase the k first rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void
       IDatabaseTable< T_DATA, ALLOC >::eraseFirstRows(const std::size_t nb_rows) {
      const std::size_t db_size = rows_.size();

      if (nb_rows >= db_size) {
        eraseAllRows();
      } else {
        updateHandlers__(db_size - nb_rows);
        rows_.erase(rows_.begin(), rows_.begin() + nb_rows);
        has_row_missing_val_.erase(has_row_missing_val_.begin(),
                                   has_row_missing_val_.begin() + nb_rows);
      }
    }


    // erase the k last rows
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void
       IDatabaseTable< T_DATA, ALLOC >::eraseLastRows(const std::size_t nb_rows) {
      const std::size_t db_size = rows_.size();

      if (nb_rows >= db_size) {
        eraseAllRows();
      } else {
        updateHandlers__(db_size - nb_rows);
        rows_.erase(rows_.begin() + (db_size - nb_rows), rows_.begin() + db_size);
        has_row_missing_val_.erase(has_row_missing_val_.begin()
                                      + (db_size - nb_rows),
                                   has_row_missing_val_.begin() + db_size);
      }
    }


    // erase the rows from the debth to the endth (not included)
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::eraseRows(std::size_t deb,
                                                           std::size_t end) {
      if (deb > end) std::swap(deb, end);

      const std::size_t db_size = rows_.size();

      if (end >= db_size) {
        if (deb >= db_size) {
          return;
        } else {
          eraseLastRows(db_size - deb);
        }
      } else {
        updateHandlers__(db_size - (end - deb));
        rows_.erase(rows_.begin() + deb, rows_.begin() + end);
        has_row_missing_val_.erase(has_row_missing_val_.begin() + deb,
                                   has_row_missing_val_.begin() + end);
      }
    }


    // erase the content of the database, including the names of the variables
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE void IDatabaseTable< T_DATA, ALLOC >::clear() {
      updateHandlers__(0);
      rows_.clear();
      has_row_missing_val_.clear();
      variable_names_.clear();
    }


    // returns the set of symbols for the missing values
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE const std::vector< std::string, ALLOC< std::string > >&
                 IDatabaseTable< T_DATA, ALLOC >::missingSymbols() const {
      return missing_symbols_;
    }


    /// changes the max number of threads that a database can use
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::setMaxNbThreads(
       const std::size_t nb) const {
      if (nb == std::size_t(0))
        max_nb_threads_ = std::size_t(1);
      else
        max_nb_threads_ = nb;
    }


    /// returns the number of threads used to parse the database
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t IDatabaseTable< T_DATA, ALLOC >::nbThreads() const {
      return max_nb_threads_;
    }


    /** @brief changes the number min of rows a thread should process in a
     * multithreading context */
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::setMinNbRowsPerThread(
       const std::size_t nb) const {
      if (nb == std::size_t(0))
        min_nb_rows_per_thread_ = std::size_t(1);
      else
        min_nb_rows_per_thread_ = nb;
    }


    /// returns the minimum of rows that each thread should process
    template < typename T_DATA, template < typename > class ALLOC >
    INLINE std::size_t
           IDatabaseTable< T_DATA, ALLOC >::minNbRowsPerThread() const {
      return min_nb_rows_per_thread_;
    }


    /// insert new rows at the end of the database
    template < template < typename > class ALLOC >
    void IDatabaseTableInsert4DBCell< ALLOC, true >::insertRows(
       const typename IDatabaseTableInsert4DBCell< ALLOC, true >::
          template DBVector< DBVector< std::string > >& new_rows) {
      for (const auto& new_row: new_rows)
        this->insertRow(new_row);
    }


    /// insert new rows at the end of the database
    template < template < typename > class ALLOC >
    void IDatabaseTableInsert4DBCell< ALLOC, false >::insertRows(
       const typename IDatabaseTableInsert4DBCell< ALLOC, false >::
          template DBVector< DBVector< std::string > >& new_rows) {
      for (const auto& new_row: new_rows)
        this->insertRow(new_row);
    }


    /// assign a given weight to all the rows of the database
    template < typename T_DATA, template < typename > class ALLOC >
    void
       IDatabaseTable< T_DATA, ALLOC >::setAllRowsWeight(const double new_weight) {
      // determine the number of threads to use and the number of rows
      // they should process
      std::vector< std::pair< std::size_t, std::size_t > > ranges;
      const std::size_t                                    db_size = nbRows();
      std::size_t nb_threads = db_size / min_nb_rows_per_thread_;
      if (nb_threads < 1)
        nb_threads = 1;
      else if (nb_threads > max_nb_threads_)
        nb_threads = max_nb_threads_;
      std::size_t nb_rows_per_thread = db_size / nb_threads;
      std::size_t rest_rows          = db_size - nb_rows_per_thread * nb_threads;

      // assign to threads the ranges over which they should change the
      // rows weights
      std::size_t begin_index = std::size_t(0);
      for (std::size_t i = std::size_t(0); i < nb_threads; ++i) {
        std::size_t end_index = begin_index + nb_rows_per_thread;
        if (rest_rows != std::size_t(0)) {
          ++end_index;
          --rest_rows;
        }
        ranges.push_back(
           std::pair< std::size_t, std::size_t >(begin_index, end_index));
        begin_index = end_index;
      }

      // perform the assignment:
      // launch the threads
      // here we use openMP for launching the threads because, experimentally,
      // it seems to provide results that are twice as fast as the results
      // with the std::thread
#  pragma omp parallel num_threads(int(nb_threads))
      {
        // get the number of the thread
        const std::size_t this_thread = getThreadNumber();
        const std::size_t begin_index = ranges[this_thread].first;
        const std::size_t end_index   = ranges[this_thread].second;

        for (std::size_t i = begin_index; i < end_index; ++i) {
          rows_[i].setWeight(new_weight);
        }
      }
    }

    /// assigns a given weight to the ith row of the database
    template < typename T_DATA, template < typename > class ALLOC >
    void IDatabaseTable< T_DATA, ALLOC >::setWeight(const std::size_t i,
                                                    const double      weight) {
      // check that i is less than the number of rows
      const std::size_t dbsize = nbRows();
      if (i >= dbsize) {
        std::string str;
        switch (i) {
          case 1:
            str = "st";
            break;
          case 2:
            str = "nd";
            break;
          default:
            str = "th";
        }
        GUM_ERROR(OutOfBounds,
                  "it is impossible to set the weight of the "
                     << i << str << " record because the database contains only "
                     << nbRows() << " records");
      }

      // check that the weight is positive
      if (weight < 0) {
        std::string str;
        switch (i) {
          case 1:
            str = "st";
            break;
          case 2:
            str = "nd";
            break;
          default:
            str = "th";
        }
        GUM_ERROR(OutOfBounds,
                  "it is impossible to set "
                     << weight << " as a weight of the " << i << str
                     << " record because this weight is negative");
      }

      rows_[i].setWeight(weight);
    }


    /// returns the weight of the ith record
    template < typename T_DATA, template < typename > class ALLOC >
    double IDatabaseTable< T_DATA, ALLOC >::weight(const std::size_t i) const {
      // check that i is less than the number of rows
      const std::size_t dbsize = nbRows();
      if (i >= dbsize) {
        std::string str;
        switch (i) {
          case 1:
            str = "st";
            break;
          case 2:
            str = "nd";
            break;
          default:
            str = "th";
        }
        GUM_ERROR(OutOfBounds,
                  "it is impossible to get the weight of the "
                     << i << str << " record because the database contains only "
                     << nbRows() << " records");
      }

      return rows_[i].weight();
    }


    /// returns the weight of the whole database
    template < typename T_DATA, template < typename > class ALLOC >
    double IDatabaseTable< T_DATA, ALLOC >::weight() const {
      double w = 0.0;
      for (const auto& row: rows_)
        w += row.weight();
      return w;
    }


  } /* namespace learning */

} /* namespace gum */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */