NXWidgets: NXWidgets::CNxString Class Reference

NXWidgets 1.19

Public Member Functions | Protected Member Functions | Protected Attributes | Private Attributes | Friends | List of all members
NXWidgets::CNxString Class Reference

`#include <cnxstring.hxx>`

Inheritance diagram for NXWidgets::CNxString:

## Public Member Functions
| CNxString ()
| CNxString (FAR const char *text)
| CNxString (const nxwidget_char_t letter)
| CNxString (const CNxString &string)
virtual | ~CNxString ()
CStringIterator * | newStringIterator (void) const
void | copyToCharArray (FAR nxwidget_char_t *buffer) const
void | setText (const CNxString &text)
void | setText (FAR const char *text)
void | setText (FAR const nxwidget_char_t *text, int nchars)
void | setText (const nxwidget_char_t text)
void | append (const CNxString &text)
void | insert (const CNxString &text, const int index)
void | remove (const int startIndex)
void | remove (const int startIndex, const int count)
const unsigned int | getLength (void) const
const unsigned int | getAllocSize (void) const
const nxwidget_char_t | getCharAt (int index) const
const int | indexOf (nxwidget_char_t letter) const
const int | indexOf (nxwidget_char_t letter, int startIndex) const
const int | indexOf (nxwidget_char_t letter, int startIndex, int count) const
const int | lastIndexOf (nxwidget_char_t letter) const
const int | lastIndexOf (nxwidget_char_t letter, int startIndex) const
const int | lastIndexOf (nxwidget_char_t letter, int startIndex, int count) const
CNxString * | subString (int startIndex) const
CNxString * | subString (int startIndex, int length) const
CNxString & | operator= (const CNxString &string)
CNxString & | operator= (const char *string)
CNxString & | operator= (nxwidget_char_t letter)
int | compareTo (const CNxString &string) const

## Protected Member Functions
void | allocateMemory (int chars, bool preserve)
bool | hasData (void) const
int | getAllocatedSize (void) const
FAR const nxwidget_char_t * | getCharArray (void) const
FAR nxwidget_char_t * | getCharPointer (const int index) const

## Protected Attributes
FAR nxwidget_char_t * | m_text

## Private Attributes
int | m_stringLength
int | m_allocatedSize
int | m_growAmount

## Friends
class | CStringIterator

## Detailed Description

Unicode string class. Uses 16-bt wide-character encoding. For optimal performance, use the CStringIterator class to iterate over a CNxString instance.

Where possible, the string avoids allocating memory each time the string grows or shrinks. This means that the string may consume more memory than the number of chars would seem to dictate if the object previously contained a large string that has subsequently been truncated. It also means that increasing the length of such a string is a cheaper operation as memory does not need to allocated and copied.

Additionally, the string increases its array size by m_growAmount every time it needs to allocate extra memory, potentially reducing the number of reallocs needed.

The string is not null-terminated. Instead, it uses a m_stringLength member that stores the number of characters in the string. This saves a byte and makes calls to getLength() run in O(1) time instead of O(n).

Definition at line 121 of file cnxstring.hxx.

## Constructor & Destructor Documentation

## ◆ CNxString() [1/4]

CNxString::CNxString | ( |  | ) |

Constructor to create an empty string object.

Definition at line 98 of file cnxstring.cxx.

## ◆ CNxString() [2/4]

CNxString::CNxString | ( | FAR const char * | text | ) |

Constructor to create a string from a C character array.

Parameters

  text | Pointer to a char array to use as the basis of the string.

Definition at line 113 of file cnxstring.cxx.

## ◆ CNxString() [3/4]

CNxString::CNxString | ( | const nxwidget_char_t | text | ) |

Constructor to create a string from a single character.

Parameters

  letter | Single character to use as the basis of the string.

Definition at line 128 of file cnxstring.cxx.

## ◆ CNxString() [4/4]

CNxString::CNxString | ( | const CNxString & | string | ) |

Copy constructor.

Parameters

  string | CNxString object to create a copy of.

