Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
WString Struct Reference

A string class that has many of the same capabilities as std::string, plus additional functions such as conversion from UTF-8, UTF-16, and local-encoded strings, case-insensitive compare, trimming, padding, and others. More...

#include <WString.h>

Inheritance diagram for WString:
WPrintfString

Public Member Functions

 WString ()
 
 WString (WCharCP str)
 
 WString (bwstring const &other)
 
 WString (bwstring const &__str, size_t __pos, size_t __n=npos)
 
 WString (WCharCP __s, size_t __n)
 
 WString (size_t __n, wchar_t __c)
 
 WString (iterator __beg, iterator __end)
 
 WString (const_iterator __beg, const_iterator __end)
 
 WString (reverse_iterator __beg, reverse_iterator __end)
 
 WString (const_reverse_iterator __beg, const_reverse_iterator __end)
 
 WString (Utf16CP in)
 Construct a WString from a Utf16 encoded Unicode string. More...
 
 WString (CharCP in, bool isUtf8=false)
 Construct a WString from a CharCP using either the current system locale or Utf8. More...
 
 WString (CharCP in, BentleyCharEncoding encoding)
 Construct a WString from a CharCP string in the specified encoding. More...
 
WStringR AssignA (CharCP in)
 Define the contents of this WString from a CharCP using the current system locale. More...
 
WStringR AssignUtf8 (Utf8CP in)
 Define the contents of this WString from a Utf8CP. More...
 
WStringR AssignUtf16 (Utf16CP in)
 Define the contents of this WString from a Utf8CP. More...
 
WStringR AssignOrClear (WCharCP in)
 
WStringR AppendA (CharCP in)
 Append a null-terminated multibyte, locale-encoded character array to this WString. More...
 
WStringR AppendUtf8 (CharCP in)
 Append a Utf8 character array to this WString. More...
 
size_t GetMaxLocaleCharBytes () const
 Get the number of bytes required to hold the current string. More...
 
CharP ConvertToLocaleChars (CharP out, size_t maxOutBytes) const
 Get the contents of this string as a 0-terminated multibyte locale-encoded array. More...
 
CharP ConvertToLocaleChars (CharP out) const
 Get the contents of this string as a 0-terminated multibyte locale-encoded array. More...
 
WCharCP GetWCharCP () const
 Equivalent to c_str. More...
 
WString substr (size_type __pos=0, size_type __n=npos) const
 Get a substring. More...
 
int CompareToI (WCharCP other) const
 Perform a case-insensitive comparison. More...
 
int CompareToI (WStringCR other) const
 Perform a case-insensitive comparison. More...
 
int CompareTo (WCharCP other) const
 Perform a (case-sensitive) comparison. More...
 
int CompareTo (WStringCR other) const
 Perform a (case-sensitive) comparison. More...
 
bool Equals (WCharCP other) const
 Test for equality with another string. More...
 
bool Equals (WStringCR other) const
 Test for equality with another string. More...
 
bool EqualsI (WStringCR other) const
 Test for equality with another string, ignoring case. More...
 
bool EqualsI (WCharCP other) const
 Test for equality with another string, ignoring case. More...
 
void Trim ()
 Removes all whitespace from the left and right sides. Whitespace includes space, line feed, carriage return, and tab (e.g. iswspace). More...
 
void Trim (WCharCP trimCharacters)
 Removes all instances of any of the given characters from the left and right sides. More...
 
void PadLeft (size_t totalSize, value_type charToPadWith)
 Pads, if necessary, to the given totalSize by adding charToPadWith to the left side. More...
 
void PadRight (size_t totalSize, value_type charToPadWith)
 Pads, if necessary, to the given totalSize by adding charToPadWith to the right side. More...
 
bool StartsWith (WCharCP) const
 Determines if this instance starts with the provided string. More...
 
bool StartsWithI (WCharCP) const
 Determines if this instance starts with the provided string, ignoring case. More...
 
bool EndsWith (WCharCP) const
 Determines if this instance ends with the provided string. More...
 
bool EndsWithI (WCharCP) const
 Determines if this instance ends with the provided string, ignoring case. More...
 
bool Contains (WStringCR other) const
 Test for whether this string contains another string. More...
 
bool Contains (WCharCP other) const
 Test for whether this string contains another string. More...
 
bool ContainsI (WStringCR other) const
 Test for whether this string contains another string, ignoring case. More...
 
bool ContainsI (WCharCP other) const
 Test for whether this string contains another string, ignoring case. More...
 
void ToUpper ()
 Converts this string, in-place, to all upper case. More...
 
void ToLower ()
 Converts this string, in-place, to all lower case. More...
 
void AddQuotes ()
 Put quotes around a string. More...
 
void DropQuotes ()
 Remove quotes from around a string. More...
 
size_t ReplaceAll (WCharCP subStringToReplace, WCharCP replacement)
 Replace all instances of a sub string. Returns the number of replacements made. More...
 
