# Visualization Library

A lightweight C++ OpenGL middleware for 2D/3D graphics

[Home] [Tutorials] [All Classes] [Grouped Classes]

# vl::String Class Reference

An advanced UTF16 (Unicode BMP) string manipulation class. More...

`#include <String.hpp>`

List of all members.

## Classes

class | StringData

## Public Member Functions

virtual const char * | className ()
| String ()
| String (const String &other)
| String (const wchar_t *wstr)
| String (const char *str)
| String (wchar_t ch, int count=1)
const unsigned short * | ptr () const
| Returns the 0-terminated utf16 string.
unsigned short * | ptr ()
| Returns the 0-terminated utf16 string.
int | length () const
| Returns the length of the string.
bool | empty () const
String & | clear ()
| Clears the string.
const unsigned short & | operator[] (int i) const
| Returns the character at position i.
unsigned short & | operator[] (int i)
| Returns the character at position i.
String & | replace (unsigned short old_ch, unsigned short new_ch)
| Replaces the character 'old_ch' with 'new_ch'.
String & | replace (int start, int count, unsigned short ch)
| Equivalent to remove(start, count); insert(ch, 1);.
String & | replace (int start, int count, const String &str)
| Equivalent to remove(start, count); insert(start, str);.
String & | replace (const String &oldstr, const String &newstr, bool case_sensitive=true)
| Replaces all the occurrences of oldstr with newstr.
String & | remove (unsigned short ch, int start=0, int count=-1)
| Removes 'count' occurrences of the characters 'ch' after position 'start'.
String & | remove (const String &str, int start=0, int count=-1)
| Removes 'count' occurrences of the string 'str' after position 'start'.
String & | remove (int start, int count)
| Removes 'count' characters starting at position 'start'.
String & | reverse ()
| Reverses the order of the characters in the string.
String & | normalizeSlashes ()
| Transform \ slashes in / slashes and removes duplicates.
int | count (unsigned short ch, int start=0) const
| Returns the number of occurrences of the given character after position 'start'.
int | count (const String &str, int start=0) const
| Returns the number of occurrences of the given string after position 'start'.
int | compare (const String &other) const
| Performs a lexicographic comparison.
bool | endsWith (const String &str) const
bool | startsWith (const String &str) const
bool | endsWith (wchar_t ch) const
bool | startsWith (wchar_t ch) const
String & | insert (int pos, const String &str)
String & | insert (int pos, unsigned short ch, int count=1)
String | left (int count) const
String | right (int count) const
String | extractPath () const
| Returns the path with the trailing slash.
String | extractFileName () const
String | extractFileExtension (bool require_dot=true) const
String & | resize (int character_count)
String | substring (int start, int count=-1) const
String & | fill (wchar_t ch)
String & | trim (unsigned short ch)
String & | trim (const String &chars)
String & | trim ()
void | split (const String &separator_list, std::vector< String > &fields, bool remove_empty=false) const
void | split (unsigned short separator, std::vector< String > &fields, bool remove_empty=false) const
void | splitLines (std::vector< String > &lines) const
String | field (unsigned short separator, int field_index) const
String & | append (const String &other)
String & | append (unsigned short ch, int count=1)
String & | prepend (const String &str)
String & | prepend (unsigned short ch, int count)
int | find (unsigned short ch, int start=0) const
int | find (const String &substr, int start=0) const
int | findBackwards (unsigned short ch) const
int | findBackwards (const String &str) const
bool | contains (unsigned short ch) const
bool | contains (const String &substr) const
void | squeeze ()
int | toInt (bool hex=false) const
| Returns the int number represented by the string. The conversion is done using the standard atoi() function.
double | toDouble () const
| Returns the double number represented by the string. The conversion is done using the standard atof() function.
float | toFloat () const
| Returns the float number represented by the string. The conversion is done using the standard atof() function.
std::string | toStdString () const
| Under Windows returns a Latin1 encoded std::string, under Linux returns a UTF8 encoded std::string.
std::wstring | toStdWString () const
void | toAscii (std::string &ascii, bool translate_non_ascii_chars=true) const
| Provides some basic character translation of code points outside of the ASCII range.
void | toUTF8 (std::vector< unsigned char > &utf8, bool include_utf8_signature=true) const
void | toUTF16BE (std::vector< unsigned char > &utf16, bool include_utf16be_signature=true) const
void | toUTF16LE (std::vector< unsigned char > &utf16, bool include_utf16le_signature=true) const
void | toLatin1 (std::vector< unsigned char > &latin1) const
String | toLowerCase () const
| Returns the lower-case version of a String.
String | toUpperCase () const
| Returns the upper-case version of a String.
bool | operator== (const String &other) const
bool | operator== (const std::string &other) const
bool | operator== (const std::wstring &other) const
bool | operator== (const char *other) const
bool | operator== (const wchar_t *other) const
bool | operator!= (const String &other) const
bool | operator!= (const std::string &other) const
bool | operator!= (const std::wstring &other) const
bool | operator!= (const char *other) const
bool | operator!= (const wchar_t *other) const
void | operator= (const String &other)
void | operator= (const wchar_t *wstr)
void | operator= (const std::wstring &str)
| equivalent to fromLatin1(str.c_str())
void | operator= (const char *str)
| Under Windows is equivalent to 'fromLatin1(str)', under Linux and Mac is equivalent to 'fromUTF8(str)'.
void | operator= (const std::string &str)
| Under Windows is equivalent to 'fromLatin1(str.c_str())', under Linux and Mac is equivalent to 'fromUTF8(str.c_str())'.
bool | operator< (const String &other) const
| lexicographic sorting
String & | operator+= (wchar_t ch)
String | operator+ (wchar_t ch) const
String & | operator+= (const String &other)
String | operator+ (const String &other) const
void | acquireData () const
| Acquires a private copy of the data, if the string for example has been copied from another one.

