Rhino C++ API  7.24
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
ON_wString Class Reference

A wide character string. The default encoding is the encoding the compiler uses for wchar_t* s = L"..."; strings. This is typically 2 byte wchar_t UTF-16 on Windows and 4 byte wchar_t UTF-32 on MacOS. However, some MacOS SDK functions return 4 byte wchar_t UTF-16 strings. More...

#include <opennurbs_string.h>

Public Types

enum  : int { MaximumStringLength = ON_String::MaximumStringLength }
 
enum  ExampleType : unsigned int {
  ExampleType::Empty = 0, ExampleType::WideChar = 1, ExampleType::UTF16 = 51, ExampleType::RichText = 90,
  ExampleType::XML = 101, ExampleType::XMLalternate1 = 102, ExampleType::XMLalternate2 = 103, ExampleType::XMLalternate3 = 104
}
 Identifies a built in string that can be used for testing. More...
 

Public Member Functions

 ON_wString () ON_NOEXCEPT
 Constructors. More...
 
 ON_wString (char, int=1)
 
 ON_wString (const char *src)
 src = nul; terminated UTF-8 string More...
 
 ON_wString (const char *src, int)
 from UTF-8 substring More...
 
 ON_wString (const ON_String &src)
 src = UTF-8 string More...
 
 ON_wString (const ON_wString &)
 
 ON_wString (const unsigned char *src)
 src = nul; terminated UTF-8 string More...
 
 ON_wString (const unsigned char *src, int)
 from UTF-8 substring More...
 
 ON_wString (const wchar_t *)
 
 ON_wString (const wchar_t *, int)
 from substring More...
 
 ON_wString (unsigned char, int=1)
 
 ON_wString (wchar_t, int=1)
 
 ~ON_wString ()
 
void Append (const char *sUTF8, int)
 string concatenation More...
 
void Append (const unsigned char *sUTF8, int)
 append specified number of elements from a UTF-8 string More...
 
void Append (const wchar_t *, int)
 append specified number of elements More...
 
wchar_t * Array ()
 
const wchar_t * Array () const
 
