NXWidgets: cnxstring.hxx Source File

NXWidgets 1.19

cnxstring.hxx
Go to the documentation of this file.
1 /****************************************************************************
2 * include/cnxtring.hxx
3 * NxWidgets/libnxwidgets/
4 *
5 * Copyright (C) 2012 Gregory Nutt. All rights reserved.
6 * Author: Gregory Nutt <gnutt@nuttx.org>
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
17 * distribution.
18 * 3. Neither the name NuttX, NxWidgets, nor the names of its contributors
19 * me be used to endorse or promote products derived from this software
20 * without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
25 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
26 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
27 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
29 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
30 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 * POSSIBILITY OF SUCH DAMAGE.
34 *
35 ****************************************************************************
36 *
37 * Portions of this package derive from Woopsi (http://woopsi.org/) and
38 * portions are original efforts. It is difficult to determine at this
39 * point what parts are original efforts and which parts derive from Woopsi.
40 * However, in any event, the work of Antony Dzeryn will be acknowledged
41 * in most NxWidget files. Thanks Antony!
42 *
43 * Copyright (c) 2007-2011, Antony Dzeryn
44 * All rights reserved.
45 *
46 * Redistribution and use in source and binary forms, with or without
47 * modification, are permitted provided that the following conditions are met:
48 *
49 * * Redistributions of source code must retain the above copyright
50 * notice, this list of conditions and the following disclaimer.
51 * * Redistributions in binary form must reproduce the above copyright
52 * notice, this list of conditions and the following disclaimer in the
53 * documentation and/or other materials provided with the distribution.
54 * * Neither the names "Woopsi", "Simian Zombie" nor the
55 * names of its contributors may be used to endorse or promote products
56 * derived from this software without specific prior written permission.
57 *
58 * THIS SOFTWARE IS PROVIDED BY Antony Dzeryn ``AS IS'' AND ANY
59 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
60 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
61 * DISCLAIMED. IN NO EVENT SHALL Antony Dzeryn BE LIABLE FOR ANY
62 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
63 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
64 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
65 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
66 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
67 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
68 *
69 ****************************************************************************/
70
71 #ifndef __INCLUDE_CNXSTRING_HXX
72 #define __INCLUDE_CNXSTRING_HXX
73
74 /****************************************************************************
75 * Included Files
76 ****************************************************************************/
77
78 #include <nuttx/config.h>
79
80 #include <sys/types.h>
81 #include <stdint.h>
82 #include <stdbool.h>
83
84 #include "nxconfig.hxx"
85
86 /****************************************************************************
87 * Pre-Processor Definitions
88 ****************************************************************************/
89
90 /****************************************************************************
91 * Implementation Classes
92 ****************************************************************************/
93
94 #if defined(__cplusplus)
95
96 namespace NXWidgets
97 {
98 class CStringIterator;
99
100 /**
101 * Unicode string class. Uses 16-bt wide-character encoding. For optimal
102 * performance, use the CStringIterator class to iterate over a CNxString
103 * instance.
104 *
105 * Where possible, the string avoids allocating memory each time the
106 * string grows or shrinks. This means that the string may consume more
107 * memory than the number of chars would seem to dictate if the object
108 * previously contained a large string that has subsequently been truncated.
109 * It also means that increasing the length of such a string is a cheaper
110 * operation as memory does not need to allocated and copied.
111 *
112 * Additionally, the string increases its array size by m_growAmount every
113 * time it needs to allocate extra memory, potentially reducing the number
114 * of reallocs needed.
115 *
116 * The string is not null-terminated. Instead, it uses a m_stringLength
117 * member that stores the number of characters in the string. This saves a
118 * byte and makes calls to getLength() run in O(1) time instead of O(n).
119 */
120
121 class CNxString
122 {
123 private:
124 friend class CStringIterator;
125
126 int m_stringLength; /**< Number of characters in the string */
127 int m_allocatedSize; /**< Number of bytes allocated for this string */
128 int m_growAmount; /**< Number of chars that the string grows by
129 whenever it needs to get larger */
130
131
132 protected:
133 FAR nxwidget_char_t *m_text; /**< Raw char array data */
134
135 /**
136 * Allocate memory for the string.
137 *
138 * @param chars Number of chars to allocate.
139 * @param preserve If true, the data in the existing memory will be
140 * preserved if new memory must be allocated
141 */
142
143 void allocateMemory(int chars, bool preserve);
144
145 /**
146 * Check if we've got any string data stored or not.
147 *
148 * @return True if the string contains any data; false if no data has
149 * yet been supplied.
150 */
151
152 inline bool hasData(void) const
153 {
154 return m_stringLength > 0;
155 }
156
157 /**
158 * Get the amount of allocated memory.
159 *
160 * @return The number of chars allocated in RAM.
161 */
162
163 inline int getAllocatedSize(void) const
164 {
165 return m_allocatedSize;
166 }
167
168 /**
169 * Returns a pointer to the raw char array data.
170 *
171 * @return Pointer to the char array.
172 */
173
174 inline FAR const nxwidget_char_t *getCharArray(void) const
175 {
176 return m_text;
177 }
178
179 /**
180 * Return a pointer to the specified character.
181 *
182 * @param index Index of the character to retrieve.
183 */
184
185 FAR nxwidget_char_t *getCharPointer(const int index) const;
186
187 public:
188
189 /**
190 * Constructor to create an empty string object.
191 */
192
193 CNxString();
194
195 /**
196 * Constructor to create a string from a C character array.
197 *
198 * @param text Pointer to a char array to use as the basis of the
199 * string.
200 */
201
202 CNxString(FAR const char *text);
203
204 /**
205 * Constructor to create a string from a single character.
206 *
207 * @param letter Single character to use as the basis of the string.
208 */
209
210 CNxString(const nxwidget_char_t letter);
211
212 /**
213 * Copy constructor.
214 * @param string CNxString object to create a copy of.
215 */
216
217 CNxString(const CNxString &string);
218
219 /**
220 * Destructor.
221 */
222
223 virtual inline ~CNxString()
224 {
225 delete[] m_text;
226 m_text = (FAR nxwidget_char_t *)NULL;
227 };
228
229 /**
230 * Creates and returns a new CStringIterator object that will iterate
231 * over this string. The object must be manually deleted once it is
232 * no longer needed.
233 *
234 * @return A new CStringIterator object.
235 */
236
237 CStringIterator *newStringIterator(void) const;
238
239 /**
240 * Copy the internal array to the supplied buffer. The buffer must be
241 * large enough to contain the full text in the string. The
242 * getAllocSize() method can be used to obtain the length of the string.
243 * Unlike the CNxString class, the char array is null-terminated.
244 * The buffer must be (getAllocSize() + 1) bytes long, in order to
245 * accommodate the terminator.
246 *
247 * @param buffer Buffer to copy the internal char array to.
248 */
249
250 void copyToCharArray(FAR nxwidget_char_t *buffer) const;
251
252 /**
253 * Set the text in the string.
254 *
255 * @param text CNxString containing the new data for this string.
256 */
257
258 void setText(const CNxString &text);
259
260 /**
261 * Set the text in the string.
262 *
263 * @param text Char array to use as the new data for this string.
264 */
265
266 void setText(FAR const char *text);
267
268 /**
269 * Set the nxwidget_char_t text in the string.
270 *
271 * @param text Char array to use as the new data for this string.
272 */
273
274 void setText(FAR const nxwidget_char_t *text, int nchars);
275
276 /**
277 * Set the 8-bit C-string text in the string.
278 *
279 * @param text Character to to use as the new data for this string.
280 */
281
282 void setText(const nxwidget_char_t text);
283
284 /**
285 * Append text to the end of the string.
286 *
287 * @param text String to append.
288 */
289
290 void append(const CNxString &text);
291
292 /**
293 * Insert text at the specified character index.
294 *
295 * @param text The text to insert.
296 * @param index The index at which to insert the text.
297 */
298
299 void insert(const CNxString &text, const int index);
300
301 /**
302 * Remove all characters from the string from the start index onwards.
303 *
304 * @param startIndex Index to remove from.
305 */
306
307 void remove(const int startIndex);
308
309 /**
310 * Remove specified number of characters from the string from the
311 * start index onwards.
312 *
313 * @param startIndex Index to remove from.
314 * @param count Number of characters to remove.
315 */
316
317 void remove(const int startIndex, const int count);
318
319 /**
320 * Get the of number of letters (ie. the length) of the string.
321 *
322 * @return The length of the string.
323 */
324
325 inline const unsigned int getLength(void) const
326 {
327 return m_stringLength;
328 };
329
330 /**
331 * Get the size of a buffer (in bytes) required in order to copy the
332 * internal string into an the array. This is normally used in
333 * conjunction with copyToCharArray(). Note that the returned size
334 * includes additional byte(s) to hold NUL termination.
335 */
336
337 inline const unsigned int getAllocSize(void) const
338 {
339 return sizeof(nxwidget_char_t) * (m_stringLength + 1);
340 }
341
342 /**
343 * Get the character at the specified index. This function is useful
344 * for finding the occasional character at an index, but for iterating
345 * over strings it is exceptionally slow. The newStringIterator()
346 * method should be used to retrieve an iterator object that can iterate
347 * over the string efficiently.
348 *
349 * @param index The index of the character to retrieve.
350 * @return The character at the specified index.
351 */
352
353 const nxwidget_char_t getCharAt(int index) const;
354
355 /**
356 * Returns the first index of the specified letter within the string.
357 * Will return -1 if the letter is not found.
358 *
359 * @param letter Letter to find.
360 * @return The index of the letter.
361 */
362
363 const int indexOf(nxwidget_char_t letter) const;
364
365 /**
366 * Returns the first index of the specified letter within the string.
367 * Will return -1 if the letter is not found. Scans through the string
368 * from "startIndex" until it has examined all subsequent letters.
369 * @param letter Letter to find.
370 *
371 * @param startIndex The index to start searching from.
372 * @return The index of the letter.
373 */
374
375 const int indexOf(nxwidget_char_t letter, int startIndex) const;
376
377 /**
378 * Returns the first index of the specified letter within the string.
379 * Will return -1 if the letter is not found. Scans through the string
380 * from "startIndex" until it has examined all letters within the
381 * range "count".
382 *
383 * @param letter Letter to find.
384 * @param startIndex The index to start searching from.
385 * @param count The number of characters to examine.
386 * @return The index of the letter.
387 */
388
389 const int indexOf(nxwidget_char_t letter, int startIndex, int count) const;
390
391 /**
392 * Returns the last index of the specified letter within the string.
393 * Will return -1 if the letter is not found.
394 *
395 * @param letter Letter to find.
396 * @return The index of the letter.
397 */
398
399 const int lastIndexOf(nxwidget_char_t letter) const;
400
401 /**
402 * Returns the last index of the specified letter within the string.
403 * Will return -1 if the letter is not found. Scans through the string
404 * backwards from "startIndex" until it has examined all preceding
405 * letters within the string.
406 *
407 * @param letter Letter to find.
408 * @param startIndex The index to start searching from.
409 * @return The index of the letter.
410 */
411
412 const int lastIndexOf(nxwidget_char_t letter, int startIndex) const;
413
414 /**
415 * Returns the last index of the specified letter within the string.
416 * Will return -1 if the letter is not found. Scans through the string
417 * backwards from "startIndex" until it has examined all letters within
418 * the range "count".
419 * @param letter Letter to find.
420 * @param startIndex The index to start searching from.
421 * @param count The number of characters to examine.
422 * @return The index of the letter.
423 */
424
425 const int lastIndexOf(nxwidget_char_t letter, int startIndex, int count) const;
426
427 /**
428 * Get a substring from this string. It is the responsibility of the
429 * caller to delete the substring when it is no longer required.
430 *
431 * @param startIndex The starting point of the substring.
432 * @return A pointer to a new CNxString object containing the
433 * substring.
434 */
435
436 CNxString *subString(int startIndex) const;
437
438 /**
439 * Get a substring from this string. It is the responsibility of the
440 * caller to delete the substring when it is no longer required.
441 *
442 * @param startIndex The starting point of the substring.
443 * @param length The length of the substring.
444 * @return A pointer to a new CNxString object containing the
445 * substring.
446 */
447
448 CNxString *subString(int startIndex, int length) const;
449
450 /**
451 * Overloaded assignment operator. Copies the data within the argument
452 * string to this string.
453 *
454 * @param string The string to copy.
455 * @return This string.
456 */
457
458 CNxString &operator=(const CNxString &string);
459
460 /**
461 * Overloaded assignment operator. Copies the data within the argument
462 * char array to this string.
463 *
464 * @param string The string to copy.
465 * @return This string.
466 */
467
468 CNxString &operator=(const char *string);
469
470 /**
471 * Overloaded assignment operator. Copies the data from the argument
472 * char to this string.
473 *
474 * @param letter The char to copy.
475 * @return This string.
476 */
477
478 CNxString &operator=(nxwidget_char_t letter);
479
480 /**
481 * Compares this string to the argument.
482 *
483 * @param string String to compare to.
484 * @return Zero if both strings are equal. A value greater than zero
485 * indicates that this string is greater than the argument string. A
486 * value less than zero indicates the opposite. Note that the return
487 * value indicates the *byte* that does not match, not the *character*.
488 */
489
490 int compareTo(const CNxString &string) const;
491 };
492 }
493
494 #endif // __cplusplus
495
496 #endif // __INCLUDE_CNXSTRING_HXX
NXWidgets::CStringIterator
Definition: cstringiterator.hxx:102
NXWidgets::CNxString::m_stringLength
int m_stringLength
Definition: cnxstring.hxx:126
NXWidgets::CNxString::compareTo
int compareTo(const CNxString &string) const
Definition: cnxstring.cxx:728
NXWidgets::CNxString::getAllocatedSize
int getAllocatedSize(void) const
Definition: cnxstring.hxx:163
NXWidgets::CNxString::~CNxString
virtual ~CNxString()
Definition: cnxstring.hxx:223
NXWidgets::CNxString::lastIndexOf
const int lastIndexOf(nxwidget_char_t letter) const
Definition: cnxstring.cxx:555
NXWidgets::CNxString::append
void append(const CNxString &text)
Definition: cnxstring.cxx:267
NXWidgets::CNxString::getCharPointer
FAR nxwidget_char_t * getCharPointer(const int index) const
Definition: cnxstring.cxx:789
NXWidgets::CNxString::m_growAmount
int m_growAmount
Definition: cnxstring.hxx:128
NXWidgets::CNxString::getAllocSize
const unsigned int getAllocSize(void) const
Definition: cnxstring.hxx:337
NXWidgets::CNxString::operator=
CNxString & operator=(const CNxString &string)
Definition: cnxstring.cxx:680
NXWidgets
Definition: cbgwindow.hxx:65
NXWidgets::CNxString::indexOf
const int indexOf(nxwidget_char_t letter) const
Definition: cnxstring.cxx:480
NXWidgets::nxwidget_char_t
uint16_t nxwidget_char_t
Definition: nxconfig.hxx:454
nxconfig.hxx
NXWidgets::CNxString::setText
void setText(const CNxString &text)
Definition: cnxstring.cxx:185
NXWidgets::CNxString::hasData
bool hasData(void) const
Definition: cnxstring.hxx:152
NXWidgets::CNxString::allocateMemory
void allocateMemory(int chars, bool preserve)
Definition: cnxstring.cxx:743
NXWidgets::CNxString::getCharArray
FAR const nxwidget_char_t * getCharArray(void) const
Definition: cnxstring.hxx:174
NXWidgets::CNxString::getLength
const unsigned int getLength(void) const
Definition: cnxstring.hxx:325
NXWidgets::CNxString::getCharAt
const nxwidget_char_t getCharAt(int index) const
Definition: cnxstring.cxx:467
NXWidgets::CNxString::copyToCharArray
void copyToCharArray(FAR nxwidget_char_t *buffer) const
Definition: cnxstring.cxx:172
NXWidgets::CNxString::newStringIterator
CStringIterator * newStringIterator(void) const
Definition: cnxstring.cxx:156
NXWidgets::CNxString
Definition: cnxstring.hxx:121
NXWidgets::CNxString::m_text
FAR nxwidget_char_t * m_text
Definition: cnxstring.hxx:133
NXWidgets::CNxString::insert
void insert(const CNxString &text, const int index)
Definition: cnxstring.cxx:295
NXWidgets::CNxString::CNxString
CNxString()
Definition: cnxstring.cxx:98
NXWidgets::CNxString::subString
CNxString * subString(int startIndex) const
Definition: cnxstring.cxx:631
NXWidgets::CNxString::m_allocatedSize
int m_allocatedSize
Definition: cnxstring.hxx:127