## Static Public Member Functions

static EStringEncoding | detectEncoding (const void *str, int byte_count, EStringEncoding encoding=VL_PLATFORM_DEFAULT_ENCODING)
| Detects the encoding.
static String | loadText (const String &path, EStringEncoding encoding=VL_PLATFORM_DEFAULT_ENCODING)
static String | loadText (const char *path, EStringEncoding encoding=VL_PLATFORM_DEFAULT_ENCODING)
static String | loadText (VirtualFile *file, EStringEncoding encoding=VL_PLATFORM_DEFAULT_ENCODING)
static String | loadText (void *data, int bytes, EStringEncoding encoding=VL_PLATFORM_DEFAULT_ENCODING)
static unsigned short | getUpperCase (unsigned short ch)
static unsigned short | getLowerCase (unsigned short ch)
static unsigned short | getTitleCase (unsigned short ch)
static void | filterStrings (std::vector< String > &strings, const String &filter)
| Accepts only filters of the type "*abc", "abc*" and "*abc*".
static wchar_t | platformSlash ()
static std::string | trimStdString (const std::string &text)
| Remove the spaces before and after an std::string.
static String | fromInt (int value)
| Creates a string representing the given integer value.
static String | fromUInt (unsigned int value)
| Creates a string representing the given unsigned integer value.
static String | fromLongLong (long long value)
| Creates a string representing the given long long value.
static String | fromULongLong (unsigned long long value)
| Creates a string representing the given unsigned long long value.
static String | fromDouble (double value, int decimals=6)
| Creates a string representing the given double value The value of 'decimals' can be between 0 and 20.
static String | fromStdString (const std::string &str)
| Initializes the string from a std::string using the fromAscii() function.
static String | fromStdWString (const std::wstring &str)
| Initializes the string from a std::string using the fromAscii() function.
static String | fromAscii (const char *str, int size=-1)
| Initializes the string from a 7 bit ascii string.
static String | fromUTF16BE (const unsigned short *str, int byte_count=-1)
| Accepts strings with and without UTF16 BE signature Supports natively the characters from the BMP, the other characters are substituted with '?' The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.
static String | fromUTF16LE (const unsigned short *str, int byte_count=-1)
| Accepts strings with and without UTF16 LE signature Supports natively the characters from the BMP, the other characters are substituted with '?' The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.
static String | fromUTF16 (const unsigned short *str, int byte_count=-1)
| str must have UTF16 LE or UTF16 BE signature The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.
static String | fromUTF8 (const char *str, int byte_count=-1)
| Accepts strings with and without UTF8 signature.
static String | fromLatin1 (const char *str, int character_count=-1)
| The size of the buffer pointed by 'str' must be at least 'character_count' bytes large or null terminated.

## Protected Member Functions

void | createData () const

## Detailed Description

An advanced UTF16 (Unicode BMP) string manipulation class.

- Lazy data copy on write that speeds up String manipulation, copy and comparison
- Encoding and decoding functions for UTF8, UTF16 BE, UTF16 LE, Latin1 and Ascii, with and without signature
- Interoperability to and from std::string, std::wstring, char* and wchar_t*
- Unicode to Ascii character translation when possible
- Extended character case manipulation for most UTF16/BMP codes
- Advanced string manipulation routines like line/field splitting, comparison, searching, matching, counting, filling, trimming etc.
- Fast substring find function based on the Quick Find algorithm

