Open CASCADE Technology 7.8.2.dev
TCollection_ExtendedString Class Reference

A variable-length sequence of "extended" (UNICODE) characters (16-bit character type). It provides editing operations with built-in memory management to make ExtendedString objects easier to use than ordinary extended character arrays. ExtendedString objects follow "value semantics", that is, they are the actual strings, not handles to strings, and are copied through assignment. You may use HExtendedString objects to get handles to strings. More...

#include <TCollection_ExtendedString.hxx>

Public Member Functions

 TCollection_ExtendedString ()
 Initializes a ExtendedString to an empty ExtendedString.
 
 TCollection_ExtendedString (const Standard_CString astring, const Standard_Boolean isMultiByte=Standard_False)
 Creation by converting a CString to an extended string. If <isMultiByte> is true then the string is treated as having UTF-8 coding. If it is not a UTF-8 then <isMultiByte> is ignored and each character is copied to ExtCharacter.
 
 TCollection_ExtendedString (const Standard_ExtString astring)
 Creation by converting an ExtString to an extended string.
 
 TCollection_ExtendedString (const Standard_WideChar *theStringUtf)
 Initialize from wide-char string considering it as Unicode string (the size of wide char is a platform-dependent - e.g. on Windows wchar_t is UTF-16).
 
 TCollection_ExtendedString (const Standard_Character aChar)
 Initializes a AsciiString with a single character.
 
 TCollection_ExtendedString (const Standard_ExtCharacter aChar)
 Initializes a ExtendedString with a single character.
 
 TCollection_ExtendedString (const Standard_Integer length, const Standard_ExtCharacter filler)
 Initializes a ExtendedString with <length> space allocated. and filled with <filler>.This is useful for buffers.
 
 TCollection_ExtendedString (const Standard_Integer value)
 Initializes an ExtendedString with an integer value.
 
 TCollection_ExtendedString (const Standard_Real value)
 Initializes an ExtendedString with a real value.
 
 TCollection_ExtendedString (const TCollection_ExtendedString &astring)
 Initializes a ExtendedString with another ExtendedString.
 
 TCollection_ExtendedString (TCollection_ExtendedString &&theOther) Standard_Noexcept
 Move constructor.
 
 TCollection_ExtendedString (const TCollection_AsciiString &astring, const Standard_Boolean isMultiByte=Standard_True)
 Creation by converting an Ascii string to an extended string. The string is treated as having UTF-8 coding. If it is not a UTF-8 or multi byte then each character is copied to ExtCharacter.
 
void AssignCat (const TCollection_ExtendedString &other)
 Appends the other extended string to this extended string. Note that this method is an alias of operator +=. Example: aString += anotherString.
 
void operator+= (const TCollection_ExtendedString &other)
 
void AssignCat (const Standard_Utf16Char theChar)
 Appends the utf16 char to this extended string.
 
TCollection_ExtendedString Cat (const TCollection_ExtendedString &other) const
 Appends <other> to me.
 
TCollection_ExtendedString operator+ (const TCollection_ExtendedString &other) const
 
void ChangeAll (const Standard_ExtCharacter aChar, const Standard_ExtCharacter NewChar)
 Substitutes all the characters equal to aChar by NewChar in the ExtendedString <me>. The substitution can be case sensitive. If you don't use default case sensitive, no matter whether aChar is uppercase or not.
 
void Clear ()
 Removes all characters contained in <me>. This produces an empty ExtendedString.
 
void Copy (const TCollection_ExtendedString &fromwhere)
 Copy <fromwhere> to <me>. Used as operator =.
 
TCollection_ExtendedStringoperator= (const TCollection_ExtendedString &theOther)
 Copy assignment operator.
 
void Move (TCollection_ExtendedString &&theOther)
 Moves string without reallocations.
 
TCollection_ExtendedStringoperator= (TCollection_ExtendedString &&theOther) noexcept
 Move assignment operator.
 