Definition at line 138 of file cnxstring.cxx.

## ◆ ~CNxString()

virtual NXWidgets::CNxString::~CNxString | ( |  | ) |
| inlinevirtual

Destructor.

Definition at line 223 of file cnxstring.hxx.

## Member Function Documentation

## ◆ allocateMemory()

void CNxString::allocateMemory | ( | int | nChars,
|  | bool | preserve
| ) |  |
| protected

Allocate memory for the string.

Parameters

  chars | Number of chars to allocate.
  preserve | If true, the data in the existing memory will be preserved if new memory must be allocated

Allocate memory for the string.

Parameters

  chars | Number nxwidget_char_t size characters to allocate.
  preserve | If true, the data in the existing memory will be preserved if new memory must be allocated

Definition at line 743 of file cnxstring.cxx.

## ◆ append()

void CNxString::append | ( | const CNxString & | text | ) |

Append text to the end of the string.

Parameters

  text | String to append.

Definition at line 267 of file cnxstring.cxx.

## ◆ compareTo()

int CNxString::compareTo | ( | const CNxString & | string | ) | const

Compares this string to the argument.

Parameters

  string | String to compare to.

Returns
  Zero if both strings are equal. A value greater than zero indicates that this string is greater than the argument string. A value less than zero indicates the opposite. Note that the return value indicates the byte that does not match, not the character.

Definition at line 728 of file cnxstring.cxx.

## ◆ copyToCharArray()

void CNxString::copyToCharArray | ( | FAR nxwidget_char_t * | buffer | ) | const

Copy the internal array to the supplied buffer. The buffer must be large enough to contain the full text in the string. The getAllocSize() method can be used to obtain the length of the string. Unlike the CNxString class, the char array is null-terminated. The buffer must be (getAllocSize() + 1) bytes long, in order to accommodate the terminator.

Parameters

  buffer | Buffer to copy the internal char array to.

Copy the internal array to the supplied buffer. The buffer must be large enough to contain the full text in the string. The getAllocSize() method can be used to obtain the length of the string. Unlike the CNxString class, the char array is null-terminated. The buffer must be (getAllocSize() + 2) bytes long, in order to accommodate the terminator.

Parameters

  buffer | Buffer to copy the internal char array to.

Definition at line 172 of file cnxstring.cxx.

## ◆ getAllocatedSize()

int NXWidgets::CNxString::getAllocatedSize | ( | void |  | ) | const
| inlineprotected

Get the amount of allocated memory.

Returns
  The number of chars allocated in RAM.

Definition at line 163 of file cnxstring.hxx.

## ◆ getAllocSize()

const unsigned int NXWidgets::CNxString::getAllocSize | ( | void |  | ) | const
| inline

Get the size of a buffer (in bytes) required in order to copy the internal string into an the array. This is normally used in conjunction with copyToCharArray(). Note that the returned size includes additional byte(s) to hold NUL termination.

Definition at line 337 of file cnxstring.hxx.

## ◆ getCharArray()

FAR const nxwidget_char_t* NXWidgets::CNxString::getCharArray | ( | void |  | ) | const
| inlineprotected

Returns a pointer to the raw char array data.

Returns
  Pointer to the char array.

Definition at line 174 of file cnxstring.hxx.

## ◆ getCharAt()

const nxwidget_char_t CNxString::getCharAt | ( | int | index | ) | const

Get the character at the specified index. This function is useful for finding the occasional character at an index, but for iterating over strings it is exceptionally slow. The newStringIterator() method should be used to retrieve an iterator object that can iterate over the string efficiently.

Parameters

  index | The index of the character to retrieve.

Returns
  The character at the specified index.

Definition at line 467 of file cnxstring.cxx.

## ◆ getCharPointer()

FAR nxwidget_char_t * CNxString::getCharPointer | ( | const int | index | ) | const
| protected

Return a pointer to the specified character.

Parameters

  index | Index of the character to retrieve.

Return a pointer to the specified characters.

Parameters

  index | Index of the character to retrieve.

