1%%%%%%%%%%%%%%%%%%%
2% XLiFE++ is an extended library of finite elements written in C++
3%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
4%
5%     This program is free software: you can redistribute it and/or modify
6%     it under the terms of the GNU General Public License as published by
7%     the Free Software Foundation, either version 3 of the License, or
8%     (at your option) any later version.
9%     This program is distributed in the hope that it will be useful,
10%     but WITHOUT ANY WARRANTY; without even the implied warranty of
11%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12%     GNU General Public License for more details.
13%     You should have received a copy of the GNU General Public License
14%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
15%%%%%%%%%%%%%%%%%%%
16
17\section{The {\classtitle Value} class}
18
19The {\class Value} class is a utility class to encapsulates user's data involved in a differential
20expression. Such data may be a function ({\class Function} object) or any real or complex scalar,
21vector or matrix value. This class is designed as follows:
22\vspace{.2cm}
23\begin{lstlisting}
24class Value
25{
26protected :
27  ValueType type_;   //type of returned value ( _real, _complex)
28  StrucType struct_; //structure of returned value (_scalar, _vector, _matrix,
29	                         _vectorofvector, _vectorofmatrix, _matrixofmatrix)
30  void * value_p;          //void pointeur to the true value
31  mutable bool conjugate_; //temporary conjugate state flag
32  mutable bool transpose_; //temporary transposition state flag
33\end{lstlisting}
34\vspace{.2cm}
35The attributes \textit{conjugate\_} and \textit{transpose\_} are temporary flags used when
36chaining Value object in a differential expression.
37They have no meaning outside a particular context!\\
38In order to recast safely the void pointer \textit{value\_p} pointing to the actual data, this
39class uses the Run Time Information, to store the names of data type supported:
40\vspace{.1cm}
41\begin{lstlisting}[deletekeywords={[3] map}]
42typedef std::pair<ValueType,StrucType> structPair;
43typedef std::pair<String,structPair> mapPair;
44static std::map<String,structPair > theValueTypeRTInames;
45static void valueTypeRTINamesInit();
46\end{lstlisting}
47\vspace{.2cm}
48The only constructors allowed are the following:
49\vspace{.1cm}
50\begin{lstlisting}[]
51Value(const real_t &);
52Value(const Vector<real_t> &);
53Value(const Matrix<real_t> &);
54Value(const Vector<Vector<real_t> > &);
55Value(const Vector<Matrix<real_t> >&);
56Value(const Matrix<Matrix<real_t> >&);
57Value(const complex_t &);
58Value(const Vector<complex_t> &);
59Value(const Matrix<complex_t> &);
60Value(const Vector<Vector<complex_t> > &);
61Value(const Vector<Matrix<complex_t> >&);
62Value(const Matrix<Matrix<complex_t> >&);
63\end{lstlisting}
64\vspace{.2cm}
65They correspond to the data types that are supported by this encapsulation class. These constructors
66create in memory a copy of the given value.\\
67
68There are two templated functions to check the data types:
69\vspace{.1cm}
70\begin{lstlisting}[]
71template<typename T> static bool checkTypeInList(const T &);
72template<typename T> static bool isTypeInList(const T&);
73template<typename T> void checkType(const T&) const;
74\end{lstlisting}
75\vspace{.2cm}
76The two first ones checks if the type T is in the list of allowed types and the second one
77compares the type T to the type of the current Value. To get the actual value, you have to
78use the templated member function:
79\vspace{.1cm}
80\begin{lstlisting}[]
81template<class T> T& value() const;
82\end{lstlisting}
83\vspace{.2cm}
84Note that you have to explicit the template argument T. This function checks the value type
85and recasts the void pointer. \\
86
87Besides, there are accessors/modifiers member functions:
88\vspace{.1cm}
89\begin{lstlisting}[]
90ValueType valueType() const{return type_;}
91StrucType strucType() const{return struct_;}
92bool  conjugate()const {return conjugate_;}
93bool& conjugate() {return conjugate_;}
94void  conjugate(bool v) const {conjugate_=v;}
95bool  transpose()const {return transpose_;}
96bool& transpose() {return transpose_;}
97void  transpose(bool v) const {transpose_=v;}
98\end{lstlisting}
99\vspace{.2cm}
100In order to conjugate or transpose (or both) a value in an expression, this class provides
101the functions:
102\vspace{.1cm}
103\begin{lstlisting}[]
104Value& conj(Value &);
105Value& trans(Value &);
106Value& adj(Value &);
107\end{lstlisting}
108\vspace{.1cm}
109Be care, these functions do not modify the value but just set the\textit{ conjugate\_}/\textit{transpose\_}
110flag to its opposite.\\
111
112Finally, there are some printing functions:
113\vspace{.1cm}
114\begin{lstlisting}[]
115static void Value::printValueTypeRTINames(std::ostream&);
116void Value::print(std::ostream &) const;
117friend std::ostream& operator<<(std::ostream&,const Value &);
118\end{lstlisting}
119\vspace{.2cm}
120Here, we give a small example to illustrate how the {\class Value} class works:
121\vspace{.1cm}
122\begin{lstlisting}[]
123Value::printValueTypeRTINames(cout);     //print on stdout the RTI names of value types
124real_t s=1.;
125Value Vs(s);                             //create Value object
126cout<<"real Value Vs(s) :"<<Vs;          //print Value
127real_t r =Vs.value<real_t>();            //get as a real
128Vector<complex_t> vc(3,complex_t(0,1));	 //a vector of complex values
129Value Vvc(vc);
130cout<<"complex vector Value Vvc(vc) :"<<Vvc;         //print Value
131Vector<complex_t> wc=Vvc.value<Vector<complex_t> >();//get as a complex vector
132\end{lstlisting}
133\vspace{.2cm}
134
135\displayInfos{library=operator, header=Value.hpp, implementation=Value.cpp, test=test\_operator.cpp,
136header dep={config.h, utils.h}}
137