void Swap (TCollection_ExtendedString &theOther)
 Exchange the data of two strings (without reallocating memory).
 
 ~TCollection_ExtendedString ()
 Frees memory allocated by ExtendedString.
 
void Insert (const Standard_Integer where, const Standard_ExtCharacter what)
 Insert a Character at position <where>.
 
void Insert (const Standard_Integer where, const TCollection_ExtendedString &what)
 Insert a ExtendedString at position <where>.
 
Standard_Boolean IsEmpty () const
 Returns True if this string contains no characters.
 
Standard_Boolean IsEqual (const Standard_ExtString other) const
 Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.
 
Standard_Boolean operator== (const Standard_ExtString other) const
 
Standard_Boolean IsEqual (const TCollection_ExtendedString &other) const
 Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.
 
Standard_Boolean operator== (const TCollection_ExtendedString &other) const
 
Standard_Boolean IsDifferent (const Standard_ExtString other) const
 Returns true if there are differences between the characters in this extended string and the other extended string. Note that this method is an alias of operator !=.
 
Standard_Boolean operator!= (const Standard_ExtString other) const
 
Standard_Boolean IsDifferent (const TCollection_ExtendedString &other) const
 Returns true if there are differences between the characters in this extended string and the other extended string. Note that this method is an alias of operator !=.
 
Standard_Boolean operator!= (const TCollection_ExtendedString &other) const
 
Standard_Boolean IsLess (const Standard_ExtString other) const
 Returns TRUE if <me> is less than <other>.
 
Standard_Boolean operator< (const Standard_ExtString other) const
 
Standard_Boolean IsLess (const TCollection_ExtendedString &other) const
 Returns TRUE if <me> is less than <other>.
 
Standard_Boolean operator< (const TCollection_ExtendedString &other) const
 
Standard_Boolean IsGreater (const Standard_ExtString other) const
 Returns TRUE if <me> is greater than <other>.
 
Standard_Boolean operator> (const Standard_ExtString other) const
 
Standard_Boolean IsGreater (const TCollection_ExtendedString &other) const
 Returns TRUE if <me> is greater than <other>.
 
Standard_Boolean operator> (const TCollection_ExtendedString &other) const
 
Standard_Boolean StartsWith (const TCollection_ExtendedString &theStartString) const
 Determines whether the beginning of this string instance matches the specified string.
 
Standard_Boolean EndsWith (const TCollection_ExtendedString &theEndString) const
 Determines whether the end of this string instance matches the specified string.
 
Standard_Boolean IsAscii () const
 Returns True if the ExtendedString contains only "Ascii Range" characters .
 
Standard_Integer Length () const
 Returns the number of 16-bit code units (might be greater than number of Unicode symbols if string contains surrogate pairs).
 
void Print (Standard_OStream &astream) const
 Displays <me> .
 
void RemoveAll (const Standard_ExtCharacter what)
 Removes every <what> characters from <me>.
 
void Remove (const Standard_Integer where, const Standard_Integer ahowmany=1)
 Erases <ahowmany> characters from position <where>,<where> included.
 
Standard_Integer Search (const TCollection_ExtendedString &what) const
 Searches a ExtendedString in <me> from the beginning and returns position of first item <what> matching. it returns -1 if not found.
 
Standard_Integer SearchFromEnd (const TCollection_ExtendedString &what) const
 Searches a ExtendedString in another ExtendedString from the end and returns position of first item <what> matching. it returns -1 if not found.
 
void SetValue (const Standard_Integer where, const Standard_ExtCharacter what)
 Replaces one character in the ExtendedString at position <where>. If <where> is less than zero or greater than the length of <me> an exception is raised.
 
void SetValue (const Standard_Integer where, const TCollection_ExtendedString &what)
 Replaces a part of <me> by another ExtendedString see above.
 
TCollection_ExtendedString Split (const Standard_Integer where)
 Splits this extended string into two sub-strings at position where.
 
