Cantera  2.4.0
stringUtils.h
Go to the documentation of this file.
1 /**
2  * @file stringUtils.h Contains declarations for string manipulation
3  * functions within Cantera.
4  */
5 
6 // This file is part of Cantera. See License.txt in the top-level directory or
7 // at http://www.cantera.org/license.txt for license and copyright information.
8 
9 #ifndef CT_STRINGUTILS_H
10 #define CT_STRINGUTILS_H
11 
12 #include "ct_defs.h"
13 #include "cantera/base/fmt.h"
14 
15 #include <string>
16 
17 namespace Cantera
18 {
19 
20 //! Convert a vector to a string (separated by commas)
21 /*!
22  * @param v vector to be converted
23  * @param fmt Format to be used (printf style) for each element
24  * @param sep Separator
25  */
26 std::string vec2str(const vector_fp& v, const std::string& fmt="%g",
27  const std::string& sep=", ");
28 
29 //! Strip non-printing characters wherever they are
30 /*!
31  * @param s Input string
32  * @returns a copy of the string, stripped of all non- printing characters.
33  */
34 std::string stripnonprint(const std::string& s);
35 
36 //! Parse a composition string into a map consisting of individual
37 //! key:composition pairs.
38 /*!
39  * Elements present in *names* but not in the composition string will have
40  * a value of 0. Elements present in the composition string but not in *names*
41  * will generate an exception. The composition is a double. Example:
42  *
43  * Input is
44  *
45  * "ice:1 snow:2"
46  * names = ["fire", "ice", "snow"]
47  *
48  * Output is
49  * x["fire"] = 0
50  * x["ice"] = 1
51  * x["snow"] = 2
52  *
53  * @param ss original string consisting of multiple key:composition
54  * pairs on multiple lines
55  * @param names (optional) valid names for elements in the composition map. If
56  * empty or unspecified, all values are allowed.
57  * @return map of names to values
58  */
59 compositionMap parseCompString(const std::string& ss,
60  const std::vector<std::string>& names=std::vector<std::string>());
61 
62 //! Translate a string into one integer value
63 /*!
64  * No error checking is done on the conversion. The c stdlib function atoi() is
65  * used.
66  *
67  * @param val String value of the integer
68  * @returns an integer
69  */
70 int intValue(const std::string& val);
71 
72 //! Translate a string into one doublereal value
73 /*!
74  * No error checking is done on the conversion.
75  *
76  * @param val String value of the double
77  * @returns a double
78  */
79 doublereal fpValue(const std::string& val);
80 
81 //! Translate a string into one doublereal value, with error checking
82 /*!
83  * fpValueCheck is a wrapper around the C++ stringstream double parser. It
84  * does quite a bit more error checking than atof() or strtod(), and is quite
85  * a bit more restrictive.
86  *
87  * First it interprets both E, e, d, and D as exponents. stringstreams only
88  * interpret e or E as an exponent character.
89  *
90  * It only accepts a string as well formed if it consists as a single token.
91  * Multiple words will raise an exception. It will raise a CanteraError for
92  * NAN and inf entries as well, in contrast to atof() or strtod(). The user
93  * needs to know that a serious numerical issue has occurred.
94  *
95  * It does not accept hexadecimal numbers.
96  *
97  * It always use the C locale, regardless of any locale settings.
98  *
99  * @param val String representation of the number
100  * @returns a double
101  */
102 doublereal fpValueCheck(const std::string& val);
103 
104 //! Parse a name string, separating out the phase name from the species name
105 /*!
106  * Name strings must not contain these internal characters "; \n \t ," Only one
107  * colon is allowed, the one separating the phase name from the species name.
108  * Therefore, names may not include a colon.
109  *
110  * @param[in] nameStr Name string containing the phase name and the species
111  * name separated by a colon. The phase name is optional.
112  * example: "silane:SiH4"
113  * @param[out] phaseName Name of the phase, if specified. If not specified, a
114  * blank string is returned.
115  * @returns species name. If nameStr is blank an empty string is returned.
116  */
117 std::string parseSpeciesName(const std::string& nameStr, std::string& phaseName);
118 
119 //! Interpret one or two token string as a single double
120 /*!
121  * This is similar to atof(). However, the second token is interpreted as an
122  * MKS units string and a conversion factor to MKS is applied.
123  *
124  * Example: "1.0 atm" results in the number 1.01325e5.
125  *
126  * @param strSI string to be converted. One or two tokens
127  * @returns a converted double
128  */
129 doublereal strSItoDbl(const std::string& strSI);
130 
131 //! This function separates a string up into tokens according to the location of
132 //! white space.
133 /*!
134  * White space includes the new line character. tokens are stripped of leading
135  * and trailing white space.
136  *
137  * The separate tokens are returned in a string vector, v.
138  *
139  * @param oval String to be broken up
140  * @param v Output vector of tokens.
141  */
142 void tokenizeString(const std::string& oval,
143  std::vector<std::string>& v);
144 
145 //! Copy the contents of a std::string into a char array of a given length
146 /*!
147  * If *length* is less than the size of *source*, the string will be truncated
148  * and the function will return the length of the buffer required to hold
149  * *source*. Otherwise, returns 0.
150  */
151 size_t copyString(const std::string& source, char* dest, size_t length);
152 
153 //! Trim.
154 /*!
155  * Remove all leading and trailing spaces (with default locale).
156  */
157 std::string trimCopy(const std::string &input);
158 
159 //! Convert to lower case.
160 /*!
161  * Convert the given string to lower case (with default locale).
162  */
163 std::string toLowerCopy(const std::string& input);
164 
165 //! Case insensitive equality predicate.
166 /*!
167  * Returns true if and only if all elements in both strings are the same
168  * when compared case insensitively (with default locale).
169  */
170 bool caseInsensitiveEquals(const std::string &input, const std::string &test);
171 
172 }
173 
174 #endif
Wrapper for either system-installed or local headers for fmt.
std::map< std::string, doublereal > compositionMap
Map connecting a string name with a double.
Definition: ct_defs.h:149
doublereal fpValue(const std::string &val)
Translate a string into one doublereal value.
std::string trimCopy(const std::string &input)
Trim.
std::string vec2str(const vector_fp &v, const std::string &fmt, const std::string &sep)
Convert a vector to a string (separated by commas)
Definition: stringUtils.cpp:34
This file contains definitions of terms that are used in internal routines and are unlikely to need m...
void tokenizeString(const std::string &in_val, std::vector< std::string > &v)
This function separates a string up into tokens according to the location of white space...
bool caseInsensitiveEquals(const std::string &input, const std::string &test)
Case insensitive equality predicate.
std::string parseSpeciesName(const std::string &nameStr, std::string &phaseName)
Parse a name string, separating out the phase name from the species name.
size_t copyString(const std::string &source, char *dest, size_t length)
Copy the contents of a std::string into a char array of a given length.
int intValue(const std::string &val)
Translate a string into one integer value.
compositionMap parseCompString(const std::string &ss, const std::vector< std::string > &names)
Parse a composition string into a map consisting of individual key:composition pairs.
Definition: stringUtils.cpp:60
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:157
Definition: fmt.h:29
std::string toLowerCopy(const std::string &input)
Convert to lower case.
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:8
doublereal strSItoDbl(const std::string &strSI)
Interpret one or two token string as a single double.
std::string stripnonprint(const std::string &s)
Strip non-printing characters wherever they are.
Definition: stringUtils.cpp:49
doublereal fpValueCheck(const std::string &val)
Translate a string into one doublereal value, with error checking.