1 /**
2  *
3  *   Copyright (c) 2005-2021 by Pierre-Henri WUILLEMIN(_at_LIP6) & Christophe GONZALES(_at_AMU)
4  *   info_at_agrum_dot_org
5  *
6  *  This library is free software: you can redistribute it and/or modify
7  *  it under the terms of the GNU Lesser General Public License as published by
8  *  the Free Software Foundation, either version 3 of the License, or
9  *  (at your option) any later version.
10  *
11  *  This library is distributed in the hope that it will be useful,
12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  *  GNU Lesser General Public License for more details.
15  *
16  *  You should have received a copy of the GNU Lesser General Public License
17  *  along with this library.  If not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 
22 /**
23  * @file
24  * @brief Headers for the abstract base class for all multi dimensionnal
25  * containers.
26  *
27  * MultiDimAdressable is the abstract base class for all multi dimensionnal
28  * adressable. Its purpose is to deal with slave Instantiation and notification
29  *
30  * @author Pierre-Henri WUILLEMIN(_at_LIP6) & Christophe GONZALES(_at_AMU)
31  */
32 
33 #ifndef GUM_MULTIDIM_ADRESSABLE_H
34 #define GUM_MULTIDIM_ADRESSABLE_H
35 
36 #include <iostream>
37 #include <vector>
38 
39 #include <agrum/agrum.h>
40 
41 #include <agrum/tools/multidim/instantiation.h>
42 
43 namespace gum {
44   // =========================================================================
45   // ===                             GUM_MULTI_DIM_ADRESSABLE              ===
46   // =========================================================================
47   /**
48    * @class MultiDimAdressable
49    * @headerfile multiDimAdressable.h <agrum/tools/multidim/multiDimAdressable.h>
50    * @ingroup multidim_group
51    *
52    * @brief Abstract base class for all multi dimensionnal addressable.
53    *
54    * MultiDimAdressable is the abstract base class for all multi dimensionnal
55    * adressable. Its purpose is to deal with slave Instantiation and
56    * notification.
57    */
58   class MultiDimAdressable: public MultiDimInterface {
59     public:
60     // =======================================================================
61     /// @name Constructors / Destructors
62     // =======================================================================
63     /// @{
64 
65     /**
66      * @brief Default constructor.
67      */
68     MultiDimAdressable();
69 
70     /**
71      * @brief Copy constructor.
72      */
73     MultiDimAdressable(const MultiDimAdressable& from);
74     MultiDimAdressable& operator=(const MultiDimAdressable& from);
75 
76     /**
77      * @brief Class move constructor.
78      */
79     MultiDimAdressable(MultiDimAdressable&&) noexcept;
80     MultiDimAdressable& operator=(MultiDimAdressable&& from) noexcept;
81 
82 
83     /**
84      * @brief Destructor.
85      */
86     ~MultiDimAdressable() override;
87 
88     /// @}
89     // =======================================================================
90     /// @name Slave management and extension due to slave management
91     // =======================================================================
92     /// @{
93     /**
94      * @brief In order to insure the dereference for decorators, we need to
95      * virtualize the access to master pointer.
96      * @return Returns the master of this MultiDimAdressable.
97      */
98     virtual MultiDimAdressable& getMasterRef() = 0;
99 
100     /**
101      * @brief In order to insure the dereference for decorators, we need to
102      * virtualize the access to master pointer.
103      * @return Returns the master of this MultiDimAdressable.
104      */
105     virtual const MultiDimAdressable& getMasterRef() const = 0;
106 
107     /**
108      * @brief Register i as a slave of this MultiDimAdressable.
109      * @param i The Instantiation to enslave.
110      * @return Returns true if i becomes a slave of this MultiDimAdressable.
111      */
112     virtual bool registerSlave(Instantiation& i) = 0;
113 
114     /**
115      * @brief Unregister i as a slave of this MultiDimAdressable.
116      * @param i The Instantiation to free.
117      * @return Returns true, whatever happens.
118      */
119     virtual bool unregisterSlave(Instantiation& i) = 0;
120 
121     /**
122      * @brief Listen to changes in a given Instantiation.
123      * @param i The Instantiation to listen.
124      * @param var The changed dim.
125      * @param oldval The old value.
126      * @param newval The changed value.
127      */
128     virtual void changeNotification(const Instantiation&          i,
129                                     const DiscreteVariable* const var,
130                                     Idx                           oldval,
131                                     Idx                           newval)
132        = 0;
133 
134     /**
135      * @brief Listen to setFirst in a given Instantiation.
136      * @param i The Instantiation to listen.
137      */
138     virtual void setFirstNotification(const Instantiation& i) = 0;
139 
140     /**
141      * @brief Listen to setLast in a given Instantiation.
142      * @param i The Instantiation to listen.
143      */
144     virtual void setLastNotification(const Instantiation& i) = 0;
145 
146     /**
147      * @brief Listen to increment in a given Instantiation.
148      * @param i The Instantiation to listen.
149      */
150     virtual void setIncNotification(const Instantiation& i) = 0;
151 
152     /**
153      * @brief Listen to increment in each recorded Instantiation.
154      * @param i The Instantiation to listen.
155      */
156     virtual void setDecNotification(const Instantiation& i) = 0;
157 
158     /**
159      * @brief Listen to an assignment of a value in a Instantiation.
160      * @param i The Instantiation to listen.
161      */
162     virtual void setChangeNotification(const Instantiation& i) = 0;
163 
164     /**
165      * @brief Return a string representation of internal data about i in this.
166      * @param i The Instantiation to represent.
167      * @return Return a string representation of internal data about i in this.
168      */
169     virtual std::string toString(const Instantiation* i) const = 0;
170 
171     /// @}
172   };
173 
174 } /* namespace gum */
175 
176 #ifndef GUM_NO_INLINE
177 #  include <agrum/tools/multidim/implementations/multiDimAdressable_inl.h>
178 #endif /* GUM_NO_INLINE */
179 
180 #endif /* GUM_MULTIDIM_ADRESSABLE_H */
181