IDatabaseTable.h

Go to the documentation of this file.

/****************************************************************************
 *   This file is part of the aGrUM/pyAgrum library.                        *
 *                                                                          *
 *   Copyright (c) 2005-2025 by                                             *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *                                                                          *
 *   The aGrUM/pyAgrum library is free software; you can redistribute it    *
 *   and/or modify it under the terms of either :                           *
 *                                                                          *
 *    - 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,                              *
 *    - the MIT license (MIT),                                              *
 *    - or both in dual license, as here.                                   *
 *                                                                          *
 *   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    *
 *                                                                          *
 *   This aGrUM/pyAgrum library is distributed in the hope that it will be  *
 *   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          *
 *   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
 *   FOR A PARTICULAR PURPOSE  AND NONINFRINGEMENT. IN NO EVENT SHALL THE   *
 *   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
 *   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,        *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR  *
 *   OTHER DEALINGS IN THE SOFTWARE.                                        *
 *                                                                          *
 *   See LICENCES for more details.                                         *
 *                                                                          *
 *   SPDX-FileCopyrightText: Copyright 2005-2025                            *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      *
 *                                                                          *
 *   Contact  : info_at_agrum_dot_org                                       *
 *   homepage : http://agrum.gitlab.io                                      *
 *   gitlab   : https://gitlab.com/agrumery/agrum                           *
 *                                                                          *
 ****************************************************************************/
 

#ifndef GUM_IDATABASE_TABLE_H
#define GUM_IDATABASE_TABLE_H
 
#include <cstddef>
#include <cstring>
#include <memory>
#include <mutex>
#include <string>
#include <utility>
#include <vector>
 
#include <agrum/agrum.h>
 
#include <agrum/base/core/threads/threadExecutor.h>
#include <agrum/base/core/threads/threads.h>
#include <agrum/base/database/DBCell.h>
#include <agrum/base/database/DBHandler.h>
#include <agrum/base/database/DBTranslator.h>
 
namespace gum {
 
  namespace learning {
 
    template < bool ENABLE_INSERT >
    struct IDatabaseTableInsert4DBCell;
 
    template <>
    struct IDatabaseTableInsert4DBCell< true > {
      template < typename TX_DATA >
      using DBVector = std::vector< TX_DATA >;
 
      template < typename TX_DATA >
      using Row = DBRow< TX_DATA >;
 
      template < typename TX_DATA >
      using Matrix = std::vector< DBRow< TX_DATA > >;
 


      virtual void insertRow(Row< DBCell >&& new_row) = 0;


      virtual void insertRow(const Row< DBCell >& new_row) = 0;


      virtual void insertRows(Matrix< DBCell >&& new_rows) = 0;


      virtual void insertRows(const Matrix< DBCell >& new_rows) = 0;


      virtual void insertRow(const std::vector< std::string >& new_row) = 0;


      virtual void insertRows(const DBVector< DBVector< std::string > >& new_rows);
    };
 
    template <>
    struct IDatabaseTableInsert4DBCell< false > {
      template < typename TX_DATA >
      using DBVector = std::vector< TX_DATA >;
 
      template < typename TX_DATA >
      using Row = DBRow< TX_DATA >;
 
      template < typename TX_DATA >
      using Matrix = std::vector< DBRow< TX_DATA > >;


      virtual void insertRow(const std::vector< std::string >& new_row) = 0;


      virtual void insertRows(const DBVector< DBVector< std::string > >& new_rows);
    };