Definition at line 789 of file cnxstring.cxx.

## ◆ getLength()

const unsigned int NXWidgets::CNxString::getLength | ( | void |  | ) | const
| inline

Get the of number of letters (ie. the length) of the string.

Returns
  The length of the string.

Definition at line 325 of file cnxstring.hxx.

## ◆ hasData()

bool NXWidgets::CNxString::hasData | ( | void |  | ) | const
| inlineprotected

Check if we've got any string data stored or not.

Returns
  True if the string contains any data; false if no data has yet been supplied.

Definition at line 152 of file cnxstring.hxx.

## ◆ indexOf() [1/3]

const int CNxString::indexOf | ( | nxwidget_char_t | letter | ) | const

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found.

Parameters

  letter | Letter to find.

Returns
  The index of the letter.

Definition at line 480 of file cnxstring.cxx.

## ◆ indexOf() [2/3]

const int CNxString::indexOf | ( | nxwidget_char_t | letter,
|  | int | startIndex
| ) |  | const

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string from "startIndex" until it has examined all subsequent letters.

Parameters

  letter | Letter to find.
  startIndex | The index to start searching from.

Returns
  The index of the letter.

Definition at line 495 of file cnxstring.cxx.

## ◆ indexOf() [3/3]

const int CNxString::indexOf | ( | nxwidget_char_t | letter,
|  | int | startIndex,
|  | int | count
| ) |  | const

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string from "startIndex" until it has examined all letters within the range "count".

Parameters

  letter | Letter to find.
  startIndex | The index to start searching from.
  count | The number of characters to examine.

Returns
  The index of the letter.

Definition at line 512 of file cnxstring.cxx.

## ◆ insert()

void CNxString::insert | ( | const CNxString & | text,
|  | const int | index
| ) |  |

Insert text at the specified character index.

Parameters

  text | The text to insert.
  index | The index at which to insert the text.

Definition at line 295 of file cnxstring.cxx.

## ◆ lastIndexOf() [1/3]

const int CNxString::lastIndexOf | ( | nxwidget_char_t | letter | ) | const

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found.

Parameters

  letter | Letter to find.

Returns
  The index of the letter.

Definition at line 555 of file cnxstring.cxx.

## ◆ lastIndexOf() [2/3]

const int CNxString::lastIndexOf | ( | nxwidget_char_t | letter,
|  | int | startIndex
| ) |  | const

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string backwards from "startIndex" until it has examined all preceding letters within the string.

Parameters

  letter | Letter to find.
  startIndex | The index to start searching from.

Returns
  The index of the letter.

Definition at line 571 of file cnxstring.cxx.

## ◆ lastIndexOf() [3/3]

const int CNxString::lastIndexOf | ( | nxwidget_char_t | letter,
|  | int | startIndex,
|  | int | count
| ) |  | const

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string backwards from "startIndex" until it has examined all letters within the range "count".

Parameters

  letter | Letter to find.
  startIndex | The index to start searching from.
  count | The number of characters to examine.

Returns
  The index of the letter.

Definition at line 587 of file cnxstring.cxx.

## ◆ newStringIterator()

CStringIterator * CNxString::newStringIterator | ( | void |  | ) | const

Creates and returns a new CStringIterator object that will iterate over this string. The object must be manually deleted once it is no longer needed.

Returns
  A new CStringIterator object.

Creates and returns a new CCStringIterator object that will iterate over this string. The object must be manually deleted once it is no longer needed.

Returns
  A new CCStringIterator object.

Definition at line 156 of file cnxstring.cxx.

## ◆ operator=() [1/3]

CNxString & CNxString::operator= | ( | const CNxString & | string | ) |

Overloaded assignment operator. Copies the data within the argument string to this string.

Parameters

  string | The string to copy.

Returns
  This string.

Definition at line 680 of file cnxstring.cxx.

## ◆ operator=() [2/3]

CNxString& NXWidgets::CNxString::operator= | ( | const char * | string | ) |

Overloaded assignment operator. Copies the data within the argument char array to this string.