int Compare (const ON_wString &other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
int Compare (const wchar_t *) const
 ON_DEPRECATED ///< deprecation in progress. More...
 
int Compare (const wchar_t *other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
int CompareAttributeName (const wchar_t *other_name) const
 
int CompareNoCase (const wchar_t *) const
 ON_DEPRECATED ///< deprecation in progress. More...
 
int CompareOrdinal (const ON_wString &other_string, bool bOrdinalIgnoreCase) const
 
int CompareOrdinal (const wchar_t *other_string, bool bOrdinalIgnoreCase) const
 
int ComparePath (const wchar_t *other_path) const
 
const ON_SHA1_Hash ContentHash (ON_StringMapOrdinalType mapping) const
 
void Create ()
 
ON__UINT32 DataCRC (ON__UINT32 current_remainder) const
 
ON__UINT32 DataCRCLower (ON__UINT32 current_remainder) const
 
const ON_wString DecodeXMLValue () const
 
void Destroy ()
 releases any memory and initializes to default empty string More...
 
const ON_wString Duplicate () const
 
void EmergencyDestroy ()
 
void Empty ()
 sets length to zero - if possible, memory is retained More...
 
void EnableReferenceCounting (bool bEnable)
 
const ON_wString EncodeXMLValue () const
 
const ON_wString EncodeXMLValue (bool bEncodeCodePointsAboveBasicLatin) const
 
bool Equal (const ON_wString &other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
bool Equal (const wchar_t *other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
bool EqualAttributeName (const wchar_t *other_name) const
 
bool EqualOrdinal (const ON_wString &other_string, bool bOrdinalIgnoreCase) const
 
bool EqualOrdinal (const wchar_t *other_string, bool bOrdinalIgnoreCase) const
 
bool EqualPath (const wchar_t *other_path) const
 
int Find (char utf8_single_byte_c) const
 
int Find (char utf8_single_byte_c, size_t start_index) const
 
int Find (const char *sUTF8) const
 
int Find (const char *sUTF8, size_t start_index) const
 
int Find (const unsigned char *sUTF8) const
 
int Find (const unsigned char *sUTF8, size_t start_index) const
 
int Find (const wchar_t *wcharString) const
 
int Find (const wchar_t *wcharString, int start_index) const
 
int Find (const wchar_t *wcharString, size_t start_index) const
 
int Find (unsigned char utf8_single_byte_c) const
 
int Find (unsigned char utf8_single_byte_c, size_t start_index) const
 
int Find (wchar_t w) const
 
int Find (wchar_t w, int start_index) const
 
int Find (wchar_t w, size_t start_index) const
 
int FindOneOf (const wchar_t *character_set) const
 
bool ON_VARGS_FUNC_CDECL Format (const wchar_t *format,...)
 
bool FormatVargs (const wchar_t *format, va_list args)
 
wchar_t GetAt (int) const
 
bool IsEmpty () const
 
bool IsNotEmpty () const
 returns true if length > 0 More...
 
bool IsReferenceCounted () const
 
bool IsValid (bool bLengthTest) const
 
ON_wString Left (int) const
 
int Length () const
 Attributes & Operations. More...
 
void MakeLower ()
 
void MakeLowerOrdinal ()
 
void MakeReverse ()
 
void MakeUpper ()
 upper/lower/reverse conversion More...
 
void MakeUpperOrdinal ()
 
ON_wString MapString (const class ON_Locale &locale, ON_StringMapType map_type) const
 
ON_wString MapStringOrdinal (ON_StringMapOrdinalType map_type) const
 
ON_wString Mid (int) const
 
ON_wString Mid (int, int) const
 simple sub-string extraction More...
 
const ON_String MultiByteEncode (int windows_code_page) const
 
 operator const wchar_t * () const
 
ON_wString operator+ (char) const
 
ON_wString operator+ (const char *sUTF8) const
 concatinate with a UTF-8 string More...
 
ON_wString operator+ (const ON_String &sUTF8) const
 concatinate with a UTF-8 string More...
 
ON_wString operator+ (const ON_wString &) const
 operator+() More...
 
ON_wString operator+ (const unsigned char *sUTF8) const
 concatinate with a UTF-8 string More...
 
ON_wString operator+ (const wchar_t *) const
 
ON_wString operator+ (unsigned char) const
 
ON_wString operator+ (wchar_t) const
 
const ON_wStringoperator+= (char)
 
const ON_wStringoperator+= (const char *sUTF8)
 append UTF-8 string More...
 
const ON_wStringoperator+= (const ON_String &sUTF8)
 append UTF-8 string More...
 
const ON_wStringoperator+= (const ON_wString &)
 
const ON_wStringoperator+= (const unsigned char *sUTF8)
 append UTF-8 string More...
 
const ON_wStringoperator+= (const wchar_t *)
 
const ON_wStringoperator+= (unsigned char)
 
const ON_wStringoperator+= (wchar_t)
 
const ON_wStringoperator= (char)
 
const ON_wStringoperator= (const char *src)
 src = UTF-8 string More...
 
const ON_wStringoperator= (const ON_String &src)
 src = UTF-8 string More...
 
const ON_wStringoperator= (const ON_wString &)
 overloaded assignment More...
 
const ON_wStringoperator= (const unsigned char *src)
 src = UTF-8 string More...
 
const ON_wStringoperator= (const wchar_t *)
 
const ON_wStringoperator= (unsigned char)
 
const ON_wStringoperator= (wchar_t)
 
wchar_t & operator[] (int)
 
wchar_t operator[] (int) const
 
int Remove (char utf8_single_byte_c)
 
int Remove (unsigned char utf8_single_byte_c)
 
int Remove (wchar_t w)
 
const ON_wString RemovePrefix (const wchar_t *prefix, const class ON_Locale &locale, bool bIgnoreCase) const
 
const ON_wString RemoveSuffix (const wchar_t *suffix, const class ON_Locale &locale, bool bIgnoreCase) const
 
int RemoveWhiteSpace (const wchar_t *whitespace=0)
 
int Replace (const wchar_t *token1, const wchar_t *token2)
 
int Replace (wchar_t token1, wchar_t token2)
 
int ReplaceWhiteSpace (wchar_t token, const wchar_t *whitespace=0)
 
wchar_t * ReserveArray (size_t capacity)
 
ON_wString Reverse () const
 
int ReverseFind (char utf8_single_byte_c) const
 
int ReverseFind (const char *sUTF8) const
 
int ReverseFind (const wchar_t *wideString) const
 
int ReverseFind (unsigned char utf8_single_byte_c) const
 
int ReverseFind (wchar_t w) const
 
ON_wString Right (int) const
 
int ON_VARGS_FUNC_CDECL Scan (const wchar_t *format,...) const
 
void SetAt (int, char)
 
void SetAt (int, unsigned char)
 
void SetAt (int, wchar_t)
 
wchar_t * SetLength (size_t)
 set length (<=capacity) More...
 
void ShrinkArray ()
 shrink internal storage to minimum size More...
 
unsigned int SizeOf () const
 
const ON_wString SubString (int start_index) const
 
const ON_wString SubString (int start_index, int count) const
 
void TrimLeft (const wchar_t *s=nullptr)
 
void TrimLeftAndRight (const wchar_t *s=nullptr)
 
void TrimRight (const wchar_t *s=nullptr)
 
unsigned int UnsignedLength () const
 
bool UrlDecode ()
 
void UrlEncode ()
 
bool WildCardMatch (const wchar_t *) const
 
bool WildCardMatchNoCase (const wchar_t *) const
 

Static Public Member Functions

static const ON_wString ApproximateFromNumber (double d)
 
static int ByteOrder (wchar_t bom_candidate)
 
static int Compare (const wchar_t *string1, const wchar_t *string2, const class ON_Locale &locale, bool bIgnoreCase)
 
static int Compare (const wchar_t *string1, int element_count1, const wchar_t *string2, int element_count2, const class ON_Locale &locale, bool bIgnoreCase)
 
static int CompareAttributeName (const wchar_t *name1, const wchar_t *name2)
 
static int CompareOrdinal (const wchar_t *string1, const wchar_t *string2, bool bOrdinalIgnoreCase)
 
static int CompareOrdinal (const wchar_t *string1, int element_count1, const wchar_t *string2, int element_count2, bool bOrdinalIgnoreCase)
 
static int ComparePath (const wchar_t *path1, const wchar_t *path2)
 
static int ComparePath (const wchar_t *path1, int element_count1, const wchar_t *path2, int element_count2)
 
static unsigned DecimalDigitFromWideChar (wchar_t c, bool bAcceptOrdinaryDigit, bool bAcceptSuperscriptDigit, bool bAcceptSubscriptDigit, unsigned invalid_c_result)
 
static bool Equal (const wchar_t *string1, const wchar_t *string2, const class ON_Locale &locale, bool bIgnoreCase)
 
static bool Equal (const wchar_t *string1, int element_count1, const wchar_t *string2, int element_count2, const class ON_Locale &locale, bool bIgnoreCase)
 
static bool EqualAttributeName (const wchar_t *name1, const wchar_t *name2)
 
static bool EqualOrdinal (const wchar_t *string1, const wchar_t *string2, bool bOrdinalIgnoreCase)
 
static bool EqualOrdinal (const wchar_t *string1, int element_count1, const wchar_t *string2, int element_count2, bool bOrdinalIgnoreCase)
 
static bool EqualPath (const wchar_t *path1, const wchar_t *path2)
 
static bool EqualPath (const wchar_t *path1, int element_count1, const wchar_t *path2, int element_count2)
 
static const ON_wString Example (ON_wString::ExampleType t)
 A selection of strings that can be used for testing. More...
 
static int ON_VARGS_FUNC_CDECL FormatIntoBuffer (ON_wStringBuffer &buffer, const wchar_t *format,...)
 
static int ON_VARGS_FUNC_CDECL FormatIntoBuffer (wchar_t *buffer, size_t buffer_capacity, const wchar_t *format,...)
 
static const ON_wString ON_VARGS_FUNC_CDECL FormatToString (const wchar_t *format,...)
 
static const ON_wString FormatToVulgarFraction (const ON_wString numerator, const ON_wString denominator)
 
static const ON_wString FormatToVulgarFraction (int numerator, int denominator)
 
static const ON_wString FormatToVulgarFraction (int numerator, int denominator, bool bReduced, bool bProper, unsigned int proper_fraction_separator_cp, bool bUseVulgarFractionCodePoints)
 
static const ON_wString FormatToVulgarFractionDenominator (const ON_wString denominator)
 
static const ON_wString FormatToVulgarFractionNumerator (const ON_wString numerator)
 
static int FormatVargsIntoBuffer (ON_wStringBuffer &buffer, const wchar_t *format, va_list args)
 
static int FormatVargsIntoBuffer (wchar_t *buffer, size_t buffer_capacity, const wchar_t *format, va_list args)
 
static int FormatVargsOutputCount (const wchar_t *format, va_list args)
 
static const ON_wString FromCurrentCoordinatedUniversalTime (ON_DateFormat date_format, ON_TimeFormat time_format, wchar_t date_separator, wchar_t date_time_separator, wchar_t time_separator)
 
static const ON_wString FromNumber (char n)
 
static const ON_wString FromNumber (double d)
 
static const ON_wString FromNumber (int n)
 
static const ON_wString FromNumber (ON__INT64 n)
 
static const ON_wString FromNumber (ON__UINT64 n)
 
static const ON_wString FromNumber (short n)
 
static const ON_wString FromNumber (unsigned char n)
 
static const ON_wString FromNumber (unsigned int n)
 
static const ON_wString FromNumber (unsigned short n)
 
static const ON_wString FromSecondsSinceJanuaryFirst1970 (ON__UINT64 seconds_since_jan_first_1970, ON_DateFormat date_format, ON_TimeFormat time_format, wchar_t date_separator, wchar_t date_time_separator, wchar_t time_separator)
 
static const ON_wString FromTime (const struct tm &t, ON_DateFormat date_format, ON_TimeFormat time_format, wchar_t date_separator, wchar_t date_time_separator, wchar_t time_separator)
 
static const ON_wString FromUnicodeCodePoint (ON__UINT32 code_point)
 
static const ON_wString FromUnicodeCodePoints (const ON__UINT32 *code_points, int code_point_count, ON__UINT32 error_code_point)
 
static const ON_wString FromYearDayHourMinuteSecond (int year, int day_of_year, int hour, int minute, int second, ON_DateFormat date_format, ON_TimeFormat time_format, wchar_t date_separator, wchar_t date_time_separator, wchar_t time_separator)
 
static const ON_wString FromYearMonthDayHourMinuteSecond (int year, int month, int mday, int hour, int minute, int second, ON_DateFormat date_format, ON_TimeFormat time_format, wchar_t date_separator, wchar_t date_time_separator, wchar_t time_separator)
 
static const ON_wString HexadecimalFromBytes (const ON__UINT8 *bytes, size_t byte_count, bool bCapitalDigits, bool bReverse)
 
static bool IsDecimalDigit (wchar_t c)
 
static bool IsDecimalDigit (wchar_t c, bool bOrdinaryDigitResult, bool bSuperscriptDigitResult, bool bSubscriptDigitResult)
 Determine if c is a decimal digit. More...
 
static bool IsHexDigit (wchar_t c)
 
static bool IsHorizontalSpace (wchar_t c)
 
static bool IsHorizontalSpace (wchar_t c, bool bTabResult, bool bNoBreakSpaceResult, bool bZeroWidthSpaceResult)
 
static bool IsSlash (wchar_t c, bool bOrdinarySlashResult, bool bFractionSlashResult, bool bDivisionSlashResult, bool bMathematicalSlashResult)
 Determine if c is some type opf Unicode slash (solidus). More...
 
static bool IsXMLSpecialCharacter (wchar_t c)
 Returns true if c is one of the 5 XML special characters & (ampersand), < (less than), > (greater than), " (quotation mark), or ' (apostrophe). More...
 
static int Length (const wchar_t *string)
 
static int Length (const wchar_t *string, size_t string_capacity)
 
static wchar_t MapCharacterOrdinal (ON_StringMapOrdinalType map_type, wchar_t c)
 
static ON_wString MapString (const class ON_Locale &locale, ON_StringMapType map_type, const wchar_t *string, int element_count)
 
static int MapString (const class ON_Locale &locale, ON_StringMapType map_type, const wchar_t *string, int element_count, wchar_t *mapped_string, int mapped_string_capacity)
 
static int MapStringOrdinal (ON_StringMapOrdinalType map_type, const wchar_t *string, int element_count, wchar_t *mapped_string, int mapped_string_capacity)
 
static const wchar_t * ParseHorizontalSpace (const wchar_t *s, int len)
 
static const wchar_t * ParseHorizontalSpace (const wchar_t *s, int len, bool bParseTab, bool bParseNoBreakSpace, bool bParseZeroWidthSpace)
 
static const wchar_t * ParseVulgarFraction (const wchar_t *s, int len, int &numerator, int &denomintor)
 
static const wchar_t * ParseXMLCharacterEncoding (const wchar_t *buffer, int buffer_length, unsigned value_on_failure, unsigned *unicode_code_point)
 
static const wchar_t * ParseXMLUnicodeCodePointEncoding (const wchar_t *buffer, int buffer_length, unsigned value_on_failure, unsigned *unicode_code_point)
 
static int PlusOrMinusSignFromWideChar (wchar_t c, bool bAcceptOrdinarySign, bool bAcceptSuperscriptSign, bool bAcceptSubscriptSign)
 
static const ON_wString PreciseFromNumber (double d)
 
static wchar_t * Reverse (wchar_t *string, int element_count)
 
static const ON_wString RichTextExample (const class ON_Font *font)
 Get a rich text example. More...
 
static const ON_wString RichTextExample (const class ON_FontFaceQuartet *quartet)
 Get a rich text example. More...
 
static const ON_wString RichTextExample (ON_wString rich_text_font_name, bool bBold, bool bItalic, bool bBoldItalic, bool bUnderline)
 Get a rich text example. More...
 
static int ON_VARGS_FUNC_CDECL ScanBuffer (const wchar_t *buffer, const wchar_t *format,...)
 
static int ScanBufferVargs (const wchar_t *buffer, const wchar_t *format, va_list args)
 
static void SplitPath (const char *path, ON_wString *drive, ON_wString *dir, ON_wString *fname, ON_wString *ext)
 
static void SplitPath (const wchar_t *path, ON_wString *drive, ON_wString *dir, ON_wString *fname, ON_wString *ext)
 
static wchar_t SwapByteOrder (wchar_t w)
 
static const ON_wString ToMemorySize (size_t sz)
 
static const wchar_t * ToNumber (const wchar_t *buffer, char value_on_failure, char *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, double value_on_failure, double *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, int value_on_failure, int *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, ON__INT64 value_on_failure, ON__INT64 *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, ON__UINT64 value_on_failure, ON__UINT64 *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, short value_on_failure, short *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, unsigned char value_on_failure, unsigned char *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, unsigned int value_on_failure, unsigned int *value)
 
static const wchar_t * ToNumber (const wchar_t *buffer, unsigned short value_on_failure, unsigned short *value)
 
static unsigned int UnsignedLength (const wchar_t *string)
 
static const ON_wString VulgarFractionSlash ()
 

Static Public Attributes

static const wchar_t Ampersand = (wchar_t)ON_UnicodeCodePoint::ON_Ampersand
 AMPERSAND U+0026 (&) More...
 
static const wchar_t Apostrophe = (wchar_t)ON_UnicodeCodePoint::ON_Apostrophe
 APOSTROPHE U+0027 (') More...
 
static const wchar_t Backslash = (wchar_t)ON_UnicodeCodePoint::ON_Backslash
 REVERSE SOLIDUS U+005C (&#x5c;) More...
 
static const wchar_t Backspace = (wchar_t)ON_UnicodeCodePoint::ON_Backspace
 BACKSPACE control U+0008 More...
 
static const ON_wString ByteOrderMark
 UTF-16/UTF-32 encoding of the Unicode byte order mark (BOM) U+FEFF. More...
 
static const wchar_t CarriageReturn = (wchar_t)ON_UnicodeCodePoint::ON_CarriageReturn
 CARRIAGE RETURN control U+000D More...
 
static const wchar_t Colon = (wchar_t)ON_UnicodeCodePoint::ON_Colon
 COLON U+003A (:) More...
 
static const wchar_t Comma = (wchar_t)ON_UnicodeCodePoint::ON_Comma
 COMMA U+002C (,) More...
 
static const wchar_t DecimalAsComma = (wchar_t)ON_UnicodeCodePoint::ON_Comma
 Comma decimal point (,) More...
 
static const wchar_t DecimalAsPeriod = (wchar_t)ON_UnicodeCodePoint::ON_Period
 Period decimal point (.) More...
 
static const ON_wString EmptyString
 ON_String::EmptyString has length 0. const char* s = ON_String::EmptyString sets s to L"". More...
 
static const wchar_t Escape = (wchar_t)ON_UnicodeCodePoint::ON_Escape
 ESCAPE control U+001B More...
 
static const wchar_t FormFeed = (wchar_t)ON_UnicodeCodePoint::ON_FormFeed
 FORM FEED control U+000C More...
 
static const wchar_t GreaterThanSign = (wchar_t)ON_UnicodeCodePoint::ON_GreaterThanSign
 GREATER-THAN SIGN U+003E (&#x3e;) More...
 
static const wchar_t HyphenMinus = (wchar_t)ON_UnicodeCodePoint::ON_HyphenMinus
 HYPHEN-MINUS U+002D (-) More...
 
static const wchar_t LessThanSign = (wchar_t)ON_UnicodeCodePoint::ON_LessThanSign
 LESS-THAN SIGN U+003C (&#x3c;) More...
 
static const wchar_t LineFeed = (wchar_t)ON_UnicodeCodePoint::ON_LineFeed
 LINE FEED control U+000A More...
 
static const wchar_t NumberSign = (wchar_t)ON_UnicodeCodePoint::ON_NumberSign
 NUMBER SIGN U+0023 (#) More...
 
static const wchar_t PercentSign = (wchar_t)ON_UnicodeCodePoint::ON_PercentSign
 PERCENT SIGN U+0025 (%) More...
 
static const wchar_t Period = (wchar_t)ON_UnicodeCodePoint::ON_Period
 PERIOD U+002E (decimal 46) (.) More...
 
static const wchar_t Pipe = (wchar_t)ON_UnicodeCodePoint::ON_Pipe
 VERTICAL LINE U+007C (&#x7c;) More...
 
static const wchar_t QuotationMark = (wchar_t)ON_UnicodeCodePoint::ON_QuotationMark
 QUOTATION MARK U+0022 (") More...
 
static const wchar_t Semicolon = (wchar_t)ON_UnicodeCodePoint::ON_Semicolon
 SEMICOLON U+003B (;) More...
 
static const wchar_t Slash = (wchar_t)ON_UnicodeCodePoint::ON_Slash
 SOLIDUS U+002F (&#x2f;) More...
 
static const wchar_t Space = (wchar_t)ON_UnicodeCodePoint::ON_Space
 SPACE U+0020 More...
 
static const wchar_t Tab = (wchar_t)ON_UnicodeCodePoint::ON_Tab
 CHARACTER TABULATION control U+0009 More...
 
static const wchar_t Tilde = (wchar_t)ON_UnicodeCodePoint::ON_Tilde
 TILDE U+007E (&#x7e;) More...
 
static const wchar_t Underscore = (wchar_t)ON_UnicodeCodePoint::ON_Underscore
 ///< Unicode LOW LINE U+005F (_) More...
 
static const wchar_t VerticalTab = (wchar_t)ON_UnicodeCodePoint::ON_VerticalTab
 LINE TABULATION control U+000B More...
 

Protected Member Functions

void AppendToArray (const ON_wString &)
 
void AppendToArray (int, const char *)
 
void AppendToArray (int, const unsigned char *)
 
void AppendToArray (int, const wchar_t *)
 
void CopyArray ()
 
void CopyToArray (const ON_wString &)
 
void CopyToArray (int, const char *)
 
void CopyToArray (int, const unsigned char *)
 
void CopyToArray (int, const wchar_t *)
 
wchar_t * CreateArray (int)
 
class ON_wStringHeader * Header () const
 m_s - 12 bytes points at the string's ON_wStringHeader More...
 
class ON_wStringHeader * IncrementedHeader () const
 

Protected Attributes

wchar_t * m_s
 Implementation. More...
 

Detailed Description

A wide character string. The default encoding is the encoding the compiler uses for wchar_t* s = L"..."; strings. This is typically 2 byte wchar_t UTF-16 on Windows and 4 byte wchar_t UTF-32 on MacOS. However, some MacOS SDK functions return 4 byte wchar_t UTF-16 strings.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum : int
Enumerator
MaximumStringLength 

This ON_String::MaximumStringLength value of 100,000,000 is used for string length sanity checking in both ON_String and ON_wString. The design of the ON_String and ON_wString classes could support string lengths up to 0xFFFFFFFEU = 4,294,967,294 but a cap of 100 million seems generous enough for current usage and is small enough to detect many corrupt memory situations. This value is used for both ON_String and ON_wString.

◆ ExampleType

enum ON_wString::ExampleType : unsigned int
strong

Identifies a built in string that can be used for testing.

Enumerator
Empty 

ON_wString::EmptyString

WideChar 

A wchar_t string that contains code points with 2, 3, 4, and 5 hex digit code points. Useful for testing what a compiler does with string that have UTF-8 multiple byte encodings and UTF-16 surrogate pair encodings. "The math teacher said, &#x5c;"It isn't true that &#x3a3; > 3&#xa2; & &#x3a3; < 2 &#x20bd; & &#x3a3; > &#x20ac;99.&#x5c;" &#x1f5d1;!"

UTF16 

The WideChar string UTF-16 encoded.

RichText 

The rich text string from ON_wString::RichTextExample(&ON_FOnt::Default).

XML 

The WideChar string as an XML value with special characters encoded in the &amp; format and code points above basic latin UTF-16 encoded.

XMLalternate1 

The WideChar string as an XML value with special characters encoded in the &amp; format and code points above basic latin encoded in the &#hhhh; format using lower case hex digits (0123456789abcdef).

XMLalternate2 

The WideChar string as an XML value with special characters encoded in the &amp; format and code points above basic latin encoded in the hexadecimal &#xhhhh; format with upper case hex digits (0123456789ABCDEF).

XMLalternate3 

The WideChar string as an XML value with special characters and code points above basic latin encoded in the decimal code point &#nnnn; format.

Constructor & Destructor Documentation

◆ ON_wString() [1/12]

ON_wString::ON_wString ( )

Constructors.

◆ ON_wString() [2/12]

ON_wString::ON_wString ( const ON_wString )

◆ ON_wString() [3/12]

ON_wString::ON_wString ( const ON_String src)

src = UTF-8 string

◆ ON_wString() [4/12]

ON_wString::ON_wString ( const char *  src)

src = nul; terminated UTF-8 string

◆ ON_wString() [5/12]

ON_wString::ON_wString ( const char *  src,
int   
)

from UTF-8 substring

◆ ON_wString() [6/12]

ON_wString::ON_wString ( char  ,
int  = 1 
)

◆ ON_wString() [7/12]

ON_wString::ON_wString ( const unsigned char *  src)

src = nul; terminated UTF-8 string

◆ ON_wString() [8/12]

ON_wString::ON_wString ( const unsigned char *  src,
int   
)

from UTF-8 substring

◆ ON_wString() [9/12]

ON_wString::ON_wString ( unsigned char  ,
int  = 1 
)

◆ ON_wString() [10/12]

ON_wString::ON_wString ( const wchar_t *  )

◆ ON_wString() [11/12]

ON_wString::ON_wString ( const wchar_t *  ,
int   
)

from substring

◆ ON_wString() [12/12]

ON_wString::ON_wString ( wchar_t  ,
int  = 1 
)

◆ ~ON_wString()

ON_wString::~ON_wString ( )

Member Function Documentation

◆ Append() [1/3]

void ON_wString::Append ( const char *  sUTF8,
int   
)

string concatenation

append specified number of elements from a UTF-8 string

◆ Append() [2/3]

void ON_wString::Append ( const unsigned char *  sUTF8,
int   
)

append specified number of elements from a UTF-8 string

◆ Append() [3/3]

void ON_wString::Append ( const wchar_t *  ,
int   
)

append specified number of elements

◆ AppendToArray() [1/4]

void ON_wString::AppendToArray ( const ON_wString )
protected

◆ AppendToArray() [2/4]

void ON_wString::AppendToArray ( int  ,
const char *   
)
protected

◆ AppendToArray() [3/4]

void ON_wString::AppendToArray ( int  ,
const unsigned char *   
)
protected

◆ AppendToArray() [4/4]

void ON_wString::AppendToArray ( int  ,
const wchar_t *   
)
protected

◆ ApproximateFromNumber()

static const ON_wString ON_wString::ApproximateFromNumber ( double  d)
static
Parameters
d"%f" when possible, otherwise "%g"

◆ Array() [1/2]

wchar_t* ON_wString::Array ( )

◆ Array() [2/2]

const wchar_t* ON_wString::Array ( ) const

◆ ByteOrder()

static int ON_wString::ByteOrder ( wchar_t  bom_candidate)
static

Parameters: bom_candidate - [in] Returns; 1: bom_candidate = ON_UnicodeCodePoint::ON_ByteOrderMark -1: After swapping bytes, bom_candidate = ON_UnicodeCodePoint::ON_ByteOrderMark 0: otherwise

◆ Compare() [1/5]

int ON_wString::Compare ( const ON_wString other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

Description: Compare this string and other_string by normalizing (NFC) and using invariant culture ordering. Parameters: other_string - [in] bIgnoreCase - [in] Remarks: 1) Ordinal compares are the fastest. 2) Equal(...) is faster than Compare(...)

◆ Compare() [2/5]

int ON_wString::Compare ( const wchar_t *  ) const

ON_DEPRECATED ///< deprecation in progress.

Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate

◆ Compare() [3/5]

int ON_wString::Compare ( const wchar_t *  other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

◆ Compare() [4/5]

static int ON_wString::Compare ( const wchar_t *  string1,
const wchar_t *  string2,
const class ON_Locale locale,
bool  bIgnoreCase 
)
static

Description: Compare string1 and string2 by normalizing (NFC) and using invariant culture ordering. Parameters: string1 - [in] string2 - [in] bIgnoreCase - [in] Remarks: 1) Ordinal compares are the fastest. 2) Equal(...) is faster than Compare(...)

◆ Compare() [5/5]

static int ON_wString::Compare ( const wchar_t *  string1,
int  element_count1,
const wchar_t *  string2,
int  element_count2,
const class ON_Locale locale,
bool  bIgnoreCase 
)
static

Description: Compare string1 and string2 by normalizing (NFC) and using invariant culture ordering. Parameters: string1 - [in] element_count1 - [in] The number of string1[] elements to compare. If element_count1 < 0, then string1 must be null terminated. string2 - [in] element_count2 - [in] The number of string2[] elements to compare. If element_count2 < 0, then string2 must be null terminated. locale - [in] Typically ON_Locale::Ordinal, ON_Locale::InvariantCulture, or ON_Locale::CurrentCulture. bIgnoreCase - [in] Remarks: 1) Ordinal compares are the fastest. 2) Equal(...) is faster than Compare(...)

◆ CompareAttributeName() [1/2]

static int ON_wString::CompareAttributeName ( const wchar_t *  name1,
const wchar_t *  name2 
)
static

Description: Compare this string and other_name as a name attribute of an object like ON_3dmObjectAttributes.m_name, ON_Layer.m_name, and so on. These comparisons ignore case and use appropriate string normalization.
Parameters: name1 - [in] null terminated string name2 - [in] null terminated string

◆ CompareAttributeName() [2/2]

int ON_wString::CompareAttributeName ( const wchar_t *  other_name) const

Description: Compare this string and other_name as a name attribute of an object like ON_3dmObjectAttributes.m_name, ON_Layer.m_name, and so on. These comparisons ignore case and use appropriate string normalization.
Parameters: other_name - [in] null terminated string

◆ CompareNoCase()

int ON_wString::CompareNoCase ( const wchar_t *  ) const

ON_DEPRECATED ///< deprecation in progress.

Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate

◆ CompareOrdinal() [1/4]

int ON_wString::CompareOrdinal ( const ON_wString other_string,
bool  bOrdinalIgnoreCase 
) const

Description: Compare this string and other_string wchar_t element by wchar_t element. Parameters: other_string - [in] bOrdinalIgnoreCase - [in] Remarks: 1) If the string is UTF-8 encoded and bOrdinalIgnoreCase is true, only small latin a - z and capital latin A - Z are considered equal. It is imposible to ignore case for any other values in an ordinal compare.

2) If you are comparing file system paths, you should use ComparePath().

3) If locale, linguistic issues, UTF-8 encoding issues or unicode normalization or collation issues need to be considered, then CompareOrdinal() is the wrong function to use.

◆ CompareOrdinal() [2/4]

int ON_wString::CompareOrdinal ( const wchar_t *  other_string,
bool  bOrdinalIgnoreCase 
) const

◆ CompareOrdinal() [3/4]

static int ON_wString::CompareOrdinal ( const wchar_t *  string1,
const wchar_t *  string2,
bool  bOrdinalIgnoreCase 
)
static

Description: Compare this string1 and string2 wchar_t element by wchar_t element. Parameters: string1 - [in] string2 - [in] bOrdinalIgnoreCase - [in] If true, elements with values a-z are compared as if they had values A-Z. Remarks: 1) If the string is UTF-8 encoded and bOrdinalIgnoreCase is true, only small latin a - z and capital latin A - Z are considered equal. It is imposible to ignore case for any other values in an ordinal compare.

2) If you are comparing file system paths, you should use ComparePath().

3) If locale, linguistic issues, UTF-8 encoding issues or unicode normalization or collation issues need to be considered, then CompareOrdinal() is the wrong function to use.

◆ CompareOrdinal() [4/4]

static int ON_wString::CompareOrdinal ( const wchar_t *  string1,
int  element_count1,
const wchar_t *  string2,
int  element_count2,
bool  bOrdinalIgnoreCase 
)
static

Description: Compare this string1 and string2 wchar_t element by wchar_t element. Parameters: string1 - [in] maximum_element_count1 - [in] maximum number of elements to compare string2 - [in] maximum_element_count2 - [in] maximum number of elements to compare bOrdinalIgnoreCase - [in] If true, elements with values a-z are compared as if they had values A-Z. Remarks: 1) If the string is UTF-8 encoded and bOrdinalIgnoreCase is true, only small latin a - z and capital latin A - Z are considered equal. It is imposible to ignore case for any other values in an ordinal compare.

2) If you are comparing file system paths, you should use ComparePath().

3) If locale, linguistic issues, UTF-8 encoding issues or unicode normalization or collation issues need to be considered, then CompareOrdinal() is the wrong function to use.