## Constructor & Destructor Documentation

String::String | ( |  | ) |

String::String | ( | const String & | other | ) |

String::String | ( | const wchar_t * | wstr | ) |

String::String | ( | const char * | str | ) |

String::String | ( | wchar_t | ch,
|  | int | count = `1` |
| ) |  |  | `[explicit]`

## Member Function Documentation

virtual const char* vl::String::className | ( |  | ) | `[inline, virtual]`

EStringEncoding String::detectEncoding | ( | const void * | str,
|  | int | byte_count,
|  | EStringEncoding | encoding = `VL_PLATFORM_DEFAULT_ENCODING` |
| ) |  |  | `[static]`

Detects the encoding.

String String::loadText | ( | const String & | path,
|  | EStringEncoding | encoding = `VL_PLATFORM_DEFAULT_ENCODING` |
| ) |  |  | `[static]`

static String vl::String::loadText | ( | const char * | path,
|  | EStringEncoding | encoding = `VL_PLATFORM_DEFAULT_ENCODING` |
| ) |  |  | `[inline, static]`

String String::loadText | ( | VirtualFile * | file,
|  | EStringEncoding | encoding = `VL_PLATFORM_DEFAULT_ENCODING` |
| ) |  |  | `[static]`

String String::loadText | ( | void * | data,
|  | int | bytes,
|  | EStringEncoding | encoding = `VL_PLATFORM_DEFAULT_ENCODING` |
| ) |  |  | `[static]`

unsigned short String::getUpperCase | ( | unsigned short | ch | ) | `[static]`

unsigned short String::getLowerCase | ( | unsigned short | ch | ) | `[static]`

unsigned short String::getTitleCase | ( | unsigned short | ch | ) | `[static]`

void String::filterStrings | ( | std::vector< String > & | strings,
|  | const String & | filter |
| ) |  |  | `[static]`

Accepts only filters of the type "*abc", "abc*" and "*abc*".

static wchar_t vl::String::platformSlash | ( |  | ) | `[inline, static]`

std::string String::trimStdString | ( | const std::string & | text | ) | `[static]`

Remove the spaces before and after an std::string.

const unsigned short* vl::String::ptr | ( |  | ) | const`[inline]`

Returns the 0-terminated utf16 string.

unsigned short* vl::String::ptr | ( |  | ) | `[inline]`

Returns the 0-terminated utf16 string.

int vl::String::length | ( |  | ) | const`[inline]`

Returns the length of the string.

bool vl::String::empty | ( |  | ) | const`[inline]`

String& vl::String::clear | ( |  | ) | `[inline]`

Clears the string.

const unsigned short& vl::String::operator[] | ( | int | i | ) | const`[inline]`

Returns the character at position i.

unsigned short& vl::String::operator[] | ( | int | i | ) | `[inline]`

Returns the character at position i.

String & String::replace | ( | unsigned short | old_ch,
|  | unsigned short | new_ch |
| ) |  |  |

Replaces the character 'old_ch' with 'new_ch'.

String & String::replace | ( | int | start,
|  | int | count,
|  | unsigned short | ch |
| ) |  |  |

Equivalent to remove(start, count); insert(ch, 1);.

String & String::replace | ( | int | start,
|  | int | count,
|  | const String & | str |
| ) |  |  |

Equivalent to remove(start, count); insert(start, str);.

String & String::replace | ( | const String & | oldstr,
|  | const String & | newstr,
|  | bool | case_sensitive = `true` |
| ) |  |  |

Replaces all the occurrences of oldstr with newstr.

String & String::remove | ( | unsigned short | ch,
|  | int | start = `0`,
|  | int | count = `-1` |
| ) |  |  |

Removes 'count' occurrences of the characters 'ch' after position 'start'.

If 'count' is set -1 there is no limit to the number of occurrences removed.

String & String::remove | ( | const String & | str,
|  | int | start = `0`,
|  | int | count = `-1` |
| ) |  |  |

Removes 'count' occurrences of the string 'str' after position 'start'.

If 'count' is set -1 there is no limit to the number of occurrences removed.

String & String::remove | ( | int | start,
|  | int | count |
| ) |  |  |

Removes 'count' characters starting at position 'start'.

String & String::reverse | ( |  | ) |

Reverses the order of the characters in the string.

String & String::normalizeSlashes | ( |  | ) |

Transform \ slashes in / slashes and removes duplicates.

int String::count | ( | unsigned short | ch,
|  | int | start = `0` |
| ) |  |  | const