TCollection_ExtendedString Token (const Standard_ExtString separators, const Standard_Integer whichone=1) const
 Extracts <whichone> token from <me>. By default, the <separators> is set to space and tabulation. By default, the token extracted is the first one (whichone = 1). <separators> contains all separators you need. If no token indexed by <whichone> is found, it returns an empty AsciiString. Example: aString contains "This is a message" aString.Token() returns "This" aString.Token(" ",4) returns "message" aString.Token(" ",2) returns "is" aString.Token(" ",9) returns "" Other separators than space character and tabulation are allowed : aString contains "1234; test:message , value" aString.Token("; :,",4) returns "value" aString.Token("; :,",2) returns "test".
 
Standard_ExtString ToExtString () const
 Returns pointer to ExtString.
 
void Trunc (const Standard_Integer ahowmany)
 Truncates <me> to <ahowmany> characters. Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel" Exceptions Standard_OutOfRange if ahowmany is greater than the length of this string.
 
Standard_ExtCharacter Value (const Standard_Integer where) const
 Returns character at position <where> in <me>. If <where> is less than zero or greater than the length of <me>, an exception is raised. Example: aString contains "Hello" aString.Value(2) returns 'e' Exceptions Standard_OutOfRange if where lies outside the bounds of this extended string.
 
size_t HashCode () const
 Returns a hashed value for the extended string. Note: if string is ASCII, the computed value is the same as the value computed with the HashCode function on a TCollection_AsciiString string composed with equivalent ASCII characters.
 
Standard_Integer ToUTF8CString (Standard_PCharacter &theCString) const
 Converts the internal <mystring> to UTF8 coding and returns length of the out CString. A memory for the <theCString> should be allocated before call!
 
Standard_Integer LengthOfCString () const
 Returns expected CString length in UTF8 coding. It can be used for memory calculation before converting to CString containing symbols in UTF8 coding.
 

Static Public Member Functions

static Standard_Boolean IsEqual (const TCollection_ExtendedString &theString1, const TCollection_ExtendedString &theString2)
 Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.
 

Detailed Description

A variable-length sequence of "extended" (UNICODE) characters (16-bit character type). It provides editing operations with built-in memory management to make ExtendedString objects easier to use than ordinary extended character arrays. ExtendedString objects follow "value semantics", that is, they are the actual strings, not handles to strings, and are copied through assignment. You may use HExtendedString objects to get handles to strings.

Beware that class can transparently store UTF-16 string with surrogate pairs (Unicode symbol represented by two 16-bit code units). However, surrogate pairs are not considered by the following methods:

  • Method Length() return the number of 16-bit code units, not the number of Unicode symbols.
  • Methods taking/returning symbol index work with 16-bit code units, not true Unicode symbols, including Remove(), SetValue(), Value(), Search(), Trunc() and others. If application needs to process surrogate pairs, NCollection_Utf16Iter class can be used for iterating through Unicode string (UTF-32 code unit will be returned for each position).

Constructor & Destructor Documentation

◆ TCollection_ExtendedString() [1/12]

TCollection_ExtendedString::TCollection_ExtendedString ( )

Initializes a ExtendedString to an empty ExtendedString.

◆ TCollection_ExtendedString() [2/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_CString astring,
const Standard_Boolean isMultiByte = Standard_False )

Creation by converting a CString to an extended string. If <isMultiByte> is true then the string is treated as having UTF-8 coding. If it is not a UTF-8 then <isMultiByte> is ignored and each character is copied to ExtCharacter.

◆ TCollection_ExtendedString() [3/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_ExtString astring)

Creation by converting an ExtString to an extended string.

◆ TCollection_ExtendedString() [4/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_WideChar * theStringUtf)

Initialize from wide-char string considering it as Unicode string (the size of wide char is a platform-dependent - e.g. on Windows wchar_t is UTF-16).

This constructor is unavailable if application is built with deprecated msvc option "-Zc:wchar_t-", since OCCT itself is never built with this option.

◆ TCollection_ExtendedString() [5/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_Character aChar)

Initializes a AsciiString with a single character.

◆ TCollection_ExtendedString() [6/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_ExtCharacter aChar)