Parameters

  string | The string to copy.

Returns
  This string.

## ◆ operator=() [3/3]

CNxString & CNxString::operator= | ( | nxwidget_char_t | letter | ) |

Overloaded assignment operator. Copies the data from the argument char to this string.

Parameters

  letter | The char to copy.

Returns
  This string.

Definition at line 712 of file cnxstring.cxx.

## ◆ remove() [1/2]

void CNxString::remove | ( | const int | startIndex | ) |

Remove all characters from the string from the start index onwards.

Parameters

  startIndex | Index to remove from.

Definition at line 398 of file cnxstring.cxx.

## ◆ remove() [2/2]

void CNxString::remove | ( | const int | startIndex,
|  | const int | count
| ) |  |

Remove specified number of characters from the string from the start index onwards.

Parameters

  startIndex | Index to remove from.
  count | Number of characters to remove.

Definition at line 421 of file cnxstring.cxx.

## ◆ setText() [1/4]

void CNxString::setText | ( | const CNxString & | text | ) |

Set the text in the string.

Parameters

  text | CNxString containing the new data for this string.

Definition at line 185 of file cnxstring.cxx.

## ◆ setText() [2/4]

void CNxString::setText | ( | FAR const char * | text | ) |

Set the text in the string.

Parameters

  text | Char array to use as the new data for this string.

Set the 8-bit C-string text in the string.

Parameters

  text | Char array to use as the new data for this string.

Definition at line 206 of file cnxstring.cxx.

## ◆ setText() [3/4]

void CNxString::setText | ( | FAR const nxwidget_char_t * | text,
|  | int | nchars
| ) |  |

Set the nxwidget_char_t text in the string.

Parameters

  text | Char array to use as the new data for this string.

Set the text in the string.

Parameters

  text | Char array to use as the new data for this string.

Definition at line 231 of file cnxstring.cxx.

## ◆ setText() [4/4]

void CNxString::setText | ( | const nxwidget_char_t | letter | ) |

Set the 8-bit C-string text in the string.

Parameters

  text | Character to to use as the new data for this string.

Set the text in the string.

Parameters

  text | Character to to use as the new data for this string.

Definition at line 249 of file cnxstring.cxx.

## ◆ subString() [1/2]

CNxString * CNxString::subString | ( | int | startIndex | ) | const

Get a substring from this string. It is the responsibility of the caller to delete the substring when it is no longer required.

Parameters

  startIndex | The starting point of the substring.

Returns
  A pointer to a new CNxString object containing the substring.

Definition at line 631 of file cnxstring.cxx.

## ◆ subString() [2/2]

CNxString * CNxString::subString | ( | int | startIndex,
|  | int | length
| ) |  | const

Get a substring from this string. It is the responsibility of the caller to delete the substring when it is no longer required.

Parameters

  startIndex | The starting point of the substring.
  length | The length of the substring.

Returns
  A pointer to a new CNxString object containing the substring.

Definition at line 646 of file cnxstring.cxx.

## Friends And Related Function Documentation

## ◆ CStringIterator

friend class CStringIterator
| friend

Definition at line 124 of file cnxstring.hxx.

## Member Data Documentation

## ◆ m_allocatedSize

int NXWidgets::CNxString::m_allocatedSize
| private

Number of bytes allocated for this string

Definition at line 127 of file cnxstring.hxx.

## ◆ m_growAmount

int NXWidgets::CNxString::m_growAmount
| private

Number of chars that the string grows by whenever it needs to get larger

Definition at line 128 of file cnxstring.hxx.

## ◆ m_stringLength

int NXWidgets::CNxString::m_stringLength
| private

Number of characters in the string

Definition at line 126 of file cnxstring.hxx.

## ◆ m_text

FAR nxwidget_char_t* NXWidgets::CNxString::m_text
| protected

Raw char array data

Definition at line 133 of file cnxstring.hxx.

The documentation for this class was generated from the following files:

- cnxstring.hxx
- cnxstring.cxx