size_t FindI (WCharCP findString) const
 Find first occurrence of findString, ignoring case. More...
 
bool ReplaceI (WCharCP findString, WCharCP replaceString)
 Replace first occurrence of findString with replaceString, ignoring case. More...
 
void VSprintf (WCharCP format, va_list argptr)
 Replace the contents of this string with a formatted result. More...
 
void Sprintf (WCharCP format,...)
 Replace the contents of this string with a formatted result. More...
 

Static Public Member Functions

static bool IsNullOrEmpty (WCharCP str)
 True if the provided string is NULL or contains no character data. More...
 
static void Sprintf (WStringR str, WCharCP format,...)
 Replace the contents of str with a formatted result. More...
 
static void VSprintf (WStringR str, WCharCP format, va_list argptr)
 Replace the contents of str with a formatted result. More...
 

Protected Member Functions

wchar_tGetBase ()
 

Detailed Description

A string class that has many of the same capabilities as std::string, plus additional functions such as conversion from UTF-8, UTF-16, and local-encoded strings, case-insensitive compare, trimming, padding, and others.

Constructor & Destructor Documentation

WString ( )
WString ( WCharCP  str)
WString ( bwstring const &  other)
WString ( bwstring const &  __str,
size_t  __pos,
size_t  __n = npos 
)
WString ( WCharCP  __s,
size_t  __n 
)
WString ( size_t  __n,
wchar_t  __c 
)
WString ( iterator  __beg,
iterator  __end 
)
WString ( const_iterator  __beg,
const_iterator  __end 
)
WString ( reverse_iterator  __beg,
reverse_iterator  __end 
)
WString ( const_reverse_iterator  __beg,
const_reverse_iterator  __end 
)
WString ( Utf16CP  in)
explicit

Construct a WString from a Utf16 encoded Unicode string.

WString ( CharCP  in,
bool  isUtf8 = false 
)
explicit

Construct a WString from a CharCP using either the current system locale or Utf8.

WString ( CharCP  in,
BentleyCharEncoding  encoding 
)

Construct a WString from a CharCP string in the specified encoding.

Member Function Documentation

void AddQuotes ( )

Put quotes around a string.

References begin(), end(), and insert().

WStringR AppendA ( CharCP  in)

Append a null-terminated multibyte, locale-encoded character array to this WString.

This will create a WString internally, so if you are appending a character constant it is more efficient to use append (L"string to append").

Parameters
[in]inThe multibyte string
Returns
Reference to this string.
WStringR AppendUtf8 ( CharCP  in)

Append a Utf8 character array to this WString.

This will create a WString internally, so if you are appending a character constant it is more efficient to use append (L"string to append").

Parameters
[in]inThe multibyte string
Returns
Reference to this string.
WStringR AssignA ( CharCP  in)

Define the contents of this WString from a CharCP using the current system locale.

Parameters
[in]inThe ASCII string
Returns
Reference to this string.
WStringR AssignOrClear ( WCharCP  in)

References clear(), and NULL.

WStringR AssignUtf16 ( Utf16CP  in)

Define the contents of this WString from a Utf8CP.

Parameters
[in]inThe Utf8 string. May be NULL.
Returns
Reference to this string.
WStringR AssignUtf8 ( Utf8CP  in)

Define the contents of this WString from a Utf8CP.

Parameters
[in]inThe Utf8 string. May be NULL.
Returns
Reference to this string.
int CompareTo ( WCharCP  other) const

Perform a (case-sensitive) comparison.

Returns
0 if the strings are equal, or -1 or 1 if this string should come before or after other.
Parameters
otherThe other string.

Referenced by SchemaNameClassNamePair::operator==().

int CompareTo ( WStringCR  other) const

Perform a (case-sensitive) comparison.

Returns
0 if the strings are equal, or -1 or 1 if this string should come before or after other.
Parameters
otherThe other string.
int CompareToI ( WCharCP  other) const

Perform a case-insensitive comparison.

Returns
0 if the strings are equal (ignoring case), or -1 or 1 if this string should come before or after other.
Parameters
otherThe other string.
int CompareToI ( WStringCR  other) const

Perform a case-insensitive comparison.

Returns
0 if the strings are equal (ignoring case), or -1 or 1 if this string should come before or after other.
Parameters
otherThe other string.

References WString::CompareToI().

Referenced by WString::CompareToI().

bool Contains ( WStringCR  other) const

Test for whether this string contains another string.

Parameters
otherThe other string.
Returns
true if this string contains the other string.
bool Contains ( WCharCP  other) const

Test for whether this string contains another string.

Parameters
otherThe other string.
Returns
true if this string contains the other string.
bool ContainsI ( WStringCR  other) const

Test for whether this string contains another string, ignoring case.

Parameters
otherThe other string.
Returns
true if this string contains the other string.
bool ContainsI ( WCharCP  other) const

Test for whether this string contains another string, ignoring case.

Parameters
otherThe other string.
Returns
true if this string contains the other string.
CharP ConvertToLocaleChars ( CharP  out,
size_t  maxOutBytes 
) const