Initializes a ExtendedString with a single character.

◆ TCollection_ExtendedString() [7/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_Integer length,
const Standard_ExtCharacter filler )

Initializes a ExtendedString with <length> space allocated. and filled with <filler>.This is useful for buffers.

◆ TCollection_ExtendedString() [8/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_Integer value)

Initializes an ExtendedString with an integer value.

◆ TCollection_ExtendedString() [9/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const Standard_Real value)

Initializes an ExtendedString with a real value.

◆ TCollection_ExtendedString() [10/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const TCollection_ExtendedString & astring)

Initializes a ExtendedString with another ExtendedString.

◆ TCollection_ExtendedString() [11/12]

TCollection_ExtendedString::TCollection_ExtendedString ( TCollection_ExtendedString && theOther)

Move constructor.

◆ TCollection_ExtendedString() [12/12]

TCollection_ExtendedString::TCollection_ExtendedString ( const TCollection_AsciiString & astring,
const Standard_Boolean isMultiByte = Standard_True )

Creation by converting an Ascii string to an extended string. The string is treated as having UTF-8 coding. If it is not a UTF-8 or multi byte then each character is copied to ExtCharacter.

◆ ~TCollection_ExtendedString()

TCollection_ExtendedString::~TCollection_ExtendedString ( )

Frees memory allocated by ExtendedString.

Member Function Documentation

◆ AssignCat() [1/2]

void TCollection_ExtendedString::AssignCat ( const Standard_Utf16Char theChar)

Appends the utf16 char to this extended string.

◆ AssignCat() [2/2]

void TCollection_ExtendedString::AssignCat ( const TCollection_ExtendedString & other)

Appends the other extended string to this extended string. Note that this method is an alias of operator +=. Example: aString += anotherString.

◆ Cat()

TCollection_ExtendedString TCollection_ExtendedString::Cat ( const TCollection_ExtendedString & other) const

Appends <other> to me.

◆ ChangeAll()

void TCollection_ExtendedString::ChangeAll ( const Standard_ExtCharacter aChar,
const Standard_ExtCharacter NewChar )

Substitutes all the characters equal to aChar by NewChar in the ExtendedString <me>. The substitution can be case sensitive. If you don't use default case sensitive, no matter whether aChar is uppercase or not.

◆ Clear()

void TCollection_ExtendedString::Clear ( )

Removes all characters contained in <me>. This produces an empty ExtendedString.

◆ Copy()

void TCollection_ExtendedString::Copy ( const TCollection_ExtendedString & fromwhere)

Copy <fromwhere> to <me>. Used as operator =.

◆ EndsWith()

Standard_Boolean TCollection_ExtendedString::EndsWith ( const TCollection_ExtendedString & theEndString) const

Determines whether the end of this string instance matches the specified string.

◆ HashCode()

size_t TCollection_ExtendedString::HashCode ( ) const
inline

Returns a hashed value for the extended string. Note: if string is ASCII, the computed value is the same as the value computed with the HashCode function on a TCollection_AsciiString string composed with equivalent ASCII characters.

Returns
a computed hash code

◆ Insert() [1/2]

void TCollection_ExtendedString::Insert ( const Standard_Integer where,
const Standard_ExtCharacter what )

Insert a Character at position <where>.

◆ Insert() [2/2]

void TCollection_ExtendedString::Insert ( const Standard_Integer where,
const TCollection_ExtendedString & what )

Insert a ExtendedString at position <where>.

◆ IsAscii()

Standard_Boolean TCollection_ExtendedString::IsAscii ( ) const

Returns True if the ExtendedString contains only "Ascii Range" characters .

◆ IsDifferent() [1/2]

Standard_Boolean TCollection_ExtendedString::IsDifferent ( const Standard_ExtString other) const

Returns true if there are differences between the characters in this extended string and the other extended string. Note that this method is an alias of operator !=.

◆ IsDifferent() [2/2]

Standard_Boolean TCollection_ExtendedString::IsDifferent ( const TCollection_ExtendedString & other) const