◆ ComparePath() [1/3]

int ON_wString::ComparePath ( const wchar_t *  other_path) const

Description: Compare this string and other_path as file system paths using appropriate tests for the current operating system. Parameters: other_path - [in] null terminated string Remarks: 1) Windows and UNIX directory separators (/ and ) are considered equal.

2) Case is ignored when the file system is not case sensitive, like Windows.

3) String normalization appropriate for the current operating system is performed.

◆ ComparePath() [2/3]

static int ON_wString::ComparePath ( const wchar_t *  path1,
const wchar_t *  path2 
)
static

Description: Compare sPath1 and sPath2 as file system paths using appropriate tests for the current operating system. Parameters: path1 - [in] null terminated string path2 - [in] null terminated string Remarks: 1) Windows and UNIX directory separators (/ and ) are considered equal.

2) Case is ignored when the file system is not case sensitive, like Windows.

3) String normalization appropriate for the current operating system is performed.

◆ ComparePath() [3/3]

static int ON_wString::ComparePath ( const wchar_t *  path1,
int  element_count1,
const wchar_t *  path2,
int  element_count2 
)
static

Description: Compare sPath1 and sPath2 as file system paths using appropriate tests for the current operating system. Parameters: path1 - [in] maximum_element_count1 - [in] path2 - [in] maximum_element_count2 - [in] Remarks: 1) Windows and UNIX directory separators (/ and ) are considered equal.

