openNURBS SDK Help  6.0
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
ON_String Class Reference

#include <opennurbs_string.h>

Public Member Functions

 ON_String () ON_NOEXCEPT
 Constructors. More...
 
 ON_String (const ON_String &)
 
 ON_String (const char *)
 
 ON_String (const char *, int)
 from substring More...
 
 ON_String (char, int=1)
 
 ON_String (const unsigned char *)
 
 ON_String (const unsigned char *, int)
 from substring More...
 
 ON_String (unsigned char, int=1)
 
 ON_String (const wchar_t *src)
 construct a UTF-8 string string from a UTF-16 string. More...
 
 ON_String (const wchar_t *src, int length)
 from a UTF-16 substring More...
 
 ON_String (const ON_wString &src)
 src = UTF-16 string More...
 
 ~ON_String ()
 
void Append (const char *, int)
 string concatenation More...
 
void Append (const unsigned char *, int)
 append specified number of characters More...
 
char * Array ()
 
const char * Array () const
 
int Compare (const ON_String &other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
int Compare (const char *other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
int CompareAttributeName (const char *other_name) const
 
int CompareOrdinal (const ON_String &other_string, bool bIgnoreCase) const
 
int CompareOrdinal (const char *other_string, bool bIgnoreCase) const
 
int ComparePath (const char *other_path) const
 
const ON_SHA1_Hash ContentHash (ON_StringMapOrdinalType mapping) const
 
void Create ()
 
ON__UINT32 DataCRC (ON__UINT32 current_remainder) const
 
void Destroy ()
 releases any memory and initializes to default empty string More...
 
void EmergencyDestroy ()
 
void Empty ()
 sets length to zero - if possible, memory is retained More...
 
void EnableReferenceCounting (bool bEnable)
 
bool Equal (const ON_String &other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
bool Equal (const char *other_string, const class ON_Locale &locale, bool bIgnoreCase) const
 
bool EqualAttributeName (const char *other_name) const
 
bool EqualOrdinal (const ON_String &other_string, bool bOrdinalIgnoreCase) const
 
bool EqualOrdinal (const char *other_string, bool bOrdinalIgnoreCase) const
 
bool EqualPath (const char *other_path) const
 
int Find (char utf8_single_byte_c) const
 
int Find (unsigned char utf8_single_byte_c) const
 
int Find (const char *) const
 look for a specific sub-string More...
 
int Find (const unsigned char *) const
 
int Find (const char *, int start_index) const
 
int Find (const unsigned char *, int start_index) const
 
bool ON_VARGS_FUNC_CDECL Format (const char *format,...)
 
bool ON_VARGS_FUNC_CDECL Format (const unsigned char *format,...)
 
bool FormatVargs (const char *format, va_list args)
 
bool FormatVargs (const unsigned char *format, va_list args)
 
char GetAt (int) const
 
bool IsEmpty () const
 returns true if length == 0 More...
 
bool IsNotEmpty () const
 returns true if length > 0 More...
 
bool IsReferenceCounted () const
 
ON_String 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_String MapString (const class ON_Locale &locale, ON_StringMapType map_type) const
 
ON_String MapStringOrdinal (ON_StringMapOrdinalType map_type) const
 
ON_String Mid (int, int) const
 simple sub-string extraction More...
 
ON_String Mid (int) const
 
 ON_DEPRECATED_MSG ("Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate") int Compare(const char *) const
 
 ON_DEPRECATED_MSG ("Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate") int Compare(const unsigned char *) const
 
 ON_DEPRECATED_MSG ("Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate") int CompareNoCase(const char *) const
 
 ON_DEPRECATED_MSG ("Use CompareOrdinal(), ComparePath(), CompareAttributeName(), or a test that is linguistically apprropriate") int CompareNoCase(const unsigned char *) const
 
 operator const char * () const
 
ON_String operator+ (const ON_String &) const
 operator+() More...
 
ON_String operator+ (char) const
 
ON_String operator+ (unsigned char) const
 
ON_String operator+ (const char *) const
 
ON_String operator+ (const unsigned char *) const
 
const ON_Stringoperator+= (const ON_String &)
 
const ON_Stringoperator+= (char)
 
const ON_Stringoperator+= (unsigned char)
 
const ON_Stringoperator+= (const char *)
 
const ON_Stringoperator+= (const unsigned char *)
 
ON_Stringoperator= (const ON_String &)
 overloaded assignment More...
 
ON_Stringoperator= (char)
 
ON_Stringoperator= (const char *)
 
ON_Stringoperator= (unsigned char)
 
ON_Stringoperator= (const unsigned char *)
 
ON_Stringoperator= (const wchar_t *src)
 src = Wide char string, result is a UTF-8 string More...
 
ON_Stringoperator= (const ON_wString &src)
 src = Wide char string, result is a UTF-8 string More...
 
char & operator[] (int)
 
char operator[] (int) const
 
int Remove (const char utf8_single_byte_c)
 remove occurrences of chRemove More...
 
int Replace (const char *token1, const char *token2)
 
int Replace (const unsigned char *token1, const unsigned char *token2)
 
int Replace (char utf8_single_byte_c1, char utf8_single_byte_c2)
 
int Replace (unsigned char utf8_single_byte_c1, unsigned char utf8_single_byte_c2)
 
char * ReserveArray (size_t)
 Low level access to string contents as character array. More...
 
ON_String Reverse () const
 
int ReverseFind (char utf8_single_byte_c) const
 
int ReverseFind (unsigned char utf8_single_byte_c) const
 
int ReverseFind (const char *) const
 
int ReverseFind (const unsigned char *) const
 
ON_String Right (int) const
 
int ON_VARGS_FUNC_CDECL Scan (const char *format,...)
 
int ON_VARGS_FUNC_CDECL Scan (const unsigned char *format,...)
 
void SetAt (int, char)
 
void SetAt (int, unsigned char)
 
char * SetLength (size_t)
 set length (<=capacity) More...
 
void ShrinkArray ()
 the requested capacity. More...
 
unsigned int SizeOf () const
 
void TrimLeft (const char *=nullptr)
 
void TrimLeftAndRight (const char *=nullptr)
 
void TrimRight (const char *=nullptr)
 
unsigned int UnsignedLength () const
 
bool WildCardMatch (const char *) const
 
bool WildCardMatch (const unsigned char *) const
 
bool WildCardMatchNoCase (const char *) const
 
bool WildCardMatchNoCase (const unsigned char *) const
 

Static Public Member Functions

static const ON_String ApproximateFromNumber (double d)
 
static int Compare (const char *string1, const char *string2, const class ON_Locale &locale, bool bIgnoreCase)
 
static int Compare (const char *string1, int element_count1, const char *string2, int element_count2, const class ON_Locale &locale, bool bIgnoreCase)
 
static int CompareAttributeName (const char *name1, const char *name2)
 
static int CompareOrdinal (const char *string1, const char *string2, bool bIgnoreCase)
 
static int CompareOrdinal (const char *string1, int element_count1, const char *string2, int element_count2, bool bOrdinalIgnoreCase)
 
static int ComparePath (const char *path1, const char *path2)
 
static int ComparePath (const char *path1, int element_count1, const char *path2, int element_count2)
 
static bool Equal (const char *string1, const char *string2, const class ON_Locale &locale, bool bIgnoreCase)
 
static bool Equal (const char *string1, int element_count1, const char *string2, int element_count2, const class ON_Locale &locale, bool bOrdinalIgnoreCase)
 
static bool EqualAttributeName (const char *name1, const char *name2)
 
static bool EqualOrdinal (const char *string1, const char *string2, bool bOrdinalIgnoreCase)
 
static bool EqualOrdinal (const char *string1, int element_count1, const char *string2, int element_count2, bool bOrdinalIgnoreCase)
 
static bool EqualPath (const char *path1, const char *path2)
 
static bool EqualPath (const char *path1, int element_count1, const char *path2, int element_count2)
 
static int ON_VARGS_FUNC_CDECL FormatIntoBuffer (char *buffer, size_t buffer_capacity, const char *format,...)
 
static int ON_VARGS_FUNC_CDECL FormatIntoBuffer (ON_StringBuffer &buffer, const char *format,...)
 
static const ON_wString ON_VARGS_FUNC_CDECL FormatToString (const char *format,...)
 
static int FormatVargsIntoBuffer (char *buffer, size_t buffer_capacity, const char *format, va_list args)
 
static int FormatVargsIntoBuffer (ON_StringBuffer &buffer, const char *format, va_list args)
 
static int FormatVargsOutputCount (const char *format, va_list args)
 
static const ON_String FromNumber (char n)
 
static const ON_String FromNumber (unsigned char n)
 
static const ON_String FromNumber (short n)
 
static const ON_String FromNumber (unsigned short n)
 
static const ON_String FromNumber (int n)
 
static const ON_String FromNumber (unsigned int n)
 
static const ON_String FromNumber (ON__INT64 n)
 
static const ON_String FromNumber (ON__UINT64 n)
 
static const ON_String FromNumber (double d)
 
static const ON_String HexadecimalFromBytes (const ON__UINT8 *bytes, size_t byte_count, bool bCapitalDigits, bool bReverse)
 
static int Length (const char *string)
 
static char MapCharacterOrdinal (ON_StringMapOrdinalType map_type, char c)
 
static ON_String MapString (const class ON_Locale &locale, ON_StringMapType map_type, const char *string, int element_count)
 
static int MapString (const class ON_Locale &locale, ON_StringMapType map_type, const char *string, int element_count, char *mapped_string, int mapped_string_capacity)
 
static int MapStringOrdinal (ON_StringMapOrdinalType map_type, const char *string, int element_count, char *mapped_string, int mapped_string_capacity)
 
static const ON_String PreciseFromNumber (double d)
 
static char * Reverse (char *string, int element_count)
 
static int ON_VARGS_FUNC_CDECL ScanBuffer (const char *buffer, const char *format,...)
 
static int ON_VARGS_FUNC_CDECL ScanBuffer (const unsigned char *buffer, const unsigned char *format,...)
 
static int ScanBufferVargs (const char *buffer, const char *format, va_list args)
 
static int ScanBufferVargs (const unsigned char *buffer, const unsigned char *format, va_list args)
 
static void SplitPath (const char *path, ON_String *drive, ON_String *dir, ON_String *fname, ON_String *ext)
 
static const char * ToNumber (const char *buffer, char value_on_failure, char *value)
 
static const char * ToNumber (const char *buffer, unsigned char value_on_failure, unsigned char *value)
 
static const char * ToNumber (const char *buffer, short value_on_failure, short *value)
 
static const char * ToNumber (const char *buffer, unsigned short value_on_failure, unsigned short *value)
 
static const char * ToNumber (const char *buffer, int value_on_failure, int *value)
 
static const char * ToNumber (const char *buffer, unsigned int value_on_failure, unsigned int *value)
 
static const char * ToNumber (const char *buffer, ON__INT64 value_on_failure, ON__INT64 *value)
 
static const char * ToNumber (const char *buffer, ON__UINT64 value_on_failure, ON__UINT64 *value)
 
static const char * ToNumber (const char *buffer, double value_on_failure, double *value)
 
static unsigned int UnsignedLength (const char *string)
 

Static Public Attributes

static const char Backslash
 Unicode REVERSE SOLIDUS U+005C. More...
 
static const char Backspace
 Unicode BACKSPACE control U+0008. More...
 
static const char CarriageReturn
 Unicode CHARACTER TABULATION control U+000D. More...
 
static const ON_String EmptyString
 
static const char Escape
 Unicode CARRIAGE RETURN control U+001B. More...
 
static const char FormFeed
 Unicode FORM FEED control U+000C. More...
 
static const char LineFeed
 Unicode LINE FEED control U+000A. More...
 
static const char Pipe
 Unicode VERTICAL LINE U+007C. More...
 
static const char Slash
 Unicode SOLIDUS U+002F. More...
 
static const char Space
 Unicode SPACE U+0020. More...
 
static const char Tab
 Unicode CHARACTER TABULATION control U+0009. More...
 
static const char VerticalTab
 Unicode LINE TABULATION control U+000B. More...
 

Protected Member Functions

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

Protected Attributes

char * m_s
 Implementation. More...
 

Constructor & Destructor Documentation

◆ ON_String() [1/11]

ON_String::ON_String ( )

Constructors.

◆ ON_String() [2/11]

ON_String::ON_String ( const ON_String )

◆ ON_String() [3/11]

ON_String::ON_String ( const char *  )

◆ ON_String() [4/11]

ON_String::ON_String ( const char *  ,
int   
)

from substring

◆ ON_String() [5/11]

ON_String::ON_String ( char  ,
int  = 1 
)

◆ ON_String() [6/11]

ON_String::ON_String ( const unsigned char *  )

◆ ON_String() [7/11]

ON_String::ON_String ( const unsigned char *  ,
int   
)

from substring

◆ ON_String() [8/11]

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

◆ ON_String() [9/11]

ON_String::ON_String ( const wchar_t *  src)

construct a UTF-8 string string from a UTF-16 string.

src = UTF-16 string

◆ ON_String() [10/11]

ON_String::ON_String ( const wchar_t *  src,
int  length 
)

from a UTF-16 substring

◆ ON_String() [11/11]

ON_String::ON_String ( const ON_wString src)

src = UTF-16 string

◆ ~ON_String()

ON_String::~ON_String ( )

Member Function Documentation

◆ Append() [1/2]

void ON_String::Append ( const char *  ,
int   
)

string concatenation

append specified number of characters

◆ Append() [2/2]

void ON_String::Append ( const unsigned char *  ,
int   
)

append specified number of characters

◆ AppendToArray() [1/3]

void ON_String::AppendToArray ( const ON_String )
protected

◆ AppendToArray() [2/3]

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

◆ AppendToArray() [3/3]

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

◆ ApproximateFromNumber()

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

◆ Array() [1/2]

char* ON_String::Array ( )

◆ Array() [2/2]

const char* ON_String::Array ( ) const

◆ Compare() [1/4]

int ON_String::Compare ( const ON_String 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/4]

int ON_String::Compare ( const char *  other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

◆ Compare() [3/4]

static int ON_String::Compare ( const char *  string1,
const char *  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() [4/4]

static int ON_String::Compare ( const char *  string1,
int  element_count1,
const char *  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]

int ON_String::CompareAttributeName ( const char *  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

◆ CompareAttributeName() [2/2]

static int ON_String::CompareAttributeName ( const char *  name1,
const char *  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

◆ CompareOrdinal() [1/4]

int ON_String::CompareOrdinal ( const ON_String other_string,
bool  bIgnoreCase 
) const

Description: Compare this string and other_string unsigned byte by unsigned byte. Parameters: other_string - [in] bIgnoreCase - [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_String::CompareOrdinal ( const char *  other_string,
bool  bIgnoreCase 
) const

◆ CompareOrdinal() [3/4]

static int ON_String::CompareOrdinal ( const char *  string1,
const char *  string2,
bool  bIgnoreCase 
)
static

Description: Compare string1 and string2 unsigned byte by unsigned byte. Parameters: string1 - [in] string2 - [in] bIgnoreCase - [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 a UTF-8 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_String::CompareOrdinal ( const char *  string1,
int  element_count1,
const char *  string2,
int  element_count2,
bool  bOrdinalIgnoreCase 
)
static

Description: Compare string1 and string2 unsigned byte by unsigned byte. Parameters: string1 - [in] element_count1 - [in] The number of elements in string1[] to compare. If element_count1 < 1, string1 must be null terminated and every element before the null terminator will be compared. string2 - [in] element_count2 - [in] The number of elements in string2[] to compare. If element_count2 < 1, string2 must be null terminated and every element before the null terminator will be compared. 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 a UTF-8 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_String::ComparePath ( const char *  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] 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_String::ComparePath ( const char *  path1,
const char *  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_String::ComparePath ( const char *  path1,
int  element_count1,
const char *  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_String::ContentHash ( ON_StringMapOrdinalType  mapping) const

◆ CopyArray()

void ON_String::CopyArray ( )
protected

◆ CopyToArray() [1/4]

void ON_String::CopyToArray ( const ON_String )
protected

◆ CopyToArray() [2/4]

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

◆ CopyToArray() [3/4]

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

◆ CopyToArray() [4/4]

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

◆ Create()

void ON_String::Create ( )

◆ CreateArray()

char* ON_String::CreateArray ( int  )
protected

◆ DataCRC()

ON__UINT32 ON_String::DataCRC ( ON__UINT32  current_remainder) const

◆ Destroy()

void ON_String::Destroy ( )

releases any memory and initializes to default empty string

◆ EmergencyDestroy()

void ON_String::EmergencyDestroy ( )

◆ Empty()

void ON_String::Empty ( )

sets length to zero - if possible, memory is retained

◆ EnableReferenceCounting()

void ON_String::EnableReferenceCounting ( bool  bEnable)

Description: Enables reference counting. I limited cases, this is useful for large strings or strings that are frequently passed around. Reference counted strings must be carefully managed in when multi-threading is used. Parameters: If EnableReferenceCounting() is not called, then the string will not be referanceThe default is to not use reference counted strings.

◆ Equal() [1/4]

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

◆ Equal() [2/4]

bool ON_String::Equal ( const char *  other_string,
const class ON_Locale locale,
bool  bIgnoreCase 
) const

◆ Equal() [3/4]

static bool ON_String::Equal ( const char *  string1,
const char *  string2,
const class ON_Locale locale,
bool  bIgnoreCase 
)
static

◆ Equal() [4/4]

static bool ON_String::Equal ( const char *  string1,
int  element_count1,
const char *  string2,
int  element_count2,
const class ON_Locale locale,
bool  bOrdinalIgnoreCase 
)
static

◆ EqualAttributeName() [1/2]

bool ON_String::EqualAttributeName ( const char *  other_name) const

◆ EqualAttributeName() [2/2]

static bool ON_String::EqualAttributeName ( const char *  name1,
const char *  name2 
)
static

◆ EqualOrdinal() [1/4]

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

◆ EqualOrdinal() [2/4]

bool ON_String::EqualOrdinal ( const char *  other_string,
bool  bOrdinalIgnoreCase 
) const

◆ EqualOrdinal() [3/4]

static bool ON_String::EqualOrdinal ( const char *  string1,
const char *  string2,
bool  bOrdinalIgnoreCase 
)
static

◆ EqualOrdinal() [4/4]

static bool ON_String::EqualOrdinal ( const char *  string1,
int  element_count1,
const char *  string2,
int  element_count2,
bool  bOrdinalIgnoreCase 
)
static

◆ EqualPath() [1/3]

bool ON_String::EqualPath ( const char *  other_path) const

◆ EqualPath() [2/3]

static bool ON_String::EqualPath ( const char *  path1,
const char *  path2 
)
static

◆ EqualPath() [3/3]

static bool ON_String::EqualPath ( const char *  path1,
int  element_count1,
const char *  path2,
int  element_count2 
)
static

◆ Find() [1/6]

int ON_String::Find ( char  utf8_single_byte_c) const

searching (return starting index, or -1 if not found) look for a single character match

◆ Find() [2/6]

int ON_String::Find ( unsigned char  utf8_single_byte_c) const

◆ Find() [3/6]

int ON_String::Find ( const char *  ) const

look for a specific sub-string

◆ Find() [4/6]

int ON_String::Find ( const unsigned char *  ) const

◆ Find() [5/6]

int ON_String::Find ( const char *  ,
int  start_index 
) const

◆ Find() [6/6]

int ON_String::Find ( const unsigned char *  ,
int  start_index 
) const

◆ Format() [1/2]

bool ON_VARGS_FUNC_CDECL ON_String::Format ( const char *  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));

◆ Format() [2/2]

bool ON_VARGS_FUNC_CDECL ON_String::Format ( const unsigned char *  format,
  ... 
)

◆ FormatIntoBuffer() [1/2]

static int ON_VARGS_FUNC_CDECL ON_String::FormatIntoBuffer ( char *  buffer,
size_t  buffer_capacity,
const char *  format,
  ... 
)
static

Description: A platform independent, secure, culture invariant way to format a char string. 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 char elements in buffer. sFormat - [in] Avoid using S (capital S). See the Remarks for details. ... - [in] Returns: >= 0: The number of char 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));

◆ FormatIntoBuffer() [2/2]

static int ON_VARGS_FUNC_CDECL ON_String::FormatIntoBuffer ( ON_StringBuffer buffer,
const char *  format,
  ... 
)
static

◆ FormatToString()

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

◆ FormatVargs() [1/2]

bool ON_String::FormatVargs ( const char *  format,
va_list  args 
)

◆ FormatVargs() [2/2]

bool ON_String::FormatVargs ( const unsigned char *  format,
va_list  args 
)

◆ FormatVargsIntoBuffer() [1/2]

static int ON_String::FormatVargsIntoBuffer ( char *  buffer,
size_t  buffer_capacity,
const char *  format,
va_list  args 
)
static

◆ FormatVargsIntoBuffer() [2/2]

static int ON_String::FormatVargsIntoBuffer ( ON_StringBuffer buffer,
const char *  format,
va_list  args 
)
static

◆ FormatVargsOutputCount()

static int ON_String::FormatVargsOutputCount ( const char *  format,
va_list  args 
)
static

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

◆ FromNumber() [1/9]

static const ON_String ON_String::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_String ON_String::FromNumber ( unsigned char  n)
static

◆ FromNumber() [3/9]

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

◆ FromNumber() [4/9]

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

◆ FromNumber() [5/9]

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

◆ FromNumber() [6/9]

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

◆ FromNumber() [7/9]

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

◆ FromNumber() [8/9]

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

◆ FromNumber() [9/9]

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

◆ GetAt()

char ON_String::GetAt ( int  ) const

◆ Header()

struct ON_aStringHeader* ON_String::Header ( ) const
protected

m_s - 12 bytes points at the string's ON_aStringHeader

implementation helpers

◆ HexadecimalFromBytes()

static const ON_String ON_String::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].

◆ IsEmpty()

bool ON_String::IsEmpty ( ) const

returns true if length == 0

◆ IsNotEmpty()

bool ON_String::IsNotEmpty ( ) const

returns true if length > 0

◆ IsReferenceCounted()

bool ON_String::IsReferenceCounted ( ) const

Returns: True if the string is reference counted.

◆ Left()

ON_String ON_String::Left ( int  ) const

◆ Length() [1/2]

int ON_String::Length ( ) const

Attributes & Operations.

Returns: number of nonzero elements in string.

◆ Length() [2/2]

static int ON_String::Length ( const char *  string)
static

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

◆ MakeLower()

void ON_String::MakeLower ( )

ON_DEPRECATED

◆ MakeLowerOrdinal()

void ON_String::MakeLowerOrdinal ( )

◆ MakeReverse()

void ON_String::MakeReverse ( )

◆ MakeUpper()

void ON_String::MakeUpper ( )

upper/lower/reverse conversion

ON_DEPRECATED

◆ MakeUpperOrdinal()

void ON_String::MakeUpperOrdinal ( )

◆ MapCharacterOrdinal()

static char ON_String::MapCharacterOrdinal ( ON_StringMapOrdinalType  map_type,
char  c 
)
static

Description: Map a single byte UTF-8 element to upper or lower case. Parameters: c - [in] If c is in the range A to Z or a to z, the map specified by map_type is applied. All other values of c are unchanged. Remarks: MapCharacterOrdinal is not appropriate for general string mapping.

◆ MapString() [1/3]

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

◆ MapString() [2/3]

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

◆ MapString() [3/3]

static int ON_String::MapString ( const class ON_Locale locale,
ON_StringMapType  map_type,
const char *  string,
int  element_count,
char *  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 char 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 char 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_String ON_String::MapStringOrdinal ( ON_StringMapOrdinalType  map_type) const

◆ MapStringOrdinal() [2/2]

static int ON_String::MapStringOrdinal ( ON_StringMapOrdinalType  map_type,
const char *  string,
int  element_count,
char *  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[]. map_type - [in] Returns: Number of mapped_string[] elements that were mapped from string[].

When the number of string[] input elements is >= mapped_string_capacity, mapped_string_capacity mapped_string[] elements are set and mapped_string_capacity is returned.

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

◆ Mid() [1/2]

ON_String ON_String::Mid ( int  ,
int   
) const

simple sub-string extraction

◆ Mid() [2/2]

ON_String ON_String::Mid ( int  ) const

◆ ON_DEPRECATED_MSG() [1/4]

ON_String::ON_DEPRECATED_MSG ( "Use   CompareOrdinal(),
ComparePath()  ,
CompareAttributeName()  ,
or a test that is linguistically apprropriate"   
) const

◆ ON_DEPRECATED_MSG() [2/4]

ON_String::ON_DEPRECATED_MSG ( "Use   CompareOrdinal(),
ComparePath()  ,
CompareAttributeName()  ,
or a test that is linguistically apprropriate"   
) const

◆ ON_DEPRECATED_MSG() [3/4]

ON_String::ON_DEPRECATED_MSG ( "Use   CompareOrdinal(),
ComparePath()  ,
CompareAttributeName()  ,
or a test that is linguistically apprropriate"   
) const

◆ ON_DEPRECATED_MSG() [4/4]

ON_String::ON_DEPRECATED_MSG ( "Use   CompareOrdinal(),
ComparePath()  ,
CompareAttributeName()  ,
or a test that is linguistically apprropriate"   
) const

◆ operator const char *()

ON_String::operator const char * ( ) const

◆ operator+() [1/5]

ON_String ON_String::operator+ ( const ON_String ) const

◆ operator+() [2/5]

ON_String ON_String::operator+ ( char  ) const

◆ operator+() [3/5]

ON_String ON_String::operator+ ( unsigned  char) const

◆ operator+() [4/5]

ON_String ON_String::operator+ ( const char *  ) const

◆ operator+() [5/5]

ON_String ON_String::operator+ ( const unsigned char *  ) const

◆ operator+=() [1/5]

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

◆ operator+=() [2/5]

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

◆ operator+=() [3/5]

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

◆ operator+=() [4/5]

const ON_String& ON_String::operator+= ( const char *  )

◆ operator+=() [5/5]

const ON_String& ON_String::operator+= ( const unsigned char *  )

◆ operator=() [1/7]

ON_String& ON_String::operator= ( const ON_String )

overloaded assignment

◆ operator=() [2/7]

ON_String& ON_String::operator= ( char  )

◆ operator=() [3/7]

ON_String& ON_String::operator= ( const char *  )

◆ operator=() [4/7]

ON_String& ON_String::operator= ( unsigned  char)

◆ operator=() [5/7]

ON_String& ON_String::operator= ( const unsigned char *  )

◆ operator=() [6/7]

ON_String& ON_String::operator= ( const wchar_t *  src)

src = Wide char string, result is a UTF-8 string

◆ operator=() [7/7]

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

src = Wide char string, result is a UTF-8 string

◆ operator[]() [1/2]

char& ON_String::operator[] ( int  )

◆ operator[]() [2/2]

char ON_String::operator[] ( int  ) const

◆ PreciseFromNumber()

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

◆ Remove()

int ON_String::Remove ( const char  utf8_single_byte_c)

remove occurrences of chRemove

◆ Replace() [1/4]

int ON_String::Replace ( const char *  token1,
const char *  token2 
)

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

◆ Replace() [2/4]

int ON_String::Replace ( const unsigned char *  token1,
const unsigned char *  token2 
)

◆ Replace() [3/4]

int ON_String::Replace ( char  utf8_single_byte_c1,
char  utf8_single_byte_c2 
)

◆ Replace() [4/4]

int ON_String::Replace ( unsigned char  utf8_single_byte_c1,
unsigned char  utf8_single_byte_c2 
)

◆ ReserveArray()

char* ON_String::ReserveArray ( size_t  )

Low level access to string contents as character array.

make sure internal array has at least

◆ Reverse() [1/2]

ON_String ON_String::Reverse ( ) const

◆ Reverse() [2/2]

static char* ON_String::Reverse ( char *  string,
int  element_count 
)
static

◆ ReverseFind() [1/4]

int ON_String::ReverseFind ( char  utf8_single_byte_c) const

◆ ReverseFind() [2/4]

int ON_String::ReverseFind ( unsigned char  utf8_single_byte_c) const

◆ ReverseFind() [3/4]

int ON_String::ReverseFind ( const char *  ) const

◆ ReverseFind() [4/4]

int ON_String::ReverseFind ( const unsigned char *  ) const

◆ Right()

ON_String ON_String::Right ( int  ) const

◆ Scan() [1/2]

int ON_VARGS_FUNC_CDECL ON_String::Scan ( const char *  format,
  ... 
)

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

◆ Scan() [2/2]

int ON_VARGS_FUNC_CDECL ON_String::Scan ( const unsigned char *  format,
  ... 
)

◆ ScanBuffer() [1/2]

static int ON_VARGS_FUNC_CDECL ON_String::ScanBuffer ( const char *  buffer,
const char *  format,
  ... 
)
static

◆ ScanBuffer() [2/2]

static int ON_VARGS_FUNC_CDECL ON_String::ScanBuffer ( const unsigned char *  buffer,
const unsigned char *  format,
  ... 
)
static

◆ ScanBufferVargs() [1/2]

static int ON_String::ScanBufferVargs ( const char *  buffer,
const char *  format,
va_list  args 
)
static

◆ ScanBufferVargs() [2/2]

static int ON_String::ScanBufferVargs ( const unsigned char *  buffer,
const unsigned char *  format,
va_list  args 
)
static

◆ SetAt() [1/2]

void ON_String::SetAt ( int  ,
char   
)

◆ SetAt() [2/2]

void ON_String::SetAt ( int  ,
unsigned  char 
)

◆ SetLength()

char* ON_String::SetLength ( size_t  )

set length (<=capacity)

◆ ShrinkArray()

void ON_String::ShrinkArray ( )

the requested capacity.

shrink internal storage to minimum size

◆ SizeOf()

unsigned int ON_String::SizeOf ( ) const

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

◆ SplitPath()

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

◆ ToNumber() [1/9]

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

Parameters: buffer - [in] decimal number Returns: not zero: pointer to the first character that was not scanned nullptr: failure

◆ ToNumber() [2/9]

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

◆ ToNumber() [3/9]

static const char* ON_String::ToNumber ( const char *  buffer,
short  value_on_failure,
short *  value 
)
static

◆ ToNumber() [4/9]

static const char* ON_String::ToNumber ( const char *  buffer,
unsigned short  value_on_failure,
unsigned short *  value 
)
static

◆ ToNumber() [5/9]

static const char* ON_String::ToNumber ( const char *  buffer,
int  value_on_failure,
int *  value 
)
static

◆ ToNumber() [6/9]

static const char* ON_String::ToNumber ( const char *  buffer,
unsigned int  value_on_failure,
unsigned int *  value 
)
static

◆ ToNumber() [7/9]

static const char* ON_String::ToNumber ( const char *  buffer,
ON__INT64  value_on_failure,
ON__INT64 *  value 
)
static

◆ ToNumber() [8/9]

static const char* ON_String::ToNumber ( const char *  buffer,
ON__UINT64  value_on_failure,
ON__UINT64 *  value 
)
static

◆ ToNumber() [9/9]

static const char* ON_String::ToNumber ( const char *  buffer,
double  value_on_failure,
double *  value 
)
static

◆ TrimLeft()

void ON_String::TrimLeft ( const char *  = nullptr)

◆ TrimLeftAndRight()

void ON_String::TrimLeftAndRight ( const char *  = nullptr)

◆ TrimRight()

void ON_String::TrimRight ( const char *  = nullptr)

◆ UnsignedLength() [1/2]

unsigned int ON_String::UnsignedLength ( ) const

Returns: number of nonzero elements in the string.

◆ UnsignedLength() [2/2]

static unsigned int ON_String::UnsignedLength ( const char *  string)
static

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

◆ WildCardMatch() [1/2]

bool ON_String::WildCardMatch ( const char *  ) 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.

◆ WildCardMatch() [2/2]

bool ON_String::WildCardMatch ( const unsigned char *  ) const

◆ WildCardMatchNoCase() [1/2]

bool ON_String::WildCardMatchNoCase ( const char *  ) 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.

◆ WildCardMatchNoCase() [2/2]

bool ON_String::WildCardMatchNoCase ( const unsigned char *  ) const

Member Data Documentation

◆ Backslash

const char ON_String::Backslash
static

Unicode REVERSE SOLIDUS U+005C.

◆ Backspace

const char ON_String::Backspace
static

Unicode BACKSPACE control U+0008.

◆ CarriageReturn

const char ON_String::CarriageReturn
static

Unicode CHARACTER TABULATION control U+000D.

◆ EmptyString

const ON_String ON_String::EmptyString
static

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

◆ Escape

const char ON_String::Escape
static

Unicode CARRIAGE RETURN control U+001B.

◆ FormFeed

const char ON_String::FormFeed
static

Unicode FORM FEED control U+000C.

◆ LineFeed

const char ON_String::LineFeed
static

Unicode LINE FEED control U+000A.

◆ m_s

char* ON_String::m_s
protected

Implementation.

pointer to ref counted string array

◆ Pipe

const char ON_String::Pipe
static

Unicode VERTICAL LINE U+007C.

◆ Slash

const char ON_String::Slash
static

Unicode SOLIDUS U+002F.

◆ Space

const char ON_String::Space
static

Unicode SPACE U+0020.

◆ Tab

const char ON_String::Tab
static

Unicode CHARACTER TABULATION control U+0009.

◆ VerticalTab

const char ON_String::VerticalTab
static

Unicode LINE TABULATION control U+000B.