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{String, Strings}
18
19{\class String} is a nice class allowing to deal with char of arrays without managing the memory.
20{\class String} is no more than an alias to the string class of the STL which is either standard
21string (utf8, by default) or wide string (utf16); this choice is made in the \emph{config.hpp}
22header file by setting the macro \emph{WIDE\_STRING}. When this macro changes, all the library
23has to be rebuilt!\\
24
25As a string or wstring class of the STL, {\class String} proposes all the functionalities of std::string.
26Mainly, you can create, concatenate string, access to char and find string in string:
27\vspace{.2cm}
28\begin{lstlisting}
29String s1("a string");        // create a String
30String s2="an other string";  // create a String using =
31String s12=s1+" and "+s2;     // concatenate String, s3="a"+"b" does not work!
32s1+=" and "+s2;               // concatenate String, now s1 is the same as s12
33int l=s1.size();              // number of char of s1, s1.length() gives the same
34char a=s1[3];                 // char a='t' (the fourth character)
35s1[3]=p;                      // now s1="a spring and an other string";
36int p=s1.find("string",0);    // find first position of "string" from beginning (if p=-1 not found)
37s1.replace(p,5,"spring");     // replace "string" by "spring"
38s2=s1.substr(p,5);            // extract string of length 5 from position p
39s1.compare(s2);               // alphanumeric comparison, return 0 if equal,
40                              // a negative (positive) value if s1<s2 (s1>s2)
41char * c=s1.c_str();          // return pointer to the char array of the string
42\end{lstlisting}
43There a lot of variations of these string functions and other functions; see the STL documentation.\\
44
45Some additional functions which may be useful have been introduced:
46\begin{lstlisting}
47template<typename T_>
48String tostring(const T_& t);  // 'anything' to String
49template<typename T_>
50T_ stringto(const String& s);  // String to 'anything'
51// returns String converted to lowercase
52String lowercase(const String&);
53// returns String converted to uppercase
54String uppercase(const String&);
55// returns String with initial converted to uppercase
56String capitalize(const String&);
57// trims leading white space from String
58String trimLeading(const String&);
59// trims trailing white space from String
60String trimTrailing(const String&);
61// trims leading and trailing white space from String
62String trimSpace(const String&);
63// delete all white space from String
64String delSpace(const String& s);
65// search capabilities
66int findString(const String, const std::vector<String>&);
67\end{lstlisting}
68\vspace{.2cm}
69Be cautious with template conversion functions. The template \emph{T\_} type has to be clarified
70when invoking \emph{stringto}.
71\begin{lstlisting}
72// examples of conversion stringto
73String s="1 2 3";
74int i=stringto<int>(s);         // i=1
75Real r=stringto<Real>(s);       // r=1.
76Complex c=stringto<Complex>(s); // c=(1.,0)
77void * p=stringto<void*>(s);    // p=0x1
78String ss=stringto<String>(s);  // ss="1"
79s="(0,1)";
80c=stringto<Complex>(s);         // c=(0.,1.)
81\end{lstlisting}
82
83Besides, lists of strings are available using Strings:
84\begin{lstlisting}[]{}
85// list of strings
86Strings ss("x=0","x=1","y=0","z=0"); //initialize list (up to 5 elements)
87Strings ls(10);   //10 empty strings
88ls(1)="x=0";      //access to first string of list
89String s=ss(3);
90cout<<ss;         //output list
91\end{lstlisting}
92
93{\class Strings} inherits from {\cmd std::vector<String>}.
94
95