1% XLiFE++ is an extended library of finite elements written in C++
2%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
3%
4%     This program is free software: you can redistribute it and/or modify
5%     it under the terms of the GNU General Public License as published by
6%     the Free Software Foundation, either version 3 of the License, or
7%     (at your option) any later version.
8%     This program is distributed in the hope that it will be useful,
9%     but WITHOUT ANY WARRANTY; without even the implied warranty of
10%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11%     GNU General Public License for more details.
12%     You should have received a copy of the GNU General Public License
13%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
14%%%%%%%%%%%%%%%%%%%
15
16\section{The collection classes}
17
18The {\class Collection} and {\class PCollection} are simple template classes to deal with with collection of objects or pointers to object. Inheriting from {\class vector<T>} or {\class vector<T*>}, they propose constructors with one, two, three, ... objects that are useful when users want to pass several numbers, several strings, ...  to {\class Parameter} object.
19
20\subsection{The {\classtitle Collection} class}
21The {\class Collection} class deals with some collections of objects. It has the following constructors :
22\vspace{.1cm}
23\begin{lstlisting}[]{}
24template <typename T>
25class Collection : public std::vector<T>
26{
27 public:
28 Collection () : std::vector<T>() {}
29 Collection (const std::vector<T>& ts);
30 explicit Collection (int n);
31 explicit Collection (int n, const T& s)
32 Collection(const T& s1);
33 Collection(const T& s1, const T& s2);
34 ...  //constructors up to 48 arguments !
35}
36\end{lstlisting}
37\vspace{.2cm}
38Besides, it has one accessor to the i-th item and some print stuff
39\vspace{.1cm}
40\begin{lstlisting}[]{}
41const T& operator()(number_t n) const;
42T& operator()(number_t n);
43void print(std::ostream& out) const;
44void print(PrintStream& os);
45template<typename S>
46ostream& operator<<(ostream& out, const Collection<S>& ns);
47\end{lstlisting}
48\vspace{.2cm}
49and the operator \verb|<<| is overloaded to mimic the insertion of an object in the collection :
50\vspace{.1cm}
51 \begin{lstlisting}[]{}
52template<typename T>
53Collection<T>& operator<<(Collection<T>& ns, const T& n)
54\end{lstlisting}
55\vspace{.2cm}
56Two important collections are predefined in \xlifepp : the {\class Numbers} ({\class Collection<Number>}) and the {\class Strings} ({\class Collection<String>}):
57\vspace{.1cm}
58\begin{lstlisting}[]{}
59Numbers ns(2,34,12);
60Strings ss("Omega","Gamma","Sigma");
61\end{lstlisting}
62
63\subsection{The {\classtitle PCollection} class}
64the {\class PCollection} class is similar to the {\class Collection} class but it deals  with collection of pointers to avoid copy of large objects. In order to be user friendly, it hides the pointers and its use is the same as  the {\class Collection} class:
65\vspace{.1cm}
66\begin{lstlisting}[]{}
67template <typename T>
68class PCollection : public std::vector<T*>
69{
70 public:
71 explicit PCollection (number_t n=0) : std::vector<T*>(n,0) {}
72 explicit PCollection (int n) : std::vector<T*>(n,0) {}
73 PCollection (const std::vector<T*>& ts) : std::vector<T*>(ts) {}
74 PCollection(const T& t1);
75 PCollection(const T& t1, const T& t2);
76 ...  //constructors up to 10 arguments !
77 const T & operator()(number_t n) const;
78 PCollectionItem<T> operator()(number_t n);
79 void clearPointers()
80 void print(std::ostream& out) const;
81 void print(PrintStream& os) const ;
82 template <typename S>
83 ostream& operator<<(ostream& out, const PCollection<S>& ts)
84 template <typename S>
85 PCollection<T>& operator<<(PCollection<T>& ts, const T& t)
86}
87\end{lstlisting}
88\vspace{.1cm}
89{\class PCollectionItem} class is a small class that interfaces one item of the collection. Its purpose is to move from reference to pointer when inserting an item in the collection using the access operator ():
90\vspace{.1cm}
91\begin{lstlisting}[]{}
92template<typename T> class PCollectionItem
93{ public:
94 typename std::vector<T*>::iterator itp;
95 PCollectionItem(typename std::vector<T*>::iterator);
96 T& operator = (const T& t);
97 operator T&(); // //autocast PCollectionItem -> T&
98}
99\end{lstlisting}
100\vspace{.2cm}
101As said before, this class may be used in a same way as the {\class Collection} class is used, keeping in mind that there is no copy of objects and therefore the pointers are shared!
102\vspace{.1cm}
103\begin{lstlisting}[]{}
104PCollection<String> ss(3);
105String s1="Omega";
106ss(1)=s1;      // OK while s1 is not deleted
107ss(2)="Gamma"; // FORBIDEN because "Gamma" is temporary
108\end{lstlisting}
109\vspace{.2cm}
110This class is designed for large objects of \xlifepp, such as {\class GeomDomain}, {\class Space} that will be presented later.
111
112\displayInfos{library=utils, header=Collection.hpp, implementation=Collection.hpp, test=test\_Parameters.cpp,
113header dep={config.h}}