Get the contents of this string as a 0-terminated multibyte locale-encoded array.

Parameters
outoutput buffer
maxOutBytesmaximum number number of bytes to copy to out.
Returns
the out pointer
CharP ConvertToLocaleChars ( CharP  out) const

Get the contents of this string as a 0-terminated multibyte locale-encoded array.

Remarks
The entire string is copied. The caller must ensure that the output buffer is large enough before calling this function. See GetMaxLocaleCharBytes.
Parameters
outoutput buffer
Returns
the out pointer
void DropQuotes ( )

Remove quotes from around a string.

References begin(), end(), and erase().

bool EndsWith ( WCharCP  ) const

Determines if this instance ends with the provided string.

bool EndsWithI ( WCharCP  ) const

Determines if this instance ends with the provided string, ignoring case.

bool Equals ( WCharCP  other) const

Test for equality with another string.

Returns
true if the strings are equal.
Parameters
otherThe other string.
bool Equals ( WStringCR  other) const

Test for equality with another string.

Returns
true if the strings are equal.
Parameters
otherThe other string.
bool EqualsI ( WStringCR  other) const

Test for equality with another string, ignoring case.

Returns
true if the strings are equal (ignoring case).
Parameters
otherThe other string.
bool EqualsI ( WCharCP  other) const

Test for equality with another string, ignoring case.

Returns
true if the strings are equal (ignoring case).
Parameters
otherThe other string.
size_t FindI ( WCharCP  findString) const

Find first occurrence of findString, ignoring case.

Parameters
findStringThe substring to find.
Returns
location of substring or std::string::npos if not found.
wchar_t* GetBase ( )
protected
size_t GetMaxLocaleCharBytes ( ) const

Get the number of bytes required to hold the current string.

This is the value to use to allocate a buffer (e.g. via _alloca) to to call ConvertToLocaleChars.

WCharCP GetWCharCP ( ) const

Equivalent to c_str.

static bool IsNullOrEmpty ( WCharCP  str)
static

True if the provided string is NULL or contains no character data.

References NULL.

void PadLeft ( size_t  totalSize,
value_type  charToPadWith 
)

Pads, if necessary, to the given totalSize by adding charToPadWith to the left side.

void PadRight ( size_t  totalSize,
value_type  charToPadWith 
)

Pads, if necessary, to the given totalSize by adding charToPadWith to the right side.

size_t ReplaceAll ( WCharCP  subStringToReplace,
WCharCP  replacement 
)

Replace all instances of a sub string. Returns the number of replacements made.

bool ReplaceI ( WCharCP  findString,
WCharCP  replaceString 
)

Replace first occurrence of findString with replaceString, ignoring case.

Parameters
findStringThe substring to find.
replaceStringThe replacement string.
Returns
true is a replacement is made.
void Sprintf ( WCharCP  format,
  ... 
)

Replace the contents of this string with a formatted result.

Parameters
formatThe sprintf-like format string.

Referenced by SchemaNameClassNamePair::ToColonSeparatedString(), and PlotPropValue::ToString().

static void Sprintf ( WStringR  str,
WCharCP  format,
  ... 
)
static

Replace the contents of str with a formatted result.

Parameters
strthe string to update.
formatThe sprintf-like format string.
bool StartsWith ( WCharCP  ) const

Determines if this instance starts with the provided string.

bool StartsWithI ( WCharCP  ) const

Determines if this instance starts with the provided string, ignoring case.

WString substr ( size_type  __pos = 0,
size_type  __n = npos 
) const

Get a substring.

Parameters
__posIndex of first character (default 0).
__nNumber of characters in substring (default remainder).
Returns
The new string.
Exceptions
std::out_of_rangeIf pos > size().

Construct and return a new string using the __n characters starting at __pos. If the string is too short, use the remainder of the characters. If __pos is beyond the end of the string, out_of_range is thrown.

Referenced by SchemaNameClassNamePair::Parse(), and PlotFileSpec::RemoveEmbeddedSuffix().

void ToLower ( )

Converts this string, in-place, to all lower case.

References begin(), and end().

Referenced by Utf8String::ToLower().

void ToUpper ( )

Converts this string, in-place, to all upper case.

References begin(), and end().

void Trim ( )

Removes all whitespace from the left and right sides. Whitespace includes space, line feed, carriage return, and tab (e.g. iswspace).

void Trim ( WCharCP  trimCharacters)

Removes all instances of any of the given characters from the left and right sides.

void VSprintf ( WCharCP  format,
va_list  argptr 
)

Replace the contents of this string with a formatted result.

Parameters
formatThe sprintf-like format string.
argptrArguments used by format.
static void VSprintf ( WStringR  str,
WCharCP  format,
va_list  argptr 
)
static

Replace the contents of str with a formatted result.

Parameters
strthe string to update.
formatThe sprintf-like format string.
argptrArguments used by format.

The documentation for this struct was generated from the following file:

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.