Returns true if there are differences between the characters in this extended string and the other extended string. Note that this method is an alias of operator !=.

◆ IsEmpty()

Standard_Boolean TCollection_ExtendedString::IsEmpty ( ) const
inline

Returns True if this string contains no characters.

◆ IsEqual() [1/3]

Standard_Boolean TCollection_ExtendedString::IsEqual ( const Standard_ExtString other) const

Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.

◆ IsEqual() [2/3]

Standard_Boolean TCollection_ExtendedString::IsEqual ( const TCollection_ExtendedString & other) const

Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.

◆ IsEqual() [3/3]

static Standard_Boolean TCollection_ExtendedString::IsEqual ( const TCollection_ExtendedString & theString1,
const TCollection_ExtendedString & theString2 )
inlinestatic

Returns true if the characters in this extended string are identical to the characters in the other extended string. Note that this method is an alias of operator ==.

◆ IsGreater() [1/2]

Standard_Boolean TCollection_ExtendedString::IsGreater ( const Standard_ExtString other) const

Returns TRUE if <me> is greater than <other>.

◆ IsGreater() [2/2]

Standard_Boolean TCollection_ExtendedString::IsGreater ( const TCollection_ExtendedString & other) const

Returns TRUE if <me> is greater than <other>.

◆ IsLess() [1/2]

Standard_Boolean TCollection_ExtendedString::IsLess ( const Standard_ExtString other) const

Returns TRUE if <me> is less than <other>.

◆ IsLess() [2/2]

Standard_Boolean TCollection_ExtendedString::IsLess ( const TCollection_ExtendedString & other) const

Returns TRUE if <me> is less than <other>.

◆ Length()

Standard_Integer TCollection_ExtendedString::Length ( ) const

Returns the number of 16-bit code units (might be greater than number of Unicode symbols if string contains surrogate pairs).

◆ LengthOfCString()

Standard_Integer TCollection_ExtendedString::LengthOfCString ( ) const

Returns expected CString length in UTF8 coding. It can be used for memory calculation before converting to CString containing symbols in UTF8 coding.

◆ Move()

void TCollection_ExtendedString::Move ( TCollection_ExtendedString && theOther)

Moves string without reallocations.

◆ operator!=() [1/2]

Standard_Boolean TCollection_ExtendedString::operator!= ( const Standard_ExtString other) const
inline

◆ operator!=() [2/2]

Standard_Boolean TCollection_ExtendedString::operator!= ( const TCollection_ExtendedString & other) const
inline

◆ operator+()

TCollection_ExtendedString TCollection_ExtendedString::operator+ ( const TCollection_ExtendedString & other) const
inline

◆ operator+=()

void TCollection_ExtendedString::operator+= ( const TCollection_ExtendedString & other)
inline

◆ operator<() [1/2]

Standard_Boolean TCollection_ExtendedString::operator< ( const Standard_ExtString other) const
inline

◆ operator<() [2/2]

Standard_Boolean TCollection_ExtendedString::operator< ( const TCollection_ExtendedString & other) const
inline

◆ operator=() [1/2]

TCollection_ExtendedString & TCollection_ExtendedString::operator= ( const TCollection_ExtendedString & theOther)
inline

Copy assignment operator.

◆ operator=() [2/2]

TCollection_ExtendedString & TCollection_ExtendedString::operator= ( TCollection_ExtendedString && theOther)
inlinenoexcept

Move assignment operator.

◆ operator==() [1/2]

Standard_Boolean TCollection_ExtendedString::operator== ( const Standard_ExtString other) const
inline

◆ operator==() [2/2]

Standard_Boolean TCollection_ExtendedString::operator== ( const TCollection_ExtendedString & other) const
inline

◆ operator>() [1/2]

Standard_Boolean TCollection_ExtendedString::operator> ( const Standard_ExtString other) const
inline

◆ operator>() [2/2]

Standard_Boolean TCollection_ExtendedString::operator> ( const TCollection_ExtendedString & other) const
inline

