Harmonic Flow Framework (libhffwk)
Cross platform C++ 2D Game Engine Framework
StringUtil.h
Go to the documentation of this file.
1 /*
2  Harmonic Flow Framework
3  Copyright (C) 2014-2018 Andreas Widen <andreas@harmonicflow.org>
4 
5  This software is provided 'as-is', without any express or implied
6  warranty. In no event will the authors be held liable for any damages
7  arising from the use of this software.
8 
9  Permission is granted to anyone to use this software for any purpose,
10  including commercial applications, and to alter it and redistribute it
11  freely, subject to the following restrictions:
12 
13  1. The origin of this software must not be misrepresented; you must not
14  claim that you wrote the original software. If you use this software
15  in a product, an acknowledgment in the product documentation would be
16  appreciated but is not required.
17  2. Altered source versions must be plainly marked as such, and must not be
18  misrepresented as being the original software.
19  3. This notice may not be removed or altered from any source distribution.
20 */
21 #pragma once
22 
23 /** @file
24  * @brief Interface for string related helper methods.
25  */
26 
27 #include "HFDataTypes.h"
28 #include "vector/Vector2.h"
29 #include "platform/Color.h"
30 #include "unicode/UString.h"
31 
32 #include <string.h>
33 #include <vector>
34 #include <istream>
35 #include <locale>
36 #include <list>
37 #include <map>
38 
39 #include <stdlib.h>
40 #include <ctype.h>
41 #include <stdio.h>
42 #include <stdarg.h>
43 #if defined(HF_PLATFORM_LINUX)
44 #include <wctype.h>
45 #endif
46 
47 namespace HFCore
48 {
49  /**
50  * @brief Interface for string related helper methods.
51  */
52  class StringUtil
53  {
54  public:
55  /**
56  * @brief typedef for Vector holding std::string.
57  */
58  typedef std::vector<std::string> StringVector;
59 
60  /**
61  * @brief typedef for Vector holding std::wstring.
62  */
63  typedef std::vector<std::wstring> WStringVector;
64 
65  /**
66  * @brief typedef for Vector holding UString.
67  */
68  typedef std::vector<UString> UStringVector;
69 
70  /**
71  * @brief typedef for Vector holding int32_hf.
72  */
73  typedef std::vector<int32_hf> Int32Vector;
74 
75  /**
76  * @brief typedef for Vector holding fp32_hf.
77  */
78  typedef std::vector<fp32_hf> Float32Vector;
79 
80  /**
81  * @brief typedef for Vector holding fp64_hf.
82  */
83  typedef std::vector<fp64_hf> Float64Vector;
84 
85  /**
86  * @brief typedef for Map for holding std::string pair.
87  */
88  typedef std::map<std::string, std::string> StringMap;
89 
90  /**
91  * @brief typedef for Map for holding std::wstring pair.
92  */
93  typedef std::map<std::wstring, std::wstring> WStringMap;
94 
95  /**
96  * @brief typedef for Map for holding UString pair.
97  */
98  typedef std::map<UString, UString> UStringMap;
99 
100  /**
101  * @brief Tokenize str based on delimitersNotReturned and
102  * delimitersReturned.
103  *
104  * Example code:
105  * @code
106  * HFCore::UString str = "test1=1,test2=2";
107  * HFCore::UString delimNotReturned = ",";
108  * HFCore::UString delimReturned = "=";
109  * HFCore::StringUtil::UStringVector strVec;
110  *
111  * HFCore::StringUtil::tokenize(str, delimNotReturned,
112  * delimReturned, strVec);
113  * // strVec will hold these 6 tokens:
114  * test1
115  * =
116  * 1
117  * test2
118  * =
119  * 2
120  * @endcode
121  *
122  * @param str String to tokenize.
123  * @param delimitersNotReturned Delimiters not to be returned.
124  * @param delimitersReturned Delimiters returned.
125  * @param[out] tokens Vector holding the tokens.
126  */
127  static void tokenize(const UString &str,
128  const UString &delimitersNotReturned,
129  const UString &delimitersReturned,
130  UStringVector &tokens);
131 
132  /**
133  * @brief Tokenize str based on delimiters.
134  *
135  * Example code:
136  * @code
137  * HFCore::UString str = "test1,test2";
138  * HFCore::UString delimiters = ",";
139  * HFCore::StringUtil::UStringVector strVec;
140  *
141  * HFCore::StringUtil::tokenize(str, delimiters, strVec);
142  * // strVec will hold these 2 tokens:
143  * test1
144  * test2
145  * @endcode
146  *
147  * @param str String to tokenize.
148  * @param delimiters Delimiters not to be returned.
149  * @param[out] tokens Vector holding the tokens.
150  */
151  static void tokenize(const UString &str,
152  const UString &delimiters,
153  UStringVector &tokens);
154 
155  /**
156  * @brief Tokenize str based on delimitersNotReturned and
157  * delimitersReturned.
158  *
159  * Example code:
160  * @code
161  * std::string str = "test1=1,test2=2";
162  * std::string delimNotReturned = ",";
163  * std::string delimReturned = "=";
164  * HFCore::StringUtil::StringVector strVec;
165  *
166  * HFCore::StringUtil::tokenize(str, delimNotReturned,
167  * delimReturned, strVec);
168  * // strVec will hold these 6 tokens:
169  * test1
170  * =
171  * 1
172  * test2
173  * =
174  * 2
175  * @endcode
176  *
177  * @param str String to tokenize.
178  * @param delimitersNotReturned Delimiters not to be returned.
179  * @param delimitersReturned Delimiters returned.
180  * @param[out] tokens Vector holding the tokens.
181  */
182  static void tokenize(const std::string &str,
183  const std::string &delimitersNotReturned,
184  const std::string &delimitersReturned,
185  StringVector &tokens);
186 
187  /**
188  * @brief Tokenize str based on delimiters.
189  *
190  * Example code:
191  * @code
192  * std::string str = "test1,test2";
193  * std::string delimiters = ",";
194  * HFCore::StringUtil::StringVector strVec;
195  *
196  * HFCore::StringUtil::tokenize(str, delimiters, strVec);
197  * // strVec will hold these 2 tokens:
198  * test1
199  * test2
200  * @endcode
201  *
202  * @param str String to tokenize.
203  * @param delimiters Delimiters not to be returned.
204  * @param[out] tokens Vector holding the tokens.
205  */
206  static void tokenize(const std::string &str,
207  const std::string &delimiters,
208  StringVector &tokens);
209 
210  /**
211  * @brief Tokenize str based on delimiters.
212  *
213  * Example code:
214  * @code
215  * std::string str = "10,20,30";
216  * std::string delimiters = ",";
217  * HFCore::StringUtil::Int32Vector intVec;
218  *
219  * HFCore::StringUtil::tokenizeInt(str, delimiters, intVec);
220  * // intVec will hold these 3 tokens:
221  * 10
222  * 20
223  * 30
224  * @endcode
225  *
226  * @param str String to tokenize.
227  * @param delimiters Delimiters not to be returned.
228  * @param[out] tokens Vector holding the tokens as integers.
229  */
230  static void tokenizeInt(const std::string &str,
231  const std::string &delimiters,
232  Int32Vector &tokens);
233 
234  /**
235  * @brief Tokenize str based on delimiters.
236  *
237  * Example code:
238  * @code
239  * std::string str = "10.11,20.22,30.314";
240  * std::string delimiters = ",";
241  * HFCore::StringUtil::Float32Vector floatVec;
242  *
243  * HFCore::StringUtil::tokenizeFloat(str, delimiters, floatVec);
244  * // floatVec will hold these 3 tokens:
245  * 10.110000
246  * 20.219999
247  * 30.313999
248  * @endcode
249  *
250  * @param str String to tokenize.
251  * @param delimiters Delimiters not to be returned.
252  * @param[out] tokens Vector holding the tokens as floats.
253  */
254  static void tokenizeFloat(const std::string &str,
255  const std::string &delimiters,
256  Float32Vector &tokens);
257 
258  /**
259  * @brief Parse str and return bool value.
260  *
261  * Example code:
262  * @code
263  * // str should be "true" or "false", otherwise defaultValue
264  * // is returned.
265  * std::string str = "true";
266  * bool val = HFCore::StringUtil::parseBool(str);
267  * @endcode
268  *
269  * @param str String to parse.
270  * @param defaultValue bool default value to use in case str is
271  * invalid.
272  *
273  * @return bool value for parsed str value.
274  */
275  static bool parseBool(const std::string &str, bool defaultValue);
276 
277  /**
278  * @brief Parse str and return float value.
279  *
280  * Example code:
281  * @code
282  * std::string str = "0.22";
283  * fp32_hf val = HFCore::StringUtil::parseFloat(str, 1.0f);
284  * @endcode
285  *
286  * @param str String to parse.
287  * @param defaultValue float default value to use in case str is
288  * empty.
289  *
290  * @return float value for parsed str value.
291  */
292  static fp32_hf parseFloat(const std::string &str, fp32_hf defaultValue);
293 
294  /**
295  * @brief Parse str and return integer value.
296  *
297  * Example code:
298  * @code
299  * std::string str = "2000";
300  * int32_hf val = HFCore::StringUtil::parseInt(str, 1);
301  * @endcode
302  *
303  * @param str String to parse.
304  * @param defaultValue integer default value to use in case str is
305  * empty.
306  *
307  * @return integer value for parsed str value.
308  */
309  static int32_hf parseInt(const std::string &str, int32_hf defaultValue);
310 
311  /**
312  * @brief Parse str and return uint32_hf value.
313  *
314  * Example code:
315  * @code
316  * // str contains individual R,G,B color components.
317  * std::string str = "0,0,255"; // Blue color.
318  * uint32_hf val =
319  * HFCore::StringUtil::parseRGB(str, HFCore::Color::getColorWhite());
320  * // val can easily be converted to Color:
321  * HFCore::Color c = HFCore::Color::fromUint32_LERGBA(val);
322  * @endcode
323  *
324  * @param str String to parse.
325  * @param defaultColor Default Color to use in case parsing fails
326  * or str is empty.
327  *
328  * @return uint32_hf value for parsed str value.
329  *
330  * @see Color::toUint32_LERGBA()
331  * @see Color::fromUint32_LERGBA()
332  */
333  static uint32_hf parseRGB(const std::string &str, Color defaultColor);
334 
335  /**
336  * @brief Parse str and return uint32_hf value.
337  *
338  * Example code:
339  * @code
340  * // str contains individual R,G,B,A color components.
341  * std::string str = "0,0,255,127"; // Blue color ~50% trans.
342  * uint32_hf val =
343  * HFCore::StringUtil::parseRGBA(str, HFCore::Color::getColorWhite());
344  * // val can easily be converted to Color:
345  * HFCore::Color c = HFCore::Color::fromUint32_LERGBA(val);
346  * @endcode
347  *
348  * @param str String to parse.
349  * @param defaultColor Default Color to use in case parsing fails
350  * or str is empty.
351  *
352  * @return uint32_hf value for parsed str value.
353  *
354  * @see Color::toUint32_LERGBA()
355  * @see Color::fromUint32_LERGBA()
356  */
357  static uint32_hf parseRGBA(const std::string &str, Color defaultColor);
358 
359  /**
360  * @brief Parse str and return uint32_hf value.
361  *
362  * Example code:
363  * @code
364  * // str contains individual B,G,R color components.
365  * std::string str = "255,0,0"; // Blue color.
366  * uint32_hf val =
367  * HFCore::StringUtil::parseBGR(str, HFCore::Color::getColorWhite());
368  * // val can easily be converted to Color:
369  * HFCore::Color c = HFCore::Color::fromUint32_LEBGRA(val);
370  * @endcode
371  *
372  * @param str String to parse.
373  * @param defaultColor Default Color to use in case parsing fails
374  * or str is empty.
375  *
376  * @return uint32_hf value for parsed str value.
377  *
378  * @see Color::toUint32_LEBGRA()
379  * @see Color::fromUint32_LEBGRA()
380  */
381  static uint32_hf parseBGR(const std::string &str, Color defaultColor);
382 
383  /**
384  * @brief Parse str and return uint32_hf value.
385  *
386  * Example code:
387  * @code
388  * // str contains individual B,G,R,A color components.
389  * std::string str = "255,0,0,127"; // Blue color ~50% trans.
390  * uint32_hf val =
391  * HFCore::StringUtil::parseBGRA(str, HFCore::Color::getColorWhite());
392  * // val can easily be converted to Color:
393  * HFCore::Color c = HFCore::Color::fromUint32_LEBGRA(val);
394  * @endcode
395  *
396  * @param str String to parse.
397  * @param defaultColor Default Color to use in case parsing fails
398  * or str is empty.
399  *
400  * @return uint32_hf value for parsed str value.
401  *
402  * @see Color::toUint32_LEBGRA()
403  * @see Color::fromUint32_LEBGRA()
404  */
405  static uint32_hf parseBGRA(const std::string &str, Color defaultColor);
406 
407  /**
408  * @brief Parse str and set values in vec.
409  *
410  * Example code:
411  * @code
412  * // str contains vector x and y float values:
413  * std::string str = "10.22,11.78";
414  * HFCore::Vector2 vec(0.0f, 0.0f);
415  * HFCore::StringUtil::parseVector2(str, vec);
416  * @endcode
417  *
418  * @param str String to parse.
419  * @param[out] vec Vector2 holding parsed str float values.
420  */
421  static void parseVector2(const std::string &str, Vector2 &vec);
422 
423  /**
424  * @brief Trim string left and right.
425  *
426  * @code
427  * std::string str = " CupTea ";
428  * // strTrimmed will be "CupTea":
429  * std::string strTrimmed = HFCore::StringUtil::trim(str);
430  * @endcode
431  *
432  * @param str String to trim.
433  *
434  * @return Trimmed string.
435  */
436  static std::string trim(const std::string &str);
437 
438  /**
439  * @brief Skip until reaching delimChars.
440  *
441  * @param is String stream.
442  * @param delimChars Delimiters to skip until.
443  *
444  * @return Character at current position.
445  */
446  static int8_hf skipUntil(std::istream &is, const std::string &delimChars);
447 
448  /**
449  * @brief Skip until reaching delimChar.
450  *
451  * @param is String stream.
452  * @param delimChar Delimiter to skip until.
453  */
454  static void skipUntil(std::istream &is, int32_hf delimChar);
455 
456  /**
457  * @brief Skip skipChar on current stream position if any.
458  *
459  * @param is String stream.
460  * @param skipChar Character to skip.
461  */
462  static void skip(std::istream &is, int32_hf skipChar);
463 
464  /**
465  * @brief Read until reaching delimiter/s.
466  *
467  * @param is String stream.
468  * @param[out] buffer Buffer to hold characters read until
469  * delimiter/s.
470  * @param delimChars Delimiters to read until.
471  * @param respectEscapeChar true to respect ESCAPE char ("\\"),
472  * false otherwise.
473  *
474  * @return Character at current position.
475  */
476  static int8_hf readUntil(std::istream &is, std::string &buffer, const int8_hf *delimChars,
477  bool respectEscapeChar = false);
478 
479  /**
480  * @brief Convert string to uppercase.
481  *
482  * @param string String to convert.
483  *
484  * @return Uppercase string.
485  */
486  static std::string StringToUpper(const std::string &string);
487 
488  /**
489  * @brief Convert string to uppercase.
490  *
491  * @param string String to convert.
492  *
493  * @return Uppercase string.
494  */
495  static std::wstring StringToUpper(const std::wstring &string);
496 
497  /**
498  * @brief Convert string to lowercase.
499  *
500  * @param string String to convert.
501  *
502  * @return Lowercase string.
503  */
504  static std::string StringToLower(const std::string &string);
505 
506  /**
507  * @brief Convert string to lowercase.
508  *
509  * @param string String to convert.
510  *
511  * @return Lowercase string.
512  */
513  static std::wstring StringToLower(const std::wstring &string);
514 
515  /**
516  * @brief Convert std::string to std::wstring.
517  *
518  * @param string String to convert.
519  *
520  * @return Converted string.
521  */
522  static std::wstring StringToWString(const std::string &string);
523 
524 #if defined(HF_PLATFORM_ANDROID)
525  static size_t wcstombs(int8_hf *s, const wchar_t *pwcs, size_t n);
526 #endif
527 
528  /**
529  * @brief Convert std::wstring to std::string.
530  *
531  * @param string String to convert.
532  *
533  * @return Converted string.
534  */
535  static std::string WStringToString(const std::wstring &string);
536 
537  /**
538  * @brief Determine whether a UString contains only spaces.
539  *
540  * @param str UString to check.
541  *
542  * @return true if only spaces, false otherwise.
543  */
544  static bool UStringContainsOnlySpaces(const UString &str);
545 
546  /**
547  * @brief Extract file name from path with or without extension.
548  *
549  * @code
550  * std::string str = "/home/username/temp/test.ogg";
551  * // file1 = 'test.ogg':
552  * std::string file1 =
553  * HFCore::StringUtil::extractFileNameFromPath(str, false);
554  * // file2 = 'test':
555  * std::string file2 =
556  * HFCore::StringUtil::extractFileNameFromPath(str, true);
557  * @endcode
558  *
559  * @param path Full file name path.
560  * @param noExtension true to <b>not</b> include file name
561  * extension, false otherwise.
562  *
563  * @return File name with or without extension.
564  */
565  static std::string extractFileNameFromPath(const std::string &path, bool noExtension);
566 
567  /**
568  * @brief Extract file directory from path with or without last
569  * slash.
570  *
571  * @code
572  * std::string str = "/home/username/temp/test.ogg";
573  * // dir1 = '/home/username/temp':
574  * std::string dir1 =
575  * HFCore::StringUtil::extractFileDirFromPath(str, false);
576  * // dir2 = '/home/username/temp/':
577  * std::string dir2 =
578  * HFCore::StringUtil::extractFileDirFromPath(str, true);
579  * @endcode
580  *
581  * @param path Full file name path.
582  * @param withSlash true to include last slash, false otherwise.
583  *
584  * @return File directory path with or without last slash.
585  */
586  static std::string extractFileDirFromPath(const std::string &path, bool withSlash);
587 
588  /**
589  * @brief 'stricmp' std lib wrapper. Compare two strings.
590  *
591  * @param pStr1 String 1
592  * @param pStr2 String 2
593  *
594  * @return Return an integer less than, equal to, or greater than
595  * zero if pStr1 (or the first n bytes thereof) is found,
596  * respectively, to be less than, to match, or be greater than
597  * pStr2.
598  */
599  static int32_hf stricmp(const int8_hf *pStr1, const int8_hf *pStr2);
600  };
601 }
static int8_hf skipUntil(std::istream &is, const std::string &delimChars)
Skip until reaching delimChars.
Definition: StringUtil.cpp:332
unsigned int uint32_hf
A type definition for unsigned int.
Definition: HFDataTypes.h:354
static int32_hf parseInt(const std::string &str, int32_hf defaultValue)
Parse str and return integer value.
Definition: StringUtil.cpp:222
std::map< UString, UString > UStringMap
typedef for Map for holding UString pair.
Definition: StringUtil.h:98
static std::string extractFileNameFromPath(const std::string &path, bool noExtension)
Extract file name from path with or without extension.
Definition: StringUtil.cpp:518
Interface for unicode string class UString.
Definition: UString.h:35
static uint32_hf parseRGBA(const std::string &str, Color defaultColor)
Parse str and return uint32_hf value.
Definition: StringUtil.cpp:247
int int32_hf
A type definition for int.
Definition: HFDataTypes.h:349
static std::wstring StringToWString(const std::string &string)
Convert std::string to std::wstring.
Definition: StringUtil.cpp:482
static int8_hf readUntil(std::istream &is, std::string &buffer, const int8_hf *delimChars, bool respectEscapeChar=false)
Read until reaching delimiter/s.
Definition: StringUtil.cpp:403
Interface for string related helper methods.
Definition: StringUtil.h:52
static std::string trim(const std::string &str)
Trim string left and right.
Definition: StringUtil.cpp:319
std::map< std::wstring, std::wstring > WStringMap
typedef for Map for holding std::wstring pair.
Definition: StringUtil.h:93
std::vector< UString > UStringVector
typedef for Vector holding UString.
Definition: StringUtil.h:68
Framework data types, defines, typedef&#39;s, enum and structs.
std::vector< fp32_hf > Float32Vector
typedef for Vector holding fp32_hf.
Definition: StringUtil.h:78
static void parseVector2(const std::string &str, Vector2 &vec)
Parse str and set values in vec.
Definition: StringUtil.cpp:307
static uint32_hf parseBGRA(const std::string &str, Color defaultColor)
Parse str and return uint32_hf value.
Definition: StringUtil.cpp:287
static void tokenizeFloat(const std::string &str, const std::string &delimiters, Float32Vector &tokens)
Tokenize str based on delimiters.
Definition: StringUtil.cpp:183
static std::string StringToLower(const std::string &string)
Convert string to lowercase.
Definition: StringUtil.cpp:462
static void tokenize(const UString &str, const UString &delimitersNotReturned, const UString &delimitersReturned, UStringVector &tokens)
Tokenize str based on delimitersNotReturned and delimitersReturned.
Definition: StringUtil.cpp:30
A two-dimensional floating point vector and associated math functions.
Definition: Vector2.h:42
static uint32_hf parseBGR(const std::string &str, Color defaultColor)
Parse str and return uint32_hf value.
Definition: StringUtil.cpp:267
static bool UStringContainsOnlySpaces(const UString &str)
Determine whether a UString contains only spaces.
Definition: StringUtil.cpp:498
Interface for RGBA Color.
Definition: Color.h:51
char int8_hf
A type definition for char.
Definition: HFDataTypes.h:329
Interface for unicode string class UString.
std::map< std::string, std::string > StringMap
typedef for Map for holding std::string pair.
Definition: StringUtil.h:88
static fp32_hf parseFloat(const std::string &str, fp32_hf defaultValue)
Parse str and return float value.
Definition: StringUtil.cpp:212
static void skip(std::istream &is, int32_hf skipChar)
Skip skipChar on current stream position if any.
Definition: StringUtil.cpp:380
std::vector< fp64_hf > Float64Vector
typedef for Vector holding fp64_hf.
Definition: StringUtil.h:83
static bool parseBool(const std::string &str, bool defaultValue)
Parse str and return bool value.
Definition: StringUtil.cpp:196
static void tokenizeInt(const std::string &str, const std::string &delimiters, Int32Vector &tokens)
Tokenize str based on delimiters.
Definition: StringUtil.cpp:170
A two-dimensional floating point vector and associated math functions.
Interface for RGBA Color.
std::vector< int32_hf > Int32Vector
typedef for Vector holding int32_hf.
Definition: StringUtil.h:73
Definition: Actor.h:34
std::vector< std::string > StringVector
typedef for Vector holding std::string.
Definition: StringUtil.h:58
static uint32_hf parseRGB(const std::string &str, Color defaultColor)
Parse str and return uint32_hf value.
Definition: StringUtil.cpp:227
static std::string StringToUpper(const std::string &string)
Convert string to uppercase.
Definition: StringUtil.cpp:442
static std::string extractFileDirFromPath(const std::string &path, bool withSlash)
Extract file directory from path with or without last slash.
Definition: StringUtil.cpp:535
static int32_hf stricmp(const int8_hf *pStr1, const int8_hf *pStr2)
&#39;stricmp&#39; std lib wrapper. Compare two strings.
Definition: StringUtil.cpp:550
static std::string WStringToString(const std::wstring &string)
Convert std::wstring to std::string.
Definition: StringUtil.cpp:490
std::vector< std::wstring > WStringVector
typedef for Vector holding std::wstring.
Definition: StringUtil.h:63
float fp32_hf
A type definition for float.
Definition: HFDataTypes.h:359