Returns the number of occurrences of the given character after position 'start'.

int String::count | ( | const String & | str,
|  | int | start = `0` |
| ) |  |  | const

Returns the number of occurrences of the given string after position 'start'.

int String::compare | ( | const String & | other | ) | const

Performs a lexicographic comparison.

Returns < 0 if this string comes before 'other'. Returns > 0 if 'other' comes before this string. Returns 0 if the two strings are equal.

bool String::endsWith | ( | const String & | str | ) | const

bool String::startsWith | ( | const String & | str | ) | const

bool String::endsWith | ( | wchar_t | ch | ) | const

bool String::startsWith | ( | wchar_t | ch | ) | const

String & String::insert | ( | int | pos,
|  | const String & | str |
| ) |  |  |

String & String::insert | ( | int | pos,
|  | unsigned short | ch,
|  | int | count = `1` |
| ) |  |  |

String String::left | ( | int | count | ) | const

String String::right | ( | int | count | ) | const

String String::extractPath | ( |  | ) | const

Returns the path with the trailing slash.

String String::extractFileName | ( |  | ) | const

String String::extractFileExtension | ( | bool | require_dot = `true` | ) | const

String & String::resize | ( | int | character_count | ) |

String String::substring | ( | int | start,
|  | int | count = `-1` |
| ) |  |  | const

String & String::fill | ( | wchar_t | ch | ) |

String & String::trim | ( | unsigned short | ch | ) |

String & String::trim | ( | const String & | chars | ) |

String & String::trim | ( |  | ) |

void String::split | ( | const String & | separator_list,
|  | std::vector< String > & | fields,
|  | bool | remove_empty = `false` |
| ) |  |  | const

void String::split | ( | unsigned short | separator,
|  | std::vector< String > & | fields,
|  | bool | remove_empty = `false` |
| ) |  |  | const

void String::splitLines | ( | std::vector< String > & | lines | ) | const

String String::field | ( | unsigned short | separator,
|  | int | field_index |
| ) |  |  | const

String & String::append | ( | const String & | other | ) |

String & String::append | ( | unsigned short | ch,
|  | int | count = `1` |
| ) |  |  |

String & String::prepend | ( | const String & | str | ) |

String & String::prepend | ( | unsigned short | ch,
|  | int | count |
| ) |  |  |

int String::find | ( | unsigned short | ch,
|  | int | start = `0` |
| ) |  |  | const

int String::find | ( | const String & | substr,
|  | int | start = `0` |
| ) |  |  | const

int String::findBackwards | ( | unsigned short | ch | ) | const

int String::findBackwards | ( | const String & | str | ) | const

bool String::contains | ( | unsigned short | ch | ) | const

bool String::contains | ( | const String & | substr | ) | const

void String::squeeze | ( |  | ) |

String String::fromInt | ( | int | value | ) | `[static]`

Creates a string representing the given integer value.

String String::fromUInt | ( | unsigned int | value | ) | `[static]`

Creates a string representing the given unsigned integer value.

String String::fromLongLong | ( | long long | value | ) | `[static]`

Creates a string representing the given long long value.

String String::fromULongLong | ( | unsigned long long | value | ) | `[static]`

Creates a string representing the given unsigned long long value.

String String::fromDouble | ( | double | value,
|  | int | decimals = `6` |
| ) |  |  | `[static]`

Creates a string representing the given double value The value of 'decimals' can be between 0 and 20.

String String::fromStdString | ( | const std::string & | str | ) | `[static]`

Initializes the string from a std::string using the fromAscii() function.

String String::fromStdWString | ( | const std::wstring & | str | ) | `[static]`

Initializes the string from a std::string using the fromAscii() function.

String String::fromAscii | ( | const char * | str,
|  | int | size = `-1` |
| ) |  |  | `[static]`

Initializes the string from a 7 bit ascii string.

String String::fromUTF16BE | ( | const unsigned short * | str,
|  | int | byte_count = `-1` |
| ) |  |  | `[static]`

Accepts strings with and without UTF16 BE signature Supports natively the characters from the BMP, the other characters are substituted with '?' The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.

String String::fromUTF16LE | ( | const unsigned short * | str,
|  | int | byte_count = `-1` |
| ) |  |  | `[static]`

Accepts strings with and without UTF16 LE signature Supports natively the characters from the BMP, the other characters are substituted with '?' The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.

String String::fromUTF16 | ( | const unsigned short * | str,
|  | int | byte_count = `-1` |
| ) |  |  | `[static]`

str must have UTF16 LE or UTF16 BE signature The size of the buffer pointed by 'str' must be at least 'byte_count' bytes large or null terminated.