2) Case is ignored when the file system is not case sensitive, like Windows.

3) String normalization appropriate for the current operating system is performed.

◆ ContentHash()

const ON_SHA1_Hash ON_wString::ContentHash ( ON_StringMapOrdinalType  mapping) const

Returns: A platform independed SHA-1 of the string content. Independent of platform endian or platform wide string UTF encoding.

◆ CopyArray()

void ON_wString::CopyArray ( )
protected

◆ CopyToArray() [1/4]

void ON_wString::CopyToArray ( const ON_wString )
protected

◆ CopyToArray() [2/4]

void ON_wString::CopyToArray ( int  ,
const char *   
)
protected

◆ CopyToArray() [3/4]

void ON_wString::CopyToArray ( int  ,
const unsigned char *   
)
protected

◆ CopyToArray() [4/4]

void ON_wString::CopyToArray ( int  ,
const wchar_t *   
)
protected

◆ Create()

void ON_wString::Create ( )

◆ CreateArray()

wchar_t* ON_wString::CreateArray ( int  )
protected

◆ DataCRC()

ON__UINT32 ON_wString::DataCRC ( ON__UINT32  current_remainder) const

Returns: CRC of the string.

◆ DataCRCLower()

ON__UINT32 ON_wString::DataCRCLower ( ON__UINT32  current_remainder) const

Returns: CRC of the lower case version of the string. Useful for case insensitive CRCs and hash codes.

◆ DecimalDigitFromWideChar()

static unsigned ON_wString::DecimalDigitFromWideChar ( wchar_t  c,
bool  bAcceptOrdinaryDigit,
bool  bAcceptSuperscriptDigit,
bool  bAcceptSubscriptDigit,
unsigned  invalid_c_result 
)
static

◆ DecodeXMLValue()

const ON_wString ON_wString::DecodeXMLValue ( ) const

Description: Decode an XML encoded value. Examples: < is replaced with < (less-than). > is replaced with > (greater-than). & is replaced with & (ampersand). ' is replaced with ' (apostrophe or single quote). " is replaced with " (double-quote). &#nnnn; where nnnn is a valid decimal unicode code point is replaced with the wide character encode code point. &#xhhhh; where hhhh is a valid hexadecimal unicode code point is replaced with the wide character encode code point. Returns: This string with every instance of an xml encodecharacter encodeding replaced with the corresponding wide character encodeing of the literal unicode code point.

◆ Destroy()

void ON_wString::Destroy ( )

releases any memory and initializes to default empty string

◆ Duplicate()

const ON_wString ON_wString::Duplicate ( ) const

Returns: A duplicate of this that does not share memory with any other string. (A new array is allocated for the returned string.)

◆ EmergencyDestroy()

void ON_wString::EmergencyDestroy ( )

◆ Empty()

void ON_wString::Empty ( )

sets length to zero - if possible, memory is retained

◆ EnableReferenceCounting()

void ON_wString::EnableReferenceCounting ( bool  bEnable)
Deprecated:
Obsolete - does nothing.

◆ EncodeXMLValue() [1/2]

const ON_wString ON_wString::EncodeXMLValue ( ) const

Description: Convert a literal string into an XML encoded value.

< (less-than) is replaced with <

(greater-than) is replaced with >

& (ampersand) is replaces with & ' (apostrophe or single quote) is replaced with ' " (double-quote) is replaced with "

Optionally, unocode code points U+hhhh where hhhh >= 0x80 are replaced with &#xhhhh; using the minimal number of hex digits. Parameters: bUseUnicodeCodePointsForSpecialCharacters - [in] If true, the &#60;, &#62;, &#38;, &#39;, and &#34; encodings are used. If false, the < > &, ', and " encodings are used. When in doubt, pass false. bEncodeCodePointsAboveBasicLatin If true, any code point >= 0x80 is encoded using the XML format. When human readability is important and the XML will be parsed by a high quality XML reader, pass false. (The XMLspecification supports text files that are UTF=8, UTF-18, or UTF-32 encoded.) Returns: A string with every instance of an xml special character replaced with its xml encoding and, optionally, every code point > 127 replaced with .

◆ EncodeXMLValue() [2/2]

const ON_wString ON_wString::EncodeXMLValue ( bool  bEncodeCodePointsAboveBasicLatin) const

◆ Equal() [1/4]

bool ON_wString::Equal ( const ON_wString other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

◆ Equal() [2/4]

bool ON_wString::Equal ( const wchar_t *  other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

◆ Equal() [3/4]

static bool ON_wString::Equal ( const wchar_t *  string1,
const wchar_t *  string2,
const class ON_Locale locale,
bool  bIgnoreCase 
)
static

◆ Equal() [4/4]

static bool ON_wString::Equal ( const wchar_t *  string1,
int  element_count1,
const wchar_t *  string2,
int  element_count2,
const class ON_Locale locale,
bool  bIgnoreCase 
)
static

Description: Determine if string 1 and string2 are equal. Parameters: string1 - [in] element_count1 - [in] The number of string1[] elements to test. If element_count1 < 0, then string1 must nullptr or be null terminated. string2 - [in] element_count2 - [in] The number of string2[] elements to test. If element_count1 < 0, then string2 must nullptr or be null terminated. locale - [in] Typically ON_Locale::Ordinal, ON_Locale::InvariantCulture, or ON_Locale::CurrentCulture. bIgnoreCase - [in] Remarks: 1) Ordinal compares are the fastest. 2) Equal(...) is faster than Compare(...)

◆ EqualAttributeName() [1/2]

static bool ON_wString::EqualAttributeName ( const wchar_t *  name1,
const wchar_t *  name2 
)
static

◆ EqualAttributeName() [2/2]

bool ON_wString::EqualAttributeName ( const wchar_t *  other_name) const

◆ EqualOrdinal() [1/4]

bool ON_wString::EqualOrdinal ( const ON_wString other_string,
bool  bOrdinalIgnoreCase 
) const

◆ EqualOrdinal() [2/4]

bool ON_wString::EqualOrdinal ( const wchar_t *  other_string,
bool  bOrdinalIgnoreCase 
) const

◆ EqualOrdinal() [3/4]

static bool ON_wString::EqualOrdinal ( const wchar_t *  string1,
const wchar_t *  string2,
bool  bOrdinalIgnoreCase 
)
static

◆ EqualOrdinal() [4/4]

static bool ON_wString::EqualOrdinal ( const wchar_t *  string1,
int  element_count1,
const wchar_t *  string2,
int  element_count2,
bool  bOrdinalIgnoreCase 
)
static

◆ EqualPath() [1/3]

bool ON_wString::EqualPath ( const wchar_t *  other_path) const

◆ EqualPath() [2/3]

static bool ON_wString::EqualPath ( const wchar_t *  path1,
const wchar_t *  path2 
)
static

◆ EqualPath() [3/3]

static bool ON_wString::EqualPath ( const wchar_t *  path1,
int  element_count1,
const wchar_t *  path2,
int  element_count2 
)
static

◆ Example()

static const ON_wString ON_wString::Example ( ON_wString::ExampleType  t)
static

A selection of strings that can be used for testing.

◆ Find() [1/14]

int ON_wString::Find ( char  utf8_single_byte_c) const