    template < typename T_DATA >
    class IDatabaseTable:
        public IDatabaseTableInsert4DBCell< !std::is_same< T_DATA, DBCell >::value > {
      public:
      template < typename TX_DATA >
      using DBVector = std::vector< TX_DATA >;

      template < typename TX_DATA >
      using Row = DBRow< TX_DATA >;

      template < typename TX_DATA >
      using Matrix = std::vector< DBRow< TX_DATA > >;
 
      using MissingValType = std::vector< std::string >;
 
      enum IsMissing : char { False, True };

      class Handler: public DBHandler< T_DATA > {
        public:
        using iterator_category = std::random_access_iterator_tag;
        using value_type        = typename DBHandler< T_DATA >::value_type;
        using reference         = value_type&;
        using const_reference   = const value_type&;
        using pointer           = value_type*;
        using const_pointer     = const value_type*;
        using difference_type   = std::ptrdiff_t;
 
        template < typename TX_DATA >
        using DBVector = std::vector< TX_DATA >;
 
        template < typename TX_DATA >
        using Row = DBRow< TX_DATA >;
 
        template < typename TX_DATA >
        using Matrix = std::vector< DBRow< TX_DATA > >;
 
 
        // ########################################################################
        // ########################################################################


        Handler(const IDatabaseTable< T_DATA >& db);


        Handler(const Handler& h);


        Handler(Handler&& h);

        virtual ~Handler();

 
        // ########################################################################
        // ########################################################################

        virtual Handler& operator=(const Handler&);

        virtual Handler& operator=(Handler&&);


        virtual Handler& operator++() final;


        virtual Handler& operator--() final;


        virtual Handler& operator+=(const std::size_t i) final;


        virtual Handler& operator-=(const std::size_t i) final;

        virtual bool operator==(const Handler& handler) const final;

        virtual bool operator!=(const Handler& handler) const final;


        virtual const_reference operator*() const final;


        virtual const_pointer operator->() const final;

 
 
        // ########################################################################
        // ########################################################################


        virtual std::size_t size() const final;

        virtual std::size_t DBSize() const final;


        virtual const_reference rowSafe() const final;


        virtual reference rowSafe() final;


        virtual const_reference row() const final;


        virtual reference row() final;

        virtual void nextRow() final;

        virtual std::size_t numRow() const final;

        virtual bool hasRows() const final;

        virtual void reset() final;

        virtual Handler begin() const;

        virtual Handler end() const;


        virtual void setRange(std::size_t first, std::size_t last) final;

        virtual std::pair< std::size_t, std::size_t > range() const final;

        virtual const DBVector< std::string >& variableNames() const final;

        virtual std::size_t nbVariables() const final;


        virtual const IDatabaseTable< T_DATA >& database() const;

 
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
        protected:
        const IDatabaseTable< T_DATA >* _db_;


        const Matrix< T_DATA >* _row_;

        std::size_t _index_{std::size_t(0)};

        std::size_t _begin_index_{std::size_t(0)};

        std::size_t _end_index_{std::size_t(0)};
 
        friend class IDatabaseTable< T_DATA >;
 
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
      };

      class HandlerSafe final: public Handler {
        public:
        using iterator_category = std::random_access_iterator_tag;
        using value_type        = typename Handler::value_type;
        using reference         = value_type&;
        using const_reference   = const value_type&;
        using pointer           = value_type*;
        using const_pointer     = const value_type*;
        using difference_type   = std::ptrdiff_t;
 
        // ########################################################################
        // ########################################################################


        HandlerSafe(const IDatabaseTable< T_DATA >& db);

        HandlerSafe(const HandlerSafe& h);

        HandlerSafe(HandlerSafe&& h);

        virtual ~HandlerSafe();

 
        // ########################################################################
        // ########################################################################

        virtual HandlerSafe& operator=(const HandlerSafe&);

        virtual HandlerSafe& operator=(const Handler&);

        virtual HandlerSafe& operator=(HandlerSafe&&);

        virtual HandlerSafe& operator=(Handler&&);

 
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
        private:
        void _attachHandler_();

        void _detachHandler_();
 
        friend class IDatabaseTable< T_DATA >;
 
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
      };

      using value_type          = Row< T_DATA >;
      using reference           = value_type&;
      using const_reference     = const value_type&;
      using pointer             = value_type*;
      using const_pointer       = const value_type*;
      using size_type           = std::size_t;
      using difference_type     = std::ptrdiff_t;
      using iterator            = Handler;
      using iterator_safe       = HandlerSafe;
      using const_iterator      = const Handler;
      using const_iterator_safe = const HandlerSafe;
 
 
      // ##########################################################################
      // ##########################################################################

      IDatabaseTable(const MissingValType&             missing_symbols,
                     const std::vector< std::string >& var_names);

      IDatabaseTable(const IDatabaseTable< T_DATA >& from);

      IDatabaseTable(IDatabaseTable< T_DATA >&& from);

      virtual IDatabaseTable< T_DATA >* clone() const = 0;

      virtual ~IDatabaseTable();

 
 
      // ##########################################################################
      // ##########################################################################

      iterator begin() const;

      iterator_safe beginSafe() const;

      const iterator& end() const noexcept;

      const iterator_safe& endSafe() const noexcept;

 
 
      // ##########################################################################
      // ##########################################################################

      const Matrix< T_DATA >& content() const noexcept;

      iterator handler() const;

      iterator_safe handlerSafe() const;


      const DBVector< std::string >& variableNames() const noexcept;


      virtual void setVariableNames(const std::vector< std::string >& names,
                                    const bool                        from_external_object = true)
          = 0;


      const std::string& variableName(const std::size_t k) const;


      std::size_t columnFromVariableName(const std::string& name) const;


      DBVector< std::size_t > columnsFromVariableName(const std::string& name) const;

      std::size_t nbVariables() const noexcept;

      std::size_t nbRows() const noexcept;

      std::size_t size() const noexcept;

      bool empty() const noexcept;


      virtual void ignoreColumn(const std::size_t k, const bool from_external_object = true) = 0;

      virtual const DBVector< std::size_t > ignoredColumns() const = 0;

      virtual const DBVector< std::size_t > inputColumns() const = 0;
 
      using IDatabaseTableInsert4DBCell< !std::is_same< T_DATA, DBCell >::value >::insertRow;


      virtual void insertRow(const std::vector< std::string >& new_row) = 0;


      virtual void insertRow(Row< T_DATA >&& new_row, const IsMissing contains_missing_data);


      virtual void insertRow(const Row< T_DATA >& new_row, const IsMissing contains_missing_data);
 
      using IDatabaseTableInsert4DBCell< !std::is_same< T_DATA, DBCell >::value >::insertRows;


      virtual void insertRows(Matrix< T_DATA >&&           new_rows,
                              const DBVector< IsMissing >& rows_have_missing_vals);


      virtual void insertRows(const Matrix< T_DATA >&      new_rows,
                              const DBVector< IsMissing >& rows_have_missing_vals);


      void eraseRow(std::size_t index);


      void eraseFirstRow();


      void eraseLastRow();


      void eraseFirstRows(const std::size_t k);


      void eraseLastRows(const std::size_t k);


      void eraseRows(std::size_t deb, std::size_t end);

      void eraseAllRows();

      virtual void clear();

      const DBVector< std::string >& missingSymbols() const;

      bool hasMissingValues() const;

      bool hasMissingValues(const std::size_t k) const;


      void setMaxNbThreads(const std::size_t nb) const;

      std::size_t nbThreads() const;

      void setMinNbRowsPerThread(const std::size_t nb) const;

      std::size_t minNbRowsPerThread() const;

      void setAllRowsWeight(const double new_weight);


      void setWeight(const std::size_t i, const double weight);


      double weight(const std::size_t i) const;

      double weight() const;

 
 
      protected:
      DBVector< std::string > variable_names_;
 
      // the vector of DBRows containing all the raw data
      Matrix< T_DATA > rows_;
 
      // the set of string corresponding to missing values
      DBVector< std::string > missing_symbols_;
 
      // a vector indicating which rows have missing values (char != 0)
      DBVector< IsMissing > has_row_missing_val_;
 
      // the maximal number of threads that the database can use
      mutable std::size_t max_nb_threads_{std::size_t(gum::getNumberOfThreads())};
 
      // the min number of rows that a thread should process in a
      // multithreading context
      mutable std::size_t min_nb_rows_per_thread_{100};
 

      bool isRowSizeOK_(const std::size_t size) const;

      std::size_t nbProcessingThreads_() const;

      std::vector< std::pair< std::size_t, std::size_t > >
          rangesProcessingThreads_(const std::size_t nb_threads) const;

      IDatabaseTable< T_DATA >& operator=(const IDatabaseTable< T_DATA >& from);

      IDatabaseTable< T_DATA >& operator=(IDatabaseTable< T_DATA >&& from);
 
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
      private:
      // the list of handlers currently attached to the database
      /* this is useful when the database is resized */
      mutable DBVector< HandlerSafe* > _list_of_safe_handlers_;
 
      // a mutex to safely add/remove handlers in  _list_of_safe_handlers_
      mutable std::mutex _safe_handlers_mutex_;
 
      // the end iterator for the database
      Handler* _end_{nullptr};
 
      // the safe end iterator for the database
      iterator_safe* _end_safe_{nullptr};

      void _attachHandler_(HandlerSafe* handler) const;

      void _detachHandler_(HandlerSafe* handler) const;

      void _updateHandlers_(std::size_t new_size) const;
 
      // create the end iterators
      void _createEndIterators_();
 
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 

      friend class Handler;
      friend class HandlerSafe;
    };
 
  } /* namespace learning */
 
} /* namespace gum */

#include <agrum/base/database/IDatabaseTable_tpl.h>
 
#endif /* GUM_IDATABASE_TABLE_H */