String String::fromUTF8 | ( | const char * | str,
|  | int | byte_count = `-1` |
| ) |  |  | `[static]`

Accepts strings with and without UTF8 signature.

String String::fromLatin1 | ( | const char * | str,
|  | int | character_count = `-1` |
| ) |  |  | `[static]`

The size of the buffer pointed by 'str' must be at least 'character_count' bytes large or null terminated.

int String::toInt | ( | bool | hex = `false` | ) | const

Returns the int number represented by the string. The conversion is done using the standard atoi() function.

double String::toDouble | ( |  | ) | const

Returns the double number represented by the string. The conversion is done using the standard atof() function.

float vl::String::toFloat | ( |  | ) | const`[inline]`

Returns the float number represented by the string. The conversion is done using the standard atof() function.

std::string String::toStdString | ( |  | ) | const

Under Windows returns a Latin1 encoded std::string, under Linux returns a UTF8 encoded std::string.

std::wstring String::toStdWString | ( |  | ) | const

void String::toAscii | ( | std::string & | ascii,
|  | bool | translate_non_ascii_chars = `true` |
| ) |  |  | const

Provides some basic character translation of code points outside of the ASCII range.

void String::toUTF8 | ( | std::vector< unsigned char > & | utf8,
|  | bool | include_utf8_signature = `true` |
| ) |  |  | const

void String::toUTF16BE | ( | std::vector< unsigned char > & | utf16,
|  | bool | include_utf16be_signature = `true` |
| ) |  |  | const

void String::toUTF16LE | ( | std::vector< unsigned char > & | utf16,
|  | bool | include_utf16le_signature = `true` |
| ) |  |  | const

void String::toLatin1 | ( | std::vector< unsigned char > & | latin1 | ) | const

String String::toLowerCase | ( |  | ) | const

Returns the lower-case version of a String.

String String::toUpperCase | ( |  | ) | const

Returns the upper-case version of a String.

bool vl::String::operator== | ( | const String & | other | ) | const`[inline]`

bool vl::String::operator== | ( | const std::string & | other | ) | const`[inline]`

bool vl::String::operator== | ( | const std::wstring & | other | ) | const`[inline]`

bool vl::String::operator== | ( | const char * | other | ) | const`[inline]`

bool vl::String::operator== | ( | const wchar_t * | other | ) | const`[inline]`

bool vl::String::operator!= | ( | const String & | other | ) | const`[inline]`

bool vl::String::operator!= | ( | const std::string & | other | ) | const`[inline]`

bool vl::String::operator!= | ( | const std::wstring & | other | ) | const`[inline]`

bool vl::String::operator!= | ( | const char * | other | ) | const`[inline]`

bool vl::String::operator!= | ( | const wchar_t * | other | ) | const`[inline]`

void vl::String::operator= | ( | const String & | other | ) | `[inline]`

void vl::String::operator= | ( | const wchar_t * | wstr | ) | `[inline]`

void vl::String::operator= | ( | const std::wstring & | str | ) | `[inline]`

equivalent to fromLatin1(str.c_str())

void vl::String::operator= | ( | const char * | str | ) | `[inline]`

Under Windows is equivalent to 'fromLatin1(str)', under Linux and Mac is equivalent to 'fromUTF8(str)'.

void vl::String::operator= | ( | const std::string & | str | ) | `[inline]`

Under Windows is equivalent to 'fromLatin1(str.c_str())', under Linux and Mac is equivalent to 'fromUTF8(str.c_str())'.

bool vl::String::operator< | ( | const String & | other | ) | const`[inline]`

lexicographic sorting

String& vl::String::operator+= | ( | wchar_t | ch | ) | `[inline]`

String vl::String::operator+ | ( | wchar_t | ch | ) | const`[inline]`

String& vl::String::operator+= | ( | const String & | other | ) | `[inline]`

String vl::String::operator+ | ( | const String & | other | ) | const`[inline]`

void vl::String::acquireData | ( |  | ) | const`[inline]`

Acquires a private copy of the data, if the string for example has been copied from another one.

Call this function before you pass the copy of a string to another thread.

void vl::String::createData | ( |  | ) | const`[inline, protected]`

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

- E:/VisualizationLibrary/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/String.hpp
- E:/VisualizationLibrary/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/String.cpp

Visualization Library v2009.07 Reference Documentation
Copyright 2005-2009 Michele Bosi. All rights reserved.
Updated on Mon Aug 10 21:41:42 2009.
Permission is granted to use this page to write and publish articles regarding Visualization Library.