Description: Find the first occurrence of a character or substring. Parameters: utf8_single_byte_c - [in] utf8_single_byte_c must have a value between 0 and 0x7F. w - [in] When w is a 2 byte UTF-16 wchar_t value (like Microsoft's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0xFFFF. When w is a 4 byte UTF-32 wchar_t value (like Apple's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0x10FFFF. sTUF8 - [in] A null terminated UTF-8 string. wcharString - [in] A null terminated wchar_t string. start_index - [in] Index where search should begin. Returns: -1: invalid input or character is not in the string. >=0: Index of the first instance of the character.

◆ Find() [2/14]

int ON_wString::Find ( char  utf8_single_byte_c,
size_t  start_index 
) const

◆ Find() [3/14]

int ON_wString::Find ( const char *  sUTF8) const

◆ Find() [4/14]

int ON_wString::Find ( const char *  sUTF8,
size_t  start_index 
) const

◆ Find() [5/14]

int ON_wString::Find ( const unsigned char *  sUTF8) const

◆ Find() [6/14]

int ON_wString::Find ( const unsigned char *  sUTF8,
size_t  start_index 
) const

◆ Find() [7/14]

int ON_wString::Find ( const wchar_t *  wcharString) const

◆ Find() [8/14]

int ON_wString::Find ( const wchar_t *  wcharString,
int  start_index 
) const

◆ Find() [9/14]

int ON_wString::Find ( const wchar_t *  wcharString,
size_t  start_index 
) const

◆ Find() [10/14]

int ON_wString::Find ( unsigned char  utf8_single_byte_c) const

◆ Find() [11/14]

int ON_wString::Find ( unsigned char  utf8_single_byte_c,
size_t  start_index 
) const

◆ Find() [12/14]

int ON_wString::Find ( wchar_t  w) const

◆ Find() [13/14]

int ON_wString::Find ( wchar_t  w,
int  start_index 
) const

◆ Find() [14/14]

int ON_wString::Find ( wchar_t  w,
size_t  start_index 
) const

◆ FindOneOf()

int ON_wString::FindOneOf ( const wchar_t *  character_set) const

◆ Format()

bool ON_VARGS_FUNC_CDECL ON_wString::Format ( const wchar_t *  format,
  ... 
)

Parameters: format - [in] Format control. Positional paramters of the form N$x where N >= 1 and x is the standard format specification are supported. Avoid using S (capital S). See the Remarks for details. ... - [in] arguments for replacable items in the format string. Returns: True if successful. False if the string is too long or the format string is not valid. Remarks: When using Microsoft's compiler and other compilers that provide similar locale support, the locale is the invariant culture locale returned by ON_Locale::InvariantCulture::LocalePtr().

The way Windows handles the S (capital S) format parameter depends on locale and code page settings. It is strongly reccommended that you never use S to include any string that may possibly contain elements with values > 127. The following examples illustrate a way to predictably use UTF-8 and wchar_t parameters in buffers of the other element type.

const char* utf8_string = ...; / UNRELIABLE ///< ON_wString::Format(buffer,buffer_capacity,"%S",utf8_string); / The code below will treat utf8_string as a UTF-8 encoded string. wchar_t wchar_buffer[...]; const size_t wchar_buffer_capacity= sizeof(buffer)/sizeof(buffer[0]); ON_wString::Format(wchar_buffer, wchar_buffer_capacity, "%s", ON_wString(utf8_string));

const wchar_t* wide_string = ...; / UNRELIABLE ///< ON_wString::Format(buffer,buffer_capacity,"%S",char_string); / The code below will include wide_string as a UTF-8 encoded string. char char_buffer[...]; const size_t char_buffer_capacity = sizeof(buffer)/sizeof(buffer[0]); ON_String::Format(char_buffer, char_buffer_capacity, "%s", ON_String(wide_string));

◆ FormatIntoBuffer() [1/2]

static int ON_VARGS_FUNC_CDECL ON_wString::FormatIntoBuffer ( ON_wStringBuffer buffer,
const wchar_t *  format,
  ... 
)
static

◆ FormatIntoBuffer() [2/2]

static int ON_VARGS_FUNC_CDECL ON_wString::FormatIntoBuffer ( wchar_t *  buffer,
size_t  buffer_capacity,
const wchar_t *  format,
  ... 
)
static

Description: A platform independent, secure, culture invariant way to format a wchar_t string with support for positional format parameters. This function is provide to be used when it is critical that the formatting be platform independent, secure and culture invarient. Parameters: buffer - [out] not null buffer_capacity - [in] > 0 Number of wchar_t elements in buffer. format - [in] Avoid using S (capital S). See the Remarks for details. ... - [in] Returns: >= 0: The number of wchar_t elements written to buffer[], not including the null terminator. A null terminator is always added (buffer[returned value] = 0). The last element of buffer[] is always set to zero (buffer[buffer_capacity-1] = 0). < 0: failure: If buffer is not null and buffer_capacity > 0, then buffer[0] = 0 and buffer[buffer_capacity-1] = 0; Remarks: The way Windows handles the S (capital S) format parameter depends on locale and code page settings. It is strongly reccommended that you never use S to include any string that may possibly contain elements with values > 127.
The following examples illustrate a way to predictably use UTF-8 and wchar_t parameters in buffers of the other element type.

 const char* utf8_string = ...;

/ UNRELIABLE ///< ON_wString::Format(buffer,buffer_capacity,"%S",utf8_string); wchar_t wchar_buffer[...]; const size_t wchar_buffer_capacity= sizeof(buffer)/sizeof(buffer[0]); ON_wString::Format(wchar_buffer, wchar_buffer_capacity, "%s", ON_wString(utf8_string));

const wchar_t* wide_string = ...; / UNRELIABLE ///< ON_wString::Format(buffer,buffer_capacity,"%S",char_string); char char_buffer[...]; const size_t char_buffer_capacity = sizeof(buffer)/sizeof(buffer[0]); ON_String::Format(char_buffer, char_buffer_capacity, "%s", ON_String(wide_string));

◆ FormatToString()

static const ON_wString ON_VARGS_FUNC_CDECL ON_wString::FormatToString ( const wchar_t *  format,
  ... 
)
static

◆ FormatToVulgarFraction() [1/3]

static const ON_wString ON_wString::FormatToVulgarFraction ( const ON_wString  numerator,
const ON_wString  denominator 
)
static

numerator - [in] A string (digits, signs, parenthesis). denominator - [in] A string (digits, signs, parenthesis). bUseVulgarFractionCodePoints - [in] If true and if Unicode code point exists for the fraction (halves, thirds, fourths, fifths, sixths, eights, ...), that code point will be used;
Returns: A Unicode encoding of the fraction numerator/denominator.

◆ FormatToVulgarFraction() [2/3]

static const ON_wString ON_wString::FormatToVulgarFraction ( int  numerator,
int  denominator 
)
static

Returns: A Unicode encoding of the fraction numerator/denominator with the minimum number of characters. The fraction is reduced and the encoding is a short as possible.

◆ FormatToVulgarFraction() [3/3]

static const ON_wString ON_wString::FormatToVulgarFraction ( int  numerator,
int  denominator,
bool  bReduced,
bool  bProper,
unsigned int  proper_fraction_separator_cp,
bool  bUseVulgarFractionCodePoints 
)
static

Returns: A Unicode encoding of the fraction numerator/denominator with the minimum number of characters. bReduced - [in] When in doubt, pass true. If true, then the reduced fraction will be returned. For example, if bReduced is true, then 2/4 reduces to 1/2. bProper - [in] When in doubt, pass true. If true, then proper fractions will be returned when abs(numerator)>=abs(denominator). For example, if bProper is true, then 4/3 is converted to 1-1/3. The symbol between the whole number and the proper fraction is specified by mixed_fraction_separator_code_point. proper_fraction_separator_cp - [in] Species the Unicode code point of the symbol used to separate the whole number and the proper fraction.

When in doubt, pass ON_UnicodeCodePoint::ON_NullCodePoint (0) which will result in the large whole number being next to the proper fraction in a readable and compact manner.

Other options include:

Spaces: ON_UnicodeCodePoint::ON_NarrowNoBreakSpace ON_UnicodeCodePoint::ON_NoBreakSpace ON_UnicodeCodePoint::ON_ZeroWidthSpace ON_UnicodeCodePoint::ON_Space ON_UnicodeCodePoint::ON_EnSpace ON_UnicodeCodePoint::ON_EmSpace ON_UnicodeCodePoint::ON_FigureSpace ON_UnicodeCodePoint::ON_MediumMathematicalSpace ON_UnicodeCodePoint::ON_ThinSpace ON_UnicodeCodePoint::ON_HairSpace ON_UnicodeCodePoint::ON_PunctuationSpace ON_UnicodeCodePoint::ON_ThreePerEmSpace ON_UnicodeCodePoint::ON_FourPerEmSpace ON_UnicodeCodePoint::ON_SixPerEmSpace

Hyphens: ON_UnicodeCodePoint::ON_HyphenMinus ON_UnicodeCodePoint::ON_UnambiguousHyphen ON_UnicodeCodePoint::ON_NoBreakHyphen ON_UnicodeCodePoint::ON_SmallHyphen

Dashes: ON_UnicodeCodePoint::ON_FigureDash ON_UnicodeCodePoint::ON_EnDash ON_UnicodeCodePoint::ON_EmDash

bUseVulgarFractionCodePoints - [in] When in doubt, pass true. If true and a single Unicode code point exists for the vulgar fraction (1/2, 1/3, 2/3, 1/4, 3/4, 1/5, 2/5, 3/5, 4/5, 1/6, 5/6, 1/7, 1/8, 3/8, 5/8, 7/8, 1/9, 1/10), then that code point will be used. Otherwise a Unicode superscript digits, ON_UnicodeCodePoint::FractionSlash, and Unicode subscript digits are used.

◆ FormatToVulgarFractionDenominator()

static const ON_wString ON_wString::FormatToVulgarFractionDenominator ( const ON_wString  denominator)
static

denominator - [in] A string (digits, signs, parenthesis). Returns: A Unicode encoding of the fraction's denominator.

◆ FormatToVulgarFractionNumerator()

static const ON_wString ON_wString::FormatToVulgarFractionNumerator ( const ON_wString  numerator)
static

numerator - [in] A string (digits, signs, parenthesis). Returns: A Unicode encoding of the fraction's numerator.

◆ FormatVargs()

bool ON_wString::FormatVargs ( const wchar_t *  format,
va_list  args 
)

◆ FormatVargsIntoBuffer() [1/2]

static int ON_wString::FormatVargsIntoBuffer ( ON_wStringBuffer buffer,
const wchar_t *  format,
va_list  args 
)
static

◆ FormatVargsIntoBuffer() [2/2]

static int ON_wString::FormatVargsIntoBuffer ( wchar_t *  buffer,
size_t  buffer_capacity,
const wchar_t *  format,
va_list  args 
)
static

◆ FormatVargsOutputCount()

static int ON_wString::FormatVargsOutputCount ( const wchar_t *  format,
va_list  args 
)
static

Returns: >= 0: Number of char elements in the formatted string, not including the null terminator. < 0: Invalid input

◆ FromCurrentCoordinatedUniversalTime()

static const ON_wString ON_wString::FromCurrentCoordinatedUniversalTime ( ON_DateFormat  date_format,
ON_TimeFormat  time_format,
wchar_t  date_separator,
wchar_t  date_time_separator,
wchar_t  time_separator 
)
static

Description: Get the Gregorian calendar current coordinated universal time as a string. Parameters: date_format - [in] date_format - [in] time_format - [in] date_separator - [in] Character placed between the year, month and day values. If 0, then ON_wString::HyphenMinus is used to date_time_separator - [in] Character placed between the date and time. If 0, then ON_wString::Space is used. time_separator - [in] Character placed between the hour, minute, and second values. If 0, then : (colon) is used. Returns: A string value for the current coordinated universal time (UTC).

◆ FromNumber() [1/9]

static const ON_wString ON_wString::FromNumber ( char  n)
static

It is common to format single numbers into strings and the FromNumber and FromDouble functions are the fastest way to do this and provide consistent results. They return a pointer to their buffer so the can be used as function parameters.

◆ FromNumber() [2/9]

static const ON_wString ON_wString::FromNumber ( double  d)
static
Parameters
d"%g" format

◆ FromNumber() [3/9]

static const ON_wString ON_wString::FromNumber ( int  n)
static

◆ FromNumber() [4/9]

static const ON_wString ON_wString::FromNumber ( ON__INT64  n)
static

◆ FromNumber() [5/9]

static const ON_wString ON_wString::FromNumber ( ON__UINT64  n)
static

◆ FromNumber() [6/9]

static const ON_wString ON_wString::FromNumber ( short  n)
static

◆ FromNumber() [7/9]

static const ON_wString ON_wString::FromNumber ( unsigned char  n)
static

◆ FromNumber() [8/9]

static const ON_wString ON_wString::FromNumber ( unsigned int  n)
static

◆ FromNumber() [9/9]

static const ON_wString ON_wString::FromNumber ( unsigned short  n)
static

◆ FromSecondsSinceJanuaryFirst1970()

static const ON_wString ON_wString::FromSecondsSinceJanuaryFirst1970 ( ON__UINT64  seconds_since_jan_first_1970,
ON_DateFormat  date_format,
ON_TimeFormat  time_format,
wchar_t  date_separator,
wchar_t  date_time_separator,
wchar_t  time_separator 
)
static

Description: Get the Gregorian calendar date and time as a string. Parameters: seconds - [in] number of seconds since January 1, 1970 00:00:00. date_format - [in] date_format - [in] time_format - [in] date_separator - [in] Character placed between the year, month and day values. If 0, then ON_wString::HyphenMinus is used to date_time_separator - [in] Character placed between the date and time. If 0, then ON_wString::Space is used. time_separator - [in] Character placed between the hour, minute, and second values. If 0, then : (colon) is used.

◆ FromTime()

static const ON_wString ON_wString::FromTime ( const struct tm &  t,
ON_DateFormat  date_format,
ON_TimeFormat  time_format,
wchar_t  date_separator,
wchar_t  date_time_separator,
wchar_t  time_separator 
)
static

Description: Get the Gregorian calendar date and time as a string. Parameters: t - [in] Gregorian calendar time to format date_format - [in] date_format - [in] time_format - [in] date_separator - [in] Character placed between the year, month and day values. If 0, then ON_wString::HyphenMinus is used to date_time_separator - [in] Character placed between the date and time. If 0, then ON_wString::Space is used. time_separator - [in] Character placed between the hour, minute, and second values. If 0, then : (colon) is used.

◆ FromUnicodeCodePoint()

static const ON_wString ON_wString::FromUnicodeCodePoint ( ON__UINT32  code_point)
static

◆ FromUnicodeCodePoints()

static const ON_wString ON_wString::FromUnicodeCodePoints ( const ON__UINT32 code_points,
int  code_point_count,
ON__UINT32  error_code_point 
)
static

Description: Convert a list of Unicode code points into a wide string. Parameters: code_points - [in] array of Unicode code points code_point_count - [in] number of code points. -1 indicates code_points[] is terminated by a 0 value. error_code_point - [in] If error_code_point is a valid Unicode code point, then error_code_point will be used in place of invalid values in code_points[]. Otherwise, conversion will terminate if code_points[] contains an invalid value. The values ON_UnicodeCodePoint::ON_ReplacementCharacter and ON_UnicodeCodePoint::ON_InvalidCodePoint are commonly used for this parameter. Returns: A wide string encoding of the Unicode code points. Remarks: If more control over the conversion process is required, then use ON_ConvertUTF32ToWideChar().

◆ FromYearDayHourMinuteSecond()

static const ON_wString ON_wString::FromYearDayHourMinuteSecond ( int  year,
int  day_of_year,
int  hour,
int  minute,
int  second,
ON_DateFormat  date_format,
ON_TimeFormat  time_format,
wchar_t  date_separator,
wchar_t  date_time_separator,
wchar_t  time_separator 
)
static

Description: Get the Gregorian calendar date and time as a string. The year value must be >= 1582 (beginning of Gregorian calendar). Parameters: year - [in] year >= 1582 (beginning of Gregorian calendar) day_of_year - [in] 1 to 366 hour - [in] 0 to 23 minute - [in] 0 to 59 second - [in] 0 to 59 date_format - [in] date_format - [in] time_format - [in] date_separator - [in] Character placed between the year, month and day values. If 0, then ON_wString::HyphenMinus is used to date_time_separator - [in] Character placed between the date and time. If 0, then ON_wString::Space is used. time_separator - [in] Character placed between the hour, minute, and second values. If 0, then : (colon) is used.

◆ FromYearMonthDayHourMinuteSecond()

static const ON_wString ON_wString::FromYearMonthDayHourMinuteSecond ( int  year,
int  month,
int  mday,
int  hour,
int  minute,
int  second,
ON_DateFormat  date_format,
ON_TimeFormat  time_format,
wchar_t  date_separator,
wchar_t  date_time_separator,
wchar_t  time_separator 
)
static

Description: Get the Gregorian calendar date and time as a string. The year value must be >= 1582 (beginning of Gregorian calendar). Parameters: year - [in] year >= 1582 (beginning of Gregorian calendar) month - [in] 1 to 12 mday - [in] 1 to 31 hour - [in] 0 to 23 minute - [in] 0 to 59 second - [in] 0 to 59 date_format - [in] date_format - [in] time_format - [in] date_separator - [in] Character placed between the year, month and day values. If 0, then ON_wString::HyphenMinus is used to date_time_separator - [in] Character placed between the date and time. If 0, then ON_wString::Space is used. time_separator - [in] Character placed between the hour, minute, and second values. If 0, then : (colon) is used.

◆ GetAt()

wchar_t ON_wString::GetAt ( int  ) const

◆ Header()

class ON_wStringHeader* ON_wString::Header ( ) const
protected

m_s - 12 bytes points at the string's ON_wStringHeader

implementation helpers

◆ HexadecimalFromBytes()

static const ON_wString ON_wString::HexadecimalFromBytes ( const ON__UINT8 bytes,
size_t  byte_count,
bool  bCapitalDigits,
bool  bReverse 
)
static

Description: Each byte value is converted to 2 hexadecimal digits. Parameters: bytes - [in] list of byte values byte_count - [in] Number of byte values in bytes[] array. bCapitalDigits - [in] false: Use 0-9, a - b true: Use 0-9, A - F bReverse - [in] false: The digist in the string will be in the order bytes[0], bytes[1], ..., bytes[byte_count-1]. true: The digist in the string will be in the order bytes[byte_count-1], ..., bytes[1], bytes[0].

◆ IncrementedHeader()

class ON_wStringHeader* ON_wString::IncrementedHeader ( ) const
protected

◆ IsDecimalDigit() [1/2]

static bool ON_wString::IsDecimalDigit ( wchar_t  c)
static

Parameters: c - [in] Returns: True if c is '0', '1', ..., or '9'.

◆ IsDecimalDigit() [2/2]

static bool ON_wString::IsDecimalDigit ( wchar_t  c,
bool  bOrdinaryDigitResult,
bool  bSuperscriptDigitResult,
bool  bSubscriptDigitResult 
)
static

Determine if c is a decimal digit.

Parameters
ccharacter to test
bOrdinaryDigitResultResult to return when c is an ordinary decimal digit (0123456789)
bSuperscriptDigitResultResult to return when c is a sperscript decimal digit (0123456789)
bSubscriptDigitResultResult to return when c is a subscript decimal digit (0123456789)
Returns
True if c is a decimal digit.

◆ IsEmpty()

bool ON_wString::IsEmpty ( ) const

◆ IsHexDigit()

static bool ON_wString::IsHexDigit ( wchar_t  c)
static

Parameters: c - [in] Returns: True if c is '0', '1', ..., '9', 'A', 'B', ..., 'F', 'a', 'b', ..., of 'f'.

◆ IsHorizontalSpace() [1/2]

static bool ON_wString::IsHorizontalSpace ( wchar_t  c)
static

Parameters: c - [in] character to test. Returns: True if c is some type of horizontal space, including horizontal tab and zero width spaces. If you need a more nuanced test, call the version of IsHorizontalSpace() that has bool parameters.

◆ IsHorizontalSpace() [2/2]

static bool ON_wString::IsHorizontalSpace ( wchar_t  c,
bool  bTabResult,
bool  bNoBreakSpaceResult,
bool  bZeroWidthSpaceResult 
)
static

Parameters: c - [in] character to test. bTabResult - [in] Result to return when c is a horizontal tab. bNoBreakSpaceResult - [in] Result to return when c is some type of no break space. bZeroWidthSpaceResult - [in] Result to return when c is a zero width space code point. Returns: True if c is some type of horizontal space.

◆ IsNotEmpty()

bool ON_wString::IsNotEmpty ( ) const

returns true if length > 0

◆ IsReferenceCounted()

bool ON_wString::IsReferenceCounted ( ) const

Returns: True if the string is reference counted.

◆ IsSlash()

static bool ON_wString::IsSlash ( wchar_t  c,
bool  bOrdinarySlashResult,
bool  bFractionSlashResult,
bool  bDivisionSlashResult,
bool  bMathematicalSlashResult 
)
static

Determine if c is some type opf Unicode slash (solidus).

Parameters
ccharacter to test
bOrdinarySlashResultResult to return when c is an ordinary slash (solidus) U+002F (/)
bFractionSlashResultResult to return when c is a fraction slash U+2044 (&#x2044;)
bDivisionSlashResultResult to return when c is a division slash U+2215 (&#x2215;)
bMathematicalSlashResultResult to return when c is a mathematical rising diagonal slash U+27CB (&#x27CB;)
Returns

◆ IsValid()

bool ON_wString::IsValid ( bool  bLengthTest) const

Parameters: bLengthTest - [in] true (common case) If this->Length() != ON_wString::Length(static_cast<const wchar_t*)(this)), then this string is not valid. false (less common case) There may be null elements in the first this->Length()-1 chars. Returns: True - this is valid. False There is a serious memory corruption bug in your code. This was not valid and converted to ON_wString::EmptyString to prevent future crashes.

◆ IsXMLSpecialCharacter()

static bool ON_wString::IsXMLSpecialCharacter ( wchar_t  c)
static

Returns true if c is one of the 5 XML special characters & (ampersand), < (less than), > (greater than), " (quotation mark), or ' (apostrophe).

◆ Left()

ON_wString ON_wString::Left ( int  ) const

◆ Length() [1/3]

int ON_wString::Length ( ) const

Attributes & Operations.

Returns: number of nonzero elements in string.

◆ Length() [2/3]

static int ON_wString::Length ( const wchar_t *  string)
static

Returns: number of nonzero elements in string before the first null terminator. If string is nullptr, 0 is returned.

◆ Length() [3/3]

static int ON_wString::Length ( const wchar_t *  string,
size_t  string_capacity 
)
static

Parameters: string_capacity - [in] number of elements that can be read in string[] array. Returns: number of nonzero elements in string before the first null terminator or string_capacity if no null terminator is in string[]. If string is nullptr, 0 is returned.

◆ MakeLower()

void ON_wString::MakeLower ( )

ON_DEPRECATED

◆ MakeLowerOrdinal()

void ON_wString::MakeLowerOrdinal ( )

◆ MakeReverse()

void ON_wString::MakeReverse ( )

◆ MakeUpper()

void ON_wString::MakeUpper ( )

upper/lower/reverse conversion

ON_DEPRECATED

◆ MakeUpperOrdinal()

void ON_wString::MakeUpperOrdinal ( )

◆ MapCharacterOrdinal()

static wchar_t ON_wString::MapCharacterOrdinal ( ON_StringMapOrdinalType  map_type,
wchar_t  c 
)
static

Description: Map a single wchar_t element to upper or lower case. Parameters: c - [in] If sizeof(wchar_t) >= 2 and c is not a value used int surrogate pairs, the map specified by map_type is applied. If c is a value used in surrogate pairs, the value is not changed. Remarks: 1) MapCharacterOrdinal is not appropriate for general string mapping because it does not correctly handle surrogate pairs. 2) If sizeof(wchar_t) == sizeof(char), ON_String::MapCharacterOrdinal() and ON_wString::MapCharacterOrdinal() are identical.

◆ MapString() [1/3]

ON_wString ON_wString::MapString ( const class ON_Locale locale,
ON_StringMapType  map_type 
) const

◆ MapString() [2/3]

static ON_wString ON_wString::MapString ( const class ON_Locale locale,
ON_StringMapType  map_type,
const wchar_t *  string,
int  element_count 
)
static

◆ MapString() [3/3]

static int ON_wString::MapString ( const class ON_Locale locale,
ON_StringMapType  map_type,
const wchar_t *  string,
int  element_count,
wchar_t *  mapped_string,
int  mapped_string_capacity 
)
static

Description: Maps element_count elements of string[] to mapped_string[]. Parameters: locale - [in] Locale to use when converting case. It is common to pass one of the preset locales ON_Locale::Ordinal, ON_Locale::InvariantCulture, or ON_Locale::m_CurrentCulture.

map_type - [in] selects the mapping

string - [in] input string to map.

element_count - [in] The number of wchar_t elements to map from input string[].

If element_count < 1, then string[] must be null terminated and ON_wString::Length(string)+1 elements are mapped. The +1 insures the output is null terminated.

mapped_string - [out] The result of the mapping is returned in mapped_string[].

mapped_string_capacity - [in] Number of wchar_t elements available in mapped_string[] or 0 to calculate the minimum number of elements needed for the mapping.

Returns: If mapped_string_capacity > 0, then the number elements set in mapped_string[] is returned.

If mapped_string_capacity == 0, then the number elements required to perform the mapping is returned.

When there is room, mapped_string[] is null terminated.

0: Failure.

◆ MapStringOrdinal() [1/2]

ON_wString ON_wString::MapStringOrdinal ( ON_StringMapOrdinalType  map_type) const

◆ MapStringOrdinal() [2/2]

static int ON_wString::MapStringOrdinal ( ON_StringMapOrdinalType  map_type,
const wchar_t *  string,
int  element_count,
wchar_t *  mapped_string,
int  mapped_string_capacity 
)
static

Description: Map a wchar_t string. Parameters: map_type - [in] string - [in] element_count - [in] number of string[] elements to map. If element_count < 0, then ON_wString::Length(string) elements are mapped. mapped_string - [out] mapped_string_capacity - [in] number of available elements in mapped_string[]. mapped_string_capacity must be >= mapped_element_count where mapped_element_count = (element_count >= 0) element_count ? ON_wString::Length(string). map_type - [in] Returns: Number of mapped_string[] elements that were mapped from string[].

When the return value is < mapped_string_capacity, a null terminator is appended after the last mapped element.

◆ Mid() [1/2]

ON_wString ON_wString::Mid ( int  ) const

◆ Mid() [2/2]

ON_wString ON_wString::Mid ( int  ,
int   
) const

simple sub-string extraction

◆ MultiByteEncode()

const ON_String ON_wString::MultiByteEncode ( int  windows_code_page) const

Description: Encode this UTF encoded wide charater string to a char string using the multibyte character set (MBCS) specified by windows_code_page. Parameters: windows_code_page - [in] WIndows code page. For example, big5 = 950. Returns: A char string with the specified MBCS encoding. Carefully control the scope and use of the returned string. Lacking context, opennurbs assumes ON_Strings use the UTF-8 encoded. See Also: ON_String::MultiByteDecode()

◆ operator const wchar_t *()

ON_wString::operator const wchar_t * ( ) const

◆ operator+() [1/8]

ON_wString ON_wString::operator+ ( char  ) const

◆ operator+() [2/8]

ON_wString ON_wString::operator+ ( const char *  sUTF8) const

concatinate with a UTF-8 string

◆ operator+() [3/8]

ON_wString ON_wString::operator+ ( const ON_String sUTF8) const

concatinate with a UTF-8 string

◆ operator+() [4/8]

ON_wString ON_wString::operator+ ( const ON_wString ) const

◆ operator+() [5/8]

ON_wString ON_wString::operator+ ( const unsigned char *  sUTF8) const

concatinate with a UTF-8 string

◆ operator+() [6/8]

ON_wString ON_wString::operator+ ( const wchar_t *  ) const

◆ operator+() [7/8]

ON_wString ON_wString::operator+ ( unsigned char  ) const

◆ operator+() [8/8]

ON_wString ON_wString::operator+ ( wchar_t  ) const

◆ operator+=() [1/8]

const ON_wString& ON_wString::operator+= ( char  )

◆ operator+=() [2/8]

const ON_wString& ON_wString::operator+= ( const char *  sUTF8)

append UTF-8 string

◆ operator+=() [3/8]

const ON_wString& ON_wString::operator+= ( const ON_String sUTF8)

append UTF-8 string

◆ operator+=() [4/8]

const ON_wString& ON_wString::operator+= ( const ON_wString )

◆ operator+=() [5/8]

const ON_wString& ON_wString::operator+= ( const unsigned char *  sUTF8)

append UTF-8 string

◆ operator+=() [6/8]

const ON_wString& ON_wString::operator+= ( const wchar_t *  )

◆ operator+=() [7/8]

const ON_wString& ON_wString::operator+= ( unsigned char  )

◆ operator+=() [8/8]

const ON_wString& ON_wString::operator+= ( wchar_t  )

◆ operator=() [1/8]

const ON_wString& ON_wString::operator= ( char  )

◆ operator=() [2/8]

const ON_wString& ON_wString::operator= ( const char *  src)

src = UTF-8 string

◆ operator=() [3/8]

const ON_wString& ON_wString::operator= ( const ON_String src)

src = UTF-8 string

◆ operator=() [4/8]

const ON_wString& ON_wString::operator= ( const ON_wString )

overloaded assignment

◆ operator=() [5/8]

const ON_wString& ON_wString::operator= ( const unsigned char *  src)

src = UTF-8 string

◆ operator=() [6/8]

const ON_wString& ON_wString::operator= ( const wchar_t *  )

◆ operator=() [7/8]

const ON_wString& ON_wString::operator= ( unsigned char  )

◆ operator=() [8/8]

const ON_wString& ON_wString::operator= ( wchar_t  )

◆ operator[]() [1/2]

wchar_t& ON_wString::operator[] ( int  )

◆ operator[]() [2/2]

wchar_t ON_wString::operator[] ( int  ) const

◆ ParseHorizontalSpace() [1/2]

static const wchar_t* ON_wString::ParseHorizontalSpace ( const wchar_t *  s,
int  len 
)
static

Description: Parse over horizontal space in the string. This version of ParseHorizontalSpace() treas tabs and zero width code points as horizontal space. If you need more nuanced control, call the override with bool parameters. Parameters: s - [in] string to parse. len - [in] maximum number of characters to parse. You many pass -1 if s is null terminated. Returns: If horizontal spaces were successfully parsed, first character after the horizontal spaces is returned. Otherwise s is returned.

◆ ParseHorizontalSpace() [2/2]

static const wchar_t* ON_wString::ParseHorizontalSpace ( const wchar_t *  s,
int  len,
bool  bParseTab,
bool  bParseNoBreakSpace,
bool  bParseZeroWidthSpace 
)
static

Description: Parse over horizontal space in the string. Parameters: s - [in] string to parse. len - [in] maximum number of characters to parse. You many pass -1 if s is null terminated. bParseTab - [in] True if a horizontal tab should be treated as horizontal space. bParseNoBreakSpace - [in] True if no break space code points should be treated as horizontal space. bParseZeroWidthSpace - [in] True if zero width code points should be treated as horizontal space. Returns: If horizontal spaces were successfully parsed, first character after the horizontal spaces is returned. Otherwise s is returned.

◆ ParseVulgarFraction()

static const wchar_t* ON_wString::ParseVulgarFraction ( const wchar_t *  s,
int  len,
int &  numerator,
int &  denomintor 
)
static

Description: Parse the string s as a vulgar fraction (1/2). Parameters: s - [in] string to parse. s[0] must be a sign or a digit. It can be the ordinary characters or superscripts. If the first digit is an ordinary digit, the the numerator and denominator must all be ordinary digits. If the first digit is a superscript digit, the the numerator must be all superscript digits and the denominator be all subscript digits. len - [in] maximum number of characters to parse. You many pass -1 if s is null terminated. numerator - [out] denominator - [out] Returns: If a vulgar fraction was succesfully parsed, the a pointer to the first character after the vulgar fraction is returned. Otherwise nullptr is returned.

◆ ParseXMLCharacterEncoding()

static const wchar_t* ON_wString::ParseXMLCharacterEncoding ( const wchar_t *  buffer,
int  buffer_length,
unsigned  value_on_failure,
unsigned *  unicode_code_point 
)
static

Description: Parse one of the following XML chacater encodings. &#nnnn; (nnnn = one of more decimal digits) is parsed to the unicode code point with decimal value nnnn &#xhhhh; (nnnn = one of more hexadecimal digits) is parsed to the unicode code point with hexadecimal value hhhh < is parsed to < (less-than). > is parsed to > (greater-than). & is parsed to & (ampersand). ' is parsed to ' (apostrophe or single quote). " is parsed to " (double-quote). Parameters: buffer - [in] buffer to parse. The first character of buffer[] must be the leading ampersand. The buffer must include the terminating semicolon. buffer_length - [in] If -1, then buffer[] must be null terminated. Otherwise buffer_length specifies the number of whcar_t elements that may be parsed. value_on_failure - [in] unicode_code_point is set to value_on_failure if parsing fails. unicode_code_point - [out] parsed unicode code point. If you do not want the code point, you may pass nullptr. Returns: If parsing is successful, the first element of buffer that was not parsed is returned. Otherwise nullptr is returned. Remarks: Note that the XML 1 (section 2.2 of the WC3 specification) does not permit surrogate pair encodings.

◆ ParseXMLUnicodeCodePointEncoding()

static const wchar_t* ON_wString::ParseXMLUnicodeCodePointEncoding ( const wchar_t *  buffer,
int  buffer_length,
unsigned  value_on_failure,
unsigned *  unicode_code_point 
)
static

Description: Parse an xml encoded unicde code point. &#nnnn; (nnnn = any number of decimal digits) &#xhhhh; (hhhh = any muber of hexadecimal digits) Parameters: buffer - [in] buffer to parse. The first character of buffer[] must be the leading ampersand. The second character of buffer[] must be the number sign. The buffer must include the terminating semicolon. buffer_length - [in] If -1, then buffer[] must be null terminated. Otherwise buffer_length specifies the number of whcar_t elements that may be parsed. value_on_failure - [in] unicode_code_point is set to value_on_failure if parsing fails. unicode_code_point - [out] parsed unicode code point. If you do not want the code point, you may pass nullptr. Returns: If parsing is successful, the first element of buffer that was not parsed is returned. Otherwise nullptr is returned.

◆ PlusOrMinusSignFromWideChar()

static int ON_wString::PlusOrMinusSignFromWideChar ( wchar_t  c,
bool  bAcceptOrdinarySign,
bool  bAcceptSuperscriptSign,
bool  bAcceptSubscriptSign 
)
static

Parameters: c - [in] character to test. bAcceptOrdinarySign - [in] ordinary + and - signes are acceptable. bAcceptSuperscriptSign - [in] superscript + and - signes are acceptable. bAcceptSubscriptSign - [in] subscript + and - signes are acceptable. Returns: +1 if c is an acceptable plus sign. -1 if c is an acceptable minus sign. Otherwise, 0 is returned.

◆ PreciseFromNumber()

static const ON_wString ON_wString::PreciseFromNumber ( double  d)
static
Parameters
d"%.17g"

◆ Remove() [1/3]

int ON_wString::Remove ( char  utf8_single_byte_c)

Description: Remove all occurrences of the input character. Parameters: c - [in] utf8_single_byte_ct must have a value between 0 and 0x7F. When w is a 2 byte UTF-16 wchar_t value (like Microsoft's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0xFFFF. When w is a 4 byte UTF-32 wchar_t value (like Apple's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0x10FFFF. Returns: Number of characters removed.

◆ Remove() [2/3]

int ON_wString::Remove ( unsigned char  utf8_single_byte_c)

◆ Remove() [3/3]

int ON_wString::Remove ( wchar_t  w)

◆ RemovePrefix()

const ON_wString ON_wString::RemovePrefix ( const wchar_t *  prefix,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

Parameters: prefix - [in] locale - [in] When no local is available, pass ON_Locale::Ordinal. bIgnoreCase - [in] true to ignore case. Returns: If the string begins with prefix, the returned string has prefix removed. Otherwise the returned string is identical to the string.

◆ RemoveSuffix()

const ON_wString ON_wString::RemoveSuffix ( const wchar_t *  suffix,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

Parameters: suffix - [in] locale - [in] When no local is available, pass ON_Locale::Ordinal. bIgnoreCase - [in] true to ignore case. Returns: If the string ends with suffix, the returned string has suffix removed. Otherwise the returned string is identical to the string.

◆ RemoveWhiteSpace()

int ON_wString::RemoveWhiteSpace ( const wchar_t *  whitespace = 0)

Description: Removes all white-space characters with the token. Parameters: whitespace - [in] if not null, this is a 0 terminated string that lists the characters considered to be white space. If null, then (1,2,...,32,127) is used. Returns: Number of whitespace characters removed. See Also: ON_wString::ReplaceWhiteSpace

◆ Replace() [1/2]

int ON_wString::Replace ( const wchar_t *  token1,
const wchar_t *  token2 
)

Description: Replace all substrings that match token1 with token2 Parameters: token1 - [in] token2 - [in] Returns: Number of times toke1 was replaced with token2

◆ Replace() [2/2]

int ON_wString::Replace ( wchar_t  token1,
wchar_t  token2 
)

◆ ReplaceWhiteSpace()

int ON_wString::ReplaceWhiteSpace ( wchar_t  token,
const wchar_t *  whitespace = 0 
)

Description: Replace all white-space characters with the token. If token is zero, the string will end up with internal 0's Parameters: token - [in] whitespace - [in] if not null, this is a 0 terminated string that lists the characters considered to be white space. If null, then (1,2,...,32,127) is used. Returns: Number of whitespace characters replaced. See Also: ON_wString::RemoveWhiteSpace

◆ ReserveArray()

wchar_t* ON_wString::ReserveArray ( size_t  capacity)

Description: Expert user funtion to reserve and gain access to string memory. Parameters: capacity - [in] If capacity > ON_String::MaximumStringLength, then nullptr is returned. If capacity <= 0, then nullptr is returned.

◆ Reverse() [1/2]

ON_wString ON_wString::Reverse ( ) const

◆ Reverse() [2/2]

static wchar_t* ON_wString::Reverse ( wchar_t *  string,
int  element_count 
)
static

◆ ReverseFind() [1/5]

int ON_wString::ReverseFind ( char  utf8_single_byte_c) const

Description: Find the last occurrence of a character or substring. Parameters: utf8_single_byte_c - [in] utf8_single_byte_c must have a value between 0 and 0x7F. w - [in] When w is a 2 byte UTF-16 wchar_t value (like Microsoft's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0xFFFF. When w is a 4 byte UTF-32 wchar_t value (like Apple's wchar_t), it must be in the range 0 to 0xD7FF or 0xE000 to 0x10FFFF. sUTF8 - [in] wideString - [in] Returns: -1: Invalid input or character or substring was not found. >=0: Index of the final occurrence of the character or substring.

◆ ReverseFind() [2/5]

int ON_wString::ReverseFind ( const char *  sUTF8) const

◆ ReverseFind() [3/5]

int ON_wString::ReverseFind ( const wchar_t *  wideString) const

◆ ReverseFind() [4/5]

int ON_wString::ReverseFind ( unsigned char  utf8_single_byte_c) const

◆ ReverseFind() [5/5]

int ON_wString::ReverseFind ( wchar_t  w) const

◆ RichTextExample() [1/3]

static const ON_wString ON_wString::RichTextExample ( const class ON_Font font)
static

Get a rich text example.

Parameters
fontEvery rich text face supported by font will be in the sample.
Returns
A rich text example using the specified font in all supported rich text faces (regular/bold/italic/bold-italic) in both plain and underline.

◆ RichTextExample() [2/3]

static const ON_wString ON_wString::RichTextExample ( const class ON_FontFaceQuartet quartet)
static

Get a rich text example.

Parameters
quartetEvery rich text face supported by the font quartet will be in the sample.
Returns
A rich text example using the specified font in all supported rich text faces (regular/bold/italic/bold-italic) in both plain and underline.

◆ RichTextExample() [3/3]

static const ON_wString ON_wString::RichTextExample ( ON_wString  rich_text_font_name,
bool  bBold,
bool  bItalic,
bool  bBoldItalic,
bool  bUnderline 
)
static

Get a rich text example.

Parameters
rich_text_face_nameThe rich text font name. This name is not well defined and the best choice can be platform specific. For Windows use the LOGFONT always works. For Mac OS the font family name generally works. If you have an ON_Font, then ON_Font.RichTextFontName() or ON_Font.FontQuartet().QuartetName() are good choices.
bBoldPass true to include a rich text bold face line.
bItalicPass true to include a rich text italic face line.
bBoldItalicPass true to include a rich text bold-italic face line.
bUnderlinePass true to include both plain and underline in the sample.
Returns
A rich text example using the specified face and the specified

◆ Right()

ON_wString ON_wString::Right ( int  ) const

◆ Scan()

int ON_VARGS_FUNC_CDECL ON_wString::Scan ( const wchar_t *  format,
  ... 
) const

Parameters: format - [in] null terminated string to scan ... - [out] pointers to elements to assign. Returns: >= 0: number of fields successfully converted and assigned. <0: failure

◆ ScanBuffer()

static int ON_VARGS_FUNC_CDECL ON_wString::ScanBuffer ( const wchar_t *  buffer,
const wchar_t *  format,
  ... 
)
static

◆ ScanBufferVargs()

static int ON_wString::ScanBufferVargs ( const wchar_t *  buffer,
const wchar_t *  format,
va_list  args 
)
static

◆ SetAt() [1/3]

void ON_wString::SetAt ( int  ,
char   
)

◆ SetAt() [2/3]

void ON_wString::SetAt ( int  ,
unsigned char   
)

◆ SetAt() [3/3]

void ON_wString::SetAt ( int  ,
wchar_t   
)

◆ SetLength()

wchar_t* ON_wString::SetLength ( size_t  )

set length (<=capacity)

◆ ShrinkArray()

void ON_wString::ShrinkArray ( )

shrink internal storage to minimum size

◆ SizeOf()

unsigned int ON_wString::SizeOf ( ) const

Returns: Total number of bytes of memory used by this class. (For use in ON_Object::SizeOf() overrides.

◆ SplitPath() [1/2]

static void ON_wString::SplitPath ( const char *  path,
ON_wString drive,
ON_wString dir,
ON_wString fname,
ON_wString ext 
)
static

◆ SplitPath() [2/2]

static void ON_wString::SplitPath ( const wchar_t *  path,
ON_wString drive,
ON_wString dir,
ON_wString fname,
ON_wString ext 
)
static

◆ SubString() [1/2]

const ON_wString ON_wString::SubString ( int  start_index) const

◆ SubString() [2/2]

const ON_wString ON_wString::SubString ( int  start_index,
int  count 
) const

◆ SwapByteOrder()

static wchar_t ON_wString::SwapByteOrder ( wchar_t  w)
static

Parameters: w - [in] wchar_t value to swap bytes Returns: w with swapped byte order

◆ ToMemorySize()

static const ON_wString ON_wString::ToMemorySize ( size_t  sz)
static

Parameters: sz - [in] number of bytes. Returns: If sz < 0, "0 bytes" is returned. If 0 <= sz <= 9999, "x bytes" is returned where x is an exact decimal value. If s > 9999, then a description with 3 significant digits and a suffix indicating the order of magnitude is returned. The order of magnitude is described by appending KB (1024 bytes), MB (1024 KB), GB (1024 MB), TB (1024 GB), or PB (1024 TB).

◆ ToNumber() [1/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
char  value_on_failure,
char *  value 
)
static

Description: Parses buffer to extract a number. Sperscript and supscript numbers are supported. Returns: not zero: pointer to the first character that was not scanned nullptr: failure

◆ ToNumber() [2/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
double  value_on_failure,
double *  value 
)
static

◆ ToNumber() [3/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
int  value_on_failure,
int *  value 
)
static

◆ ToNumber() [4/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
ON__INT64  value_on_failure,
ON__INT64 value 
)
static

◆ ToNumber() [5/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
ON__UINT64  value_on_failure,
ON__UINT64 value 
)
static

◆ ToNumber() [6/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
short  value_on_failure,
short *  value 
)
static

◆ ToNumber() [7/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
unsigned char  value_on_failure,
unsigned char *  value 
)
static

◆ ToNumber() [8/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
unsigned int  value_on_failure,
unsigned int *  value 
)
static

◆ ToNumber() [9/9]

static const wchar_t* ON_wString::ToNumber ( const wchar_t *  buffer,
unsigned short  value_on_failure,
unsigned short *  value 
)
static

◆ TrimLeft()

void ON_wString::TrimLeft ( const wchar_t *  s = nullptr)

Description: Removes leading elements from the string. Parameters: s - [in] All leading wchar_t elements with a value that it found in s[] are removed. If s is nullptr, All leading wchar_t element with a value between 1 and space are removed.

◆ TrimLeftAndRight()

void ON_wString::TrimLeftAndRight ( const wchar_t *  s = nullptr)

◆ TrimRight()

void ON_wString::TrimRight ( const wchar_t *  s = nullptr)

Description: Removes trailing elements from the string. Parameters: s - [in] All trailing wchar_t elements with a value that it found in s[] are removed. If s is nullptr, All trailing wchar_t elements with a value between 1 and space are removed.

◆ UnsignedLength() [1/2]

unsigned int ON_wString::UnsignedLength ( ) const

Returns: number of nonzero elements in the string.

◆ UnsignedLength() [2/2]

static unsigned int ON_wString::UnsignedLength ( const wchar_t *  string)
static

Returns: number of nonzero elements in string before the first null terminator. If string is nullptr, 0 is returned.

◆ UrlDecode()

bool ON_wString::UrlDecode ( )

Description: Replaces all xx where xx a two digit hexadecimal number, with a single character. Returns false if the orginal string contained

◆ UrlEncode()

void ON_wString::UrlEncode ( )

Description: Replaces all characters in the string whose values are not '0-9', 'A-Z', or 'a-z' with a percent sign followed by a 2 digit hex value.

◆ VulgarFractionSlash()

static const ON_wString ON_wString::VulgarFractionSlash ( )
static

Returns a string with the code point U+2044.

◆ WildCardMatch()

bool ON_wString::WildCardMatch ( const wchar_t *  ) const

Description: Simple case sensitive wildcard matching. A question mark (?) in the pattern matches a single character. An asterisk (*) in the pattern mathes zero or more occurances of any character.

Parameters: pattern - [in] pattern string where ? and * are wild cards.

Returns: true if the string mathes the wild card pattern.

◆ WildCardMatchNoCase()

bool ON_wString::WildCardMatchNoCase ( const wchar_t *  ) const

Description: Simple case insensitive wildcard matching. A question mark (?) in the pattern matches a single character. An asterisk (*) in the pattern mathes zero or more occurances of any character.

Parameters: pattern - [in] pattern string where ? and * are wild cards.

Returns: true if the string mathes the wild card pattern.

Member Data Documentation

◆ Ampersand

const wchar_t ON_wString::Ampersand = (wchar_t)ON_UnicodeCodePoint::ON_Ampersand
static

AMPERSAND U+0026 (&)

◆ Apostrophe

const wchar_t ON_wString::Apostrophe = (wchar_t)ON_UnicodeCodePoint::ON_Apostrophe
static

APOSTROPHE U+0027 (')

◆ Backslash

const wchar_t ON_wString::Backslash = (wchar_t)ON_UnicodeCodePoint::ON_Backslash
static

REVERSE SOLIDUS U+005C (&#x5c;)

◆ Backspace

const wchar_t ON_wString::Backspace = (wchar_t)ON_UnicodeCodePoint::ON_Backspace
static

BACKSPACE control U+0008

◆ ByteOrderMark

const ON_wString ON_wString::ByteOrderMark
static

UTF-16/UTF-32 encoding of the Unicode byte order mark (BOM) U+FEFF.

◆ CarriageReturn

const wchar_t ON_wString::CarriageReturn = (wchar_t)ON_UnicodeCodePoint::ON_CarriageReturn
static

CARRIAGE RETURN control U+000D

◆ Colon

const wchar_t ON_wString::Colon = (wchar_t)ON_UnicodeCodePoint::ON_Colon
static

COLON U+003A (:)

◆ Comma

const wchar_t ON_wString::Comma = (wchar_t)ON_UnicodeCodePoint::ON_Comma
static

COMMA U+002C (,)

◆ DecimalAsComma

const wchar_t ON_wString::DecimalAsComma = (wchar_t)ON_UnicodeCodePoint::ON_Comma
static

Comma decimal point (,)

◆ DecimalAsPeriod

const wchar_t ON_wString::DecimalAsPeriod = (wchar_t)ON_UnicodeCodePoint::ON_Period
static

Period decimal point (.)

◆ EmptyString

const ON_wString ON_wString::EmptyString
static

ON_String::EmptyString has length 0. const char* s = ON_String::EmptyString sets s to L"".

◆ Escape

const wchar_t ON_wString::Escape = (wchar_t)ON_UnicodeCodePoint::ON_Escape
static

ESCAPE control U+001B

◆ FormFeed

const wchar_t ON_wString::FormFeed = (wchar_t)ON_UnicodeCodePoint::ON_FormFeed
static

FORM FEED control U+000C

◆ GreaterThanSign

const wchar_t ON_wString::GreaterThanSign = (wchar_t)ON_UnicodeCodePoint::ON_GreaterThanSign
static

GREATER-THAN SIGN U+003E (&#x3e;)

◆ HyphenMinus

const wchar_t ON_wString::HyphenMinus = (wchar_t)ON_UnicodeCodePoint::ON_HyphenMinus
static

HYPHEN-MINUS U+002D (-)

◆ LessThanSign

const wchar_t ON_wString::LessThanSign = (wchar_t)ON_UnicodeCodePoint::ON_LessThanSign
static

LESS-THAN SIGN U+003C (&#x3c;)

◆ LineFeed

const wchar_t ON_wString::LineFeed = (wchar_t)ON_UnicodeCodePoint::ON_LineFeed
static

LINE FEED control U+000A

◆ m_s

wchar_t* ON_wString::m_s
protected

Implementation.

pointer to ref counted string array

◆ NumberSign

const wchar_t ON_wString::NumberSign = (wchar_t)ON_UnicodeCodePoint::ON_NumberSign
static

NUMBER SIGN U+0023 (#)

◆ PercentSign

const wchar_t ON_wString::PercentSign = (wchar_t)ON_UnicodeCodePoint::ON_PercentSign
static

PERCENT SIGN U+0025 (%)

◆ Period

const wchar_t ON_wString::Period = (wchar_t)ON_UnicodeCodePoint::ON_Period
static

PERIOD U+002E (decimal 46) (.)

◆ Pipe

const wchar_t ON_wString::Pipe = (wchar_t)ON_UnicodeCodePoint::ON_Pipe
static

VERTICAL LINE U+007C (&#x7c;)

◆ QuotationMark

const wchar_t ON_wString::QuotationMark = (wchar_t)ON_UnicodeCodePoint::ON_QuotationMark
static

QUOTATION MARK U+0022 (")

◆ Semicolon

const wchar_t ON_wString::Semicolon = (wchar_t)ON_UnicodeCodePoint::ON_Semicolon
static

SEMICOLON U+003B (;)

◆ Slash

const wchar_t ON_wString::Slash = (wchar_t)ON_UnicodeCodePoint::ON_Slash
static

SOLIDUS U+002F (&#x2f;)

◆ Space

const wchar_t ON_wString::Space = (wchar_t)ON_UnicodeCodePoint::ON_Space
static

SPACE U+0020

◆ Tab

const wchar_t ON_wString::Tab = (wchar_t)ON_UnicodeCodePoint::ON_Tab
static

CHARACTER TABULATION control U+0009

◆ Tilde

const wchar_t ON_wString::Tilde = (wchar_t)ON_UnicodeCodePoint::ON_Tilde
static

TILDE U+007E (&#x7e;)

◆ Underscore

const wchar_t ON_wString::Underscore = (wchar_t)ON_UnicodeCodePoint::ON_Underscore
static

///< Unicode LOW LINE U+005F (_)

◆ VerticalTab

const wchar_t ON_wString::VerticalTab = (wchar_t)ON_UnicodeCodePoint::ON_VerticalTab
static

LINE TABULATION control U+000B