Harmonic Flow Framework (libhffwk)
Cross platform C++ 2D Game Engine Framework
UString.h
Go to the documentation of this file.
1 /*
2  Harmonic Flow Framework
3  Copyright (C) 2011-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 unicode string class UString.
25  */
26 
27 #include "HFDataTypes.h"
28 #include "debug/CrtDbgInc.h"
29 
30 namespace HFCore
31 {
32  /**
33  * @brief Interface for unicode string class UString.
34  */
35  class UString
36  {
37  public:
38  /**
39  * @brief Constructor.
40  */
41  UString();
42 
43  /**
44  * @brief Constructor.
45  *
46  * @param str unicode widechar string.
47  */
48  UString(const wchar_t *str);
49 
50  /**
51  * @brief Constructor.
52  *
53  * @param utf8 utf8 encoded string.
54  */
55  UString(const int8_hf *utf8);
56 
57  /**
58  * @brief Constructor.
59  *
60  * @param ustr UString string.
61  */
62  UString(const UString &ustr);
63 
64  /**
65  * @brief Destructor.
66  */
67  virtual ~UString();
68 
69  /**
70  * @brief Format a string.
71  *
72  * @code
73  * HFCore::UString str = "TransformationOfMan";
74  * HFCore::UString formattedStr =
75  * HFCore::UString::format("str: %s, str len: %d",
76  * str.toUtf8(), str.length());
77  * envDebugLog("formattedStr '%s'.\r\n", formattedStr.toUtf8());
78  *
79  * @endcode
80  *
81  * @param utf8format Format string (example: "string: %s int:
82  * %d" etc).
83  * @param ... Parameter list (0-n based on format string).
84  *
85  * @return Formatted UString accourding to format string.
86  */
87  static UString format(const int8_hf *utf8format, ...);
88 
89  /**
90  * @brief Get the length of the string.
91  *
92  * @return Length of the string.
93  */
94  int32_hf length() const;
95 
96  /**
97  * @brief Get the utf8 encoded string.
98  *
99  * @return utf8 encoded string.
100  */
101  const int8_hf *toUtf8() const;
102 
103  /**
104  * @brief Create string from utf8 encoded string.
105  *
106  * @param utf8 utf8 encoded string.
107  *
108  * @return Length of string created.
109  */
110  int32_hf fromUtf8(const int8_hf *utf8);
111 
112  /**
113  * @brief Get the unicode widechar string.
114  *
115  * @return Unicode widechar string.
116  *
117  * @note May return NULL for empty strings.
118  */
119  const wchar_t *wc_str() const; // WARNING: may return NULL for empty strings
120 
121  /**
122  * @brief Get a substring from offset to charCount.
123  *
124  * @code
125  * HFCore::UString str = "TransformationOfMan";
126  * HFCore::UString subStr = str.substr(16);
127  * // subStr = "Man":
128  * envDebugLog("subStr is '%s'.\r\n", subStr.toUtf8());
129  * @endcode
130  *
131  * @param offset Offset for substring.
132  * @param charCount Char count from offset (-1 means get the rest
133  * of the string from offset).
134  *
135  * @return Substring from offset to charcount.
136  */
137  UString substr(int32_hf offset, int32_hf charCount = -1) const;
138 
139  /**
140  * @brief Find a char and return it's index if found or -1 if not.
141  *
142  * @code
143  * HFCore::UString str = "TransformationOfMan";
144  * // chIdx will be 5:
145  * int32_hf chIdx = str.findChar(L'f');
146  * @endcode
147  *
148  * @param ch unicode widechar to find.
149  * @param start Start index to use in find loop.
150  * @param respectEscapeChars true to respect ESCAPE char ("\\"),
151  * false otherwise.
152  *
153  * @return Index of found ch or -1 if not found.
154  */
155  int32_hf findChar(wchar_t ch, int32_hf start = 0, bool respectEscapeChars = false) const;
156 
157  /**
158  * @brief Find a char from str and return the index of the first
159  * found character or -1 if not found.
160  *
161  * @code
162  * HFCore::UString str = "TransformationOfMan";
163  * // chIdx will be 2 as it finds 'a' before 'n':
164  * int32_hf chIdx = str.findChar("na");
165  * @endcode
166  *
167  * @param str UString string to find first character index from.
168  * @param start Start index to use in find loop.
169  * @param respectEscapeChars true to respect ESCAPE char ("\\"),
170  * false otherwise.
171  *
172  * @return Index of first found ch from str or -1 if not found.
173  */
174  int32_hf findChar(const UString &str, int32_hf start = 0,
175  bool respectEscapeChars = false) const;
176 
177  /**
178  * @brief Find first index matching str or -1 if not found.
179  *
180  * @code
181  * HFCore::UString str = "TransformationOfMan";
182  * // chIdx will be 16: ("Man" is found in str and "M" is at
183  * // index 16).
184  * int32_hf chIdx = str.find("Man");
185  * @endcode
186  *
187  * @param str UString string to find.
188  * @param start Start index to use in find loop.
189  *
190  * @return First index matching str or -1 if not found.
191  */
192  int32_hf find(const UString &str, int32_hf start = 0) const;
193 
194  /**
195  * @brief Append str to internal string.
196  *
197  * @code
198  * HFCore::UString str = "TransformationOfMan";
199  * // str will be "TransformationOfMan_Appended":
200  * str.append("_Appended");
201  * @endcode
202  *
203  * @param str UString string to append.
204  */
205  void append(const UString &str);
206 
207  /**
208  * @brief Insert str at offset position.
209  *
210  * @code
211  * HFCore::UString str = "CupTea";
212  * // str will be "CupOfTea":
213  * str.insert(3, "Of");
214  * @endcode
215  *
216  * @param offset Offset position.
217  * @param str UString string to insert.
218  */
219  void insert(int32_hf offset, const UString &str);
220 
221  /**
222  * @brief Insert ch at offset position.
223  *
224  * @code
225  * HFCore::UString str = "CupTea";
226  * // str will be "CupTeas":
227  * str.insert(6, L's');
228  * @endcode
229  *
230  * @param offset Offset position.
231  * @param ch wchar_t character to insert.
232  */
233  void insert(int32_hf offset, wchar_t ch);
234 
235  /**
236  * @brief Erase count character/s at offset position.
237  *
238  * @code
239  * HFCore::UString str = "CupTea";
240  * // str will be "Cup":
241  * str.erase(3, 3);
242  * @endcode
243  *
244  * @param offset Offset position.
245  * @param count Number of characters to erase.
246  */
247  void erase(int32_hf offset, int32_hf count);
248 
249  /**
250  * @brief Clear string and free memory used internally.
251  */
252  void clear();
253 
254  /**
255  * @brief Determine if string has Ascii only characters.
256  *
257  * @return true if string has Ascii only characters, else false.
258  */
259  bool isAsciiOnly();
260 
261  /**
262  * @brief Collapse / remove ESCAPE CHAR's ("\\").
263  */
264  void collapseEscapes();
265 
266  /**
267  * @brief Trim string left and right.
268  *
269  * @code
270  * HFCore::UString str = " CupTea ";
271  * // strTrimmed will be "CupTea":
272  * HFCore::UString strTrimmed = str.trim();
273  * @endcode
274  *
275  * @return Trimmed string.
276  */
277  UString trim();
278 
279  /**
280  * @brief Convert string to float.
281  *
282  * @return Converted string to float.
283  */
284  fp32_hf toFloat() const;
285 
286  /**
287  * @brief Overload of subscript operator [].
288  *
289  * This operator returns wchar_t character at given index.
290  *
291  * @param index Subscript index.
292  *
293  * @return wchar_t character at current index.
294  */
295  wchar_t operator [](int32_hf index) const;
296 
297  /**
298  * @brief Overload of binary operator =.
299  *
300  * This operator assign *this the value of ustr.
301  *
302  * @param ustr UString to assign to *this.
303  *
304  * @return *this assigned the value of ustr.
305  */
306  UString &operator = (const UString &ustr);
307 
308  /**
309  * @brief Overload of binary operator ==.
310  *
311  * This operator compares strict equality between two UString's.
312  *
313  * @param ustr UString to compare against *this.
314  *
315  * @return true if equal, else false.
316  */
317  bool operator == (const UString &ustr) const;
318 
319  /**
320  * @brief Overload of binary operator !=.
321  *
322  * This operator compares strict difference between two
323  * UString's.
324  *
325  * @param ustr UString to compare against *this.
326  *
327  * @return true if not equal, else false.
328  */
329  bool operator != (const UString &ustr) const;
330 
331  /**
332  * @brief Overload of operator < (less than).
333  *
334  * This operator compares two UString's and returns true if *this
335  * < ustr per character or in length.
336  *
337  * @param ustr UString to compare against *this.
338  *
339  * @return true if *this < ustr per character or in length.
340  */
341  bool operator < (const UString &ustr) const;
342 
343  private:
344  int32_hf decode(const int8_hf *utf8, wchar_t *unicode);
345  int32_hf encode(const wchar_t *unicode, int32_hf length, int8_hf *utf8,
346  bool *isAsciiOnly) const;
347  wchar_t getCodePoint(const int8_hf *utf8, int32_hf offset, int32_hf numBytes,
348  uint8_hf firstByteMask);
349  void getUtf8(wchar_t ch, int8_hf *utf8, int32_hf numBytes,
350  int32_hf firstByteValue) const;
351  void updateUtf8();
352 
353  private:
354  wchar_t *mUnicode;
355  int8_hf *mUtf8;
356  int32_hf mLength;
357  bool mIsAsciiOnly;
358  };
359 }
int32_hf findChar(wchar_t ch, int32_hf start=0, bool respectEscapeChars=false) const
Find a char and return it&#39;s index if found or -1 if not.
Definition: UString.cpp:469
void erase(int32_hf offset, int32_hf count)
Erase count character/s at offset position.
Definition: UString.cpp:533
Interface for unicode string class UString.
Definition: UString.h:35
int int32_hf
A type definition for int.
Definition: HFDataTypes.h:349
bool operator!=(const UString &ustr) const
Overload of binary operator !=.
Definition: UString.cpp:331
UString & operator=(const UString &ustr)
Overload of binary operator =.
Definition: UString.cpp:301
Framework data types, defines, typedef&#39;s, enum and structs.
const wchar_t * wc_str() const
Get the unicode widechar string.
Definition: UString.cpp:579
bool operator<(const UString &ustr) const
Overload of operator < (less than).
Definition: UString.cpp:347
UString substr(int32_hf offset, int32_hf charCount=-1) const
Get a substring from offset to charCount.
Definition: UString.cpp:183
void collapseEscapes()
Collapse / remove ESCAPE CHAR&#39;s ("\\").
Definition: UString.cpp:690
int32_hf length() const
Get the length of the string.
Definition: UString.cpp:178
const int8_hf * toUtf8() const
Get the utf8 encoded string.
Definition: UString.cpp:574
char int8_hf
A type definition for char.
Definition: HFDataTypes.h:329
void clear()
Clear string and free memory used internally.
Definition: UString.cpp:560
int32_hf find(const UString &str, int32_hf start=0) const
Find first index matching str or -1 if not found.
Definition: UString.cpp:519
void append(const UString &str)
Append str to internal string.
Definition: UString.cpp:365
bool isAsciiOnly()
Determine if string has Ascii only characters.
Definition: UString.cpp:731
wchar_t operator[](int32_hf index) const
Overload of subscript operator [].
Definition: UString.cpp:209
fp32_hf toFloat() const
Convert string to float.
Definition: UString.cpp:569
Definition: Actor.h:34
bool operator==(const UString &ustr) const
Overload of binary operator ==.
Definition: UString.cpp:337
UString trim()
Trim string left and right.
Definition: UString.cpp:736
void insert(int32_hf offset, const UString &str)
Insert str at offset position.
Definition: UString.cpp:396
UString()
Constructor.
Definition: UString.cpp:49
int32_hf fromUtf8(const int8_hf *utf8)
Create string from utf8 encoded string.
Definition: UString.cpp:138
unsigned char uint8_hf
A type definition for unsigned char.
Definition: HFDataTypes.h:334
virtual ~UString()
Destructor.
Definition: UString.cpp:88
static UString format(const int8_hf *utf8format,...)
Format a string.
Definition: UString.cpp:94
float fp32_hf
A type definition for float.
Definition: HFDataTypes.h:359