◆ Print()

void TCollection_ExtendedString::Print ( Standard_OStream & astream) const

Displays <me> .

◆ Remove()

void TCollection_ExtendedString::Remove ( const Standard_Integer where,
const Standard_Integer ahowmany = 1 )

Erases <ahowmany> characters from position <where>,<where> included.

◆ RemoveAll()

void TCollection_ExtendedString::RemoveAll ( const Standard_ExtCharacter what)

Removes every <what> characters from <me>.

◆ Search()

Standard_Integer TCollection_ExtendedString::Search ( const TCollection_ExtendedString & what) const

Searches a ExtendedString in <me> from the beginning and returns position of first item <what> matching. it returns -1 if not found.

◆ SearchFromEnd()

Standard_Integer TCollection_ExtendedString::SearchFromEnd ( const TCollection_ExtendedString & what) const

Searches a ExtendedString in another ExtendedString from the end and returns position of first item <what> matching. it returns -1 if not found.

◆ SetValue() [1/2]

void TCollection_ExtendedString::SetValue ( const Standard_Integer where,
const Standard_ExtCharacter what )

Replaces one character in the ExtendedString at position <where>. If <where> is less than zero or greater than the length of <me> an exception is raised.

◆ SetValue() [2/2]

void TCollection_ExtendedString::SetValue ( const Standard_Integer where,
const TCollection_ExtendedString & what )

Replaces a part of <me> by another ExtendedString see above.

◆ Split()

TCollection_ExtendedString TCollection_ExtendedString::Split ( const Standard_Integer where)

Splits this extended string into two sub-strings at position where.

  • The second sub-string (from position where + 1 of this string to the end) is returned in a new extended string.
  • this extended string is modified: its last characters are removed, it becomes equal to the first sub-string (from the first character to position where). Example: aString contains "abcdefg" aString.Split(3) gives <me> = "abc" and returns "defg"

◆ StartsWith()

Standard_Boolean TCollection_ExtendedString::StartsWith ( const TCollection_ExtendedString & theStartString) const

Determines whether the beginning of this string instance matches the specified string.

◆ Swap()

void TCollection_ExtendedString::Swap ( TCollection_ExtendedString & theOther)

Exchange the data of two strings (without reallocating memory).

◆ ToExtString()

Standard_ExtString TCollection_ExtendedString::ToExtString ( ) const

Returns pointer to ExtString.

◆ Token()

TCollection_ExtendedString TCollection_ExtendedString::Token ( const Standard_ExtString separators,
const Standard_Integer whichone = 1 ) const

Extracts <whichone> token from <me>. By default, the <separators> is set to space and tabulation. By default, the token extracted is the first one (whichone = 1). <separators> contains all separators you need. If no token indexed by <whichone> is found, it returns an empty AsciiString. Example: aString contains "This is a message" aString.Token() returns "This" aString.Token(" ",4) returns "message" aString.Token(" ",2) returns "is" aString.Token(" ",9) returns "" Other separators than space character and tabulation are allowed : aString contains "1234; test:message , value" aString.Token("; :,",4) returns "value" aString.Token("; :,",2) returns "test".

◆ ToUTF8CString()

Standard_Integer TCollection_ExtendedString::ToUTF8CString ( Standard_PCharacter & theCString) const

Converts the internal <mystring> to UTF8 coding and returns length of the out CString. A memory for the <theCString> should be allocated before call!

◆ Trunc()

void TCollection_ExtendedString::Trunc ( const Standard_Integer ahowmany)

Truncates <me> to <ahowmany> characters. Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel" Exceptions Standard_OutOfRange if ahowmany is greater than the length of this string.

◆ Value()

Standard_ExtCharacter TCollection_ExtendedString::Value ( const Standard_Integer where) const

Returns character at position <where> in <me>. If <where> is less than zero or greater than the length of <me>, an exception is raised. Example: aString contains "Hello" aString.Value(2) returns 'e' Exceptions Standard_OutOfRange if where lies outside the bounds of this extended string.


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