Foxit PDF SDK
CFX_WideString Class Reference

WIDE STRING CLASS. More...

Inherits CFX_Object.

Public Member Functions

 CFX_WideString ()
 Construct a null wide string.
 
 CFX_WideString (const CFX_WideString &str)
 Copy constructor. More...
 
 CFX_WideString (FX_LPCWSTR ptr, FX_STRSIZE len=-1)
 Construct from a wide character string. More...
 
 CFX_WideString (FX_WCHAR ch)
 Construct from a single wide character. More...
 
 CFX_WideString (const CFX_WideStringC &str)
 Construct from a constant ref to a CFX_WideStringC object. More...
 
 CFX_WideString (const CFX_WideStringC &str1, const CFX_WideStringC &str2)
 Concatenate constructor. More...
 
 ~CFX_WideString ()
 The Destructor.
 
int Compare (FX_LPCWSTR str) const
 Compare current string with a wide character string. Case-sensitive. More...
 
int Compare (const CFX_WideString &str) const
 Compare the the string with another. Case-sensitive. More...
 
int CompareNoCase (FX_LPCWSTR str) const
 Compare the the string with a wide character string. No case-insensitive. More...
 
void ConvertFrom (const CFX_ByteString &str, CFX_CharMap *pCharMap=NULL)
 Load MBCS data into this wide string, using specified character mapper. More...
 
FX_STRSIZE Delete (FX_STRSIZE index, FX_STRSIZE count=1)
 Delete one or more wide characters starting from specific position. More...
 
void Empty ()
 Set this string to be empty. More...
 
bool Equal (const CFX_WideStringC &str) const
 Check if current string is equal to another. More...
 
FX_STRSIZE Find (FX_LPCWSTR lpszSub, FX_STRSIZE start=0) const
 Find a sub-string, from specific position. Only first occurrence is found. More...
 
FX_STRSIZE Find (FX_WCHAR ch, FX_STRSIZE start=0) const
 Find a character, from specific position. Only first occurrence is found. More...
 
void Format (FX_LPCWSTR lpszFormat,...)
 Format a number of parameters into this wide string. More...
 
void FormatV (FX_LPCWSTR lpszFormat, va_list argList)
 Format a number of parameters into this wide string. using va_list. More...
 
FX_WCHAR GetAt (FX_STRSIZE nIndex) const
 Retrieves a single wide character specified by an index number. More...
 
FX_LPWSTR GetBuffer (FX_STRSIZE len)
 Get a buffer with specific number of characters allocated. More...
 
FX_FLOAT GetFloat () const
 Convert to other data type. More...
 
int GetInteger () const
 Convert to other data type. More...
 
FX_STRSIZE GetLength () const
 Get number of characters, not bytes. Trailing zero not counted. More...
 
FX_STRSIZE Insert (FX_STRSIZE index, FX_WCHAR ch)
 Insert a wide character before specific position. More...
 
FX_BOOL IsEmpty () const
 Check whether current string object is empty. More...
 
CFX_WideString Left (FX_STRSIZE count) const
 Extracts the first (leftmost) count wide characters from this CFX_WideString object as a sub-string. More...
 
FX_LPWSTR LockBuffer ()
 Lock and get the current string buffer, so the caller can modify the returned buffer. Caller can modified the returned buffer, and should call CFX_WideString::ReleaseBuffer after modification done. More...
 
void MakeLower ()
 Change case of English letters to lower. More...
 
void MakeUpper ()
 Change case of English letters to upper. More...
 
CFX_WideString Mid (FX_STRSIZE first) const
 Extracts a substring from this CFX_WideString object, starting at position nFirst (zero-based) to last. More...
 
CFX_WideString Mid (FX_STRSIZE first, FX_STRSIZE count) const
 Extracts a substring of count wide character from this CFX_WideString object, starting at position nFirst (zero-based) to last. More...
 
 operator FX_LPCWSTR () const
 FX_LPCWSTR type conversion operator.
 
const CFX_WideStringoperator+= (FX_LPCWSTR str)
 Concatenation(+=) operator overload. Concatenate a wide character string. More...
 
const CFX_WideStringoperator+= (FX_WCHAR ch)
 Concatenation(+=) operator overload. Concatenate a single wide character. More...
 
const CFX_WideStringoperator+= (const CFX_WideString &str)
 Concatenation(+=) operator overload. Concatenate a wide string. More...
 
const CFX_WideStringoperator+= (const CFX_WideStringC &str)
 Concatenation(+=) operator overload. Concatenate a constant wide string. More...
 
const CFX_WideStringoperator= (FX_LPCWSTR str)
 Assignment(=) operator overload. From a wide character string. More...
 
const CFX_WideStringoperator= (const CFX_WideString &stringSrc)
 Assignment(=) operator overload. From a wide string. More...
 
const CFX_WideStringoperator= (const CFX_WideStringC &stringSrc)
 Assignment(=) operator overload. From a const wide string. More...
 
FX_WCHAR operator[] (FX_STRSIZE nIndex) const
 Subscript([]) operator overload. It retrieves a wide character specified by the zero-based index in nIndex. More...
 
void ReleaseBuffer (FX_STRSIZE len=-1)
 Release the buffer fetched by function CFX_WideString::GetBuffer or CFX_WideString::LockBuffer, and set the length of modified string. More...
 
FX_STRSIZE Remove (FX_WCHAR ch)
 Remove all occurrence of a particular character. More...
 
FX_STRSIZE Replace (FX_LPCWSTR lpszOld, FX_LPCWSTR lpszNew)
 Replace all patterns in the string with a new sub-string. More...
 
void Reserve (FX_STRSIZE len)
 Reserve a buffer that can hold specific number of characters. More...
 
CFX_WideString Right (FX_STRSIZE count) const
 Extracts the last (rightmost) count wide characters from this CFX_WideString object as a sub-string. More...
 
void SetAt (FX_STRSIZE nIndex, FX_WCHAR ch)
 Overwrites a single wide character specified by an index number. More...
 
void TrimLeft ()
 Trim white spaces from the left side of the wide string. More...
 
void TrimLeft (FX_WCHAR chTarget)
 Trim continuous occurrences of specified character from left side of the wide string. More...
 
void TrimLeft (FX_LPCWSTR lpszTargets)
 Trim continuous occurrences of specified characters from left side of the wide string. More...
 
void TrimRight ()
 Trim white spaces from the right side of the wide string. More...
 
void TrimRight (FX_WCHAR chTarget)
 Trim continuous occurrences of specified character from right side of the wide string. More...
 
void TrimRight (FX_LPCWSTR lpszTargets)
 Trim continuous occurrences of specified characters from right side of the wide string. More...
 
CFX_ByteString UTF16LE_Encode (FX_BOOL bTerminate=true) const
 Do UTF16LE encoding. More...
 
CFX_ByteString UTF8Encode () const
 Do UTF8 encoding. More...
 

Static Public Member Functions

static CFX_WideString FromLocal (const char *str, FX_STRSIZE len=-1)
 Create a wide string from system multi-byte charset. More...
 
static CFX_WideString FromUTF16BE (const unsigned short *str, FX_STRSIZE len=-1)
 Create a wide string from UTF16BE encoded string. More...
 
static CFX_WideString FromUTF16LE (const unsigned short *str, FX_STRSIZE len=-1)
 Create a wide string from UTF16LE encoded string. More...
 
static CFX_WideString FromUTF8 (const char *str, FX_STRSIZE len=-1)
 Create a wide string from UTF-8 string (ASCII string compatible). More...
 
static FX_STRSIZE WStringLength (const unsigned short *str)
 Length of string. More...
 

Detailed Description

WIDE STRING CLASS.

On Windows platforms, a wide string is represented by UTF-16LE encoding; On Unix/Linux platforms, a wide string is represented by UCS-4 encoding.

Constructor & Destructor Documentation

◆ CFX_WideString() [1/5]

CFX_WideString::CFX_WideString ( const CFX_WideString str)

Copy constructor.

Parameters
[in]strA constant ref to a CFX_WideString object.

◆ CFX_WideString() [2/5]

CFX_WideString::CFX_WideString ( FX_LPCWSTR  ptr,
FX_STRSIZE  len = -1 
)
inline

Construct from a wide character string.

Parameters
[in]ptrPointer to a constant wide character string.
[in]lenThe length of the wide character string. This can be -1 for zero terminated wide character string.

◆ CFX_WideString() [3/5]

CFX_WideString::CFX_WideString ( FX_WCHAR  ch)

Construct from a single wide character.

Parameters
[in]chA single wide character.

◆ CFX_WideString() [4/5]

CFX_WideString::CFX_WideString ( const CFX_WideStringC str)

Construct from a constant ref to a CFX_WideStringC object.

Parameters
[in]strA constant ref to a CFX_WideStringC object.

◆ CFX_WideString() [5/5]

CFX_WideString::CFX_WideString ( const CFX_WideStringC str1,
const CFX_WideStringC str2 
)

Concatenate constructor.

Parameters
[in]str1Fist constant ref to a CFX_WideStringC object.
[in]str2Second constant ref to a CFX_WideStringC object.

Member Function Documentation

◆ Compare() [1/2]

int CFX_WideString::Compare ( FX_LPCWSTR  str) const

Compare current string with a wide character string. Case-sensitive.

Parameters
[in]strThe wide character string to be compared.
Returns
  • -1 means current string is "smaller" (in alphabetic order) than the other one.
  • 0 means equal.
  • 1 means current string is "larger" (in alphabetic order) than the other one.

◆ Compare() [2/2]

int CFX_WideString::Compare ( const CFX_WideString str) const

Compare the the string with another. Case-sensitive.

Parameters
[in]strThe wide string to be compared.
Returns
  • -1 means current string is "smaller" (in alphabetic order) than the other one.
  • 0 means equal.
  • 1 means current string is "larger" (in alphabetic order) than the other one.

◆ CompareNoCase()

int CFX_WideString::CompareNoCase ( FX_LPCWSTR  str) const

Compare the the string with a wide character string. No case-insensitive.

Parameters
[in]strThe wide character string to be compared.
Returns
  • -1 means current string is "smaller" (in alphabetic order) than the other one.
  • 0 means equal.
  • 1 means current string is "larger" (in alphabetic order) than the other one.

◆ ConvertFrom()

void CFX_WideString::ConvertFrom ( const CFX_ByteString str,
CFX_CharMap pCharMap = NULL 
)

Load MBCS data into this wide string, using specified character mapper.

If no character mapper specified, the system default mapper will be used.

Parameters
[in]strA byte string.
[in]pCharMapA character mapper.
Returns
None.

◆ Delete()

FX_STRSIZE CFX_WideString::Delete ( FX_STRSIZE  index,
FX_STRSIZE  count = 1 
)

Delete one or more wide characters starting from specific position.

Parameters
[in]indexSpecifies the zero-based index in the wide string for starting deleting.
[in]countCount of wide characters to be deleted.
Returns
The new length of the wide string.

◆ Empty()

void CFX_WideString::Empty ( )

Set this string to be empty.

Returns
None.

◆ Equal()

bool CFX_WideString::Equal ( const CFX_WideStringC str) const

Check if current string is equal to another.

This function os faster than CFX_WideString::Comparewhen only need to check whether two strings are equal.

Parameters
[in]strThe wide string to be compared.
Returns
true means equal, while false means not equal.

◆ Find() [1/2]

FX_STRSIZE CFX_WideString::Find ( FX_LPCWSTR  lpszSub,
FX_STRSIZE  start = 0 
) const

Find a sub-string, from specific position. Only first occurrence is found.

Parameters
[in]lpszSubThe sub-string to be found.
[in]startSpecifies the zero-based index of the starting position to do finding. Default value: 0.
Returns
The position of first occurrence in current string. -1 means not found.

◆ Find() [2/2]

FX_STRSIZE CFX_WideString::Find ( FX_WCHAR  ch,
FX_STRSIZE  start = 0 
) const

Find a character, from specific position. Only first occurrence is found.

Parameters
[in]chThe character to be found.
[in]startSpecifies the zero-based index of the starting position to do finding.Default value: 0.
Returns
The position of first occurrence in current string. -1 means not found.

◆ Format()

void CFX_WideString::Format ( FX_LPCWSTR  lpszFormat,
  ... 
)

Format a number of parameters into this wide string.

Parameters
[in]lpszFormatSpecifies a format-control string.
Returns
None.

◆ FormatV()

void CFX_WideString::FormatV ( FX_LPCWSTR  lpszFormat,
va_list  argList 
)

Format a number of parameters into this wide string. using va_list.

Parameters
[in]lpszFormatSpecifies a format-control string.
[in]argListVariable-argument lists.
Returns
None.
See also
CFX_WideString::Format

◆ FromLocal()

static CFX_WideString CFX_WideString::FromLocal ( const char *  str,
FX_STRSIZE  len = -1 
)
static

Create a wide string from system multi-byte charset.

Parameters
[in]stra multi-byte charset string.
[in]lenThe length in bytes of the multi-byte charset string. This can be -1 for zero terminated multi-byte charset string.
Returns
A wide string.

◆ FromUTF16BE()

static CFX_WideString CFX_WideString::FromUTF16BE ( const unsigned short *  str,
FX_STRSIZE  len = -1 
)
static

Create a wide string from UTF16BE encoded string.

Parameters
[in]strA UTF16BE encoded string.
[in]lenThe length in bytes of the UTF16BE encoded string. This can be -1 for zero terminated UTF16BE string.
Returns
A wide string.

◆ FromUTF16LE()

static CFX_WideString CFX_WideString::FromUTF16LE ( const unsigned short *  str,
FX_STRSIZE  len = -1 
)
static

Create a wide string from UTF16LE encoded string.

Parameters
[in]strA UTF16LE encoded string.
[in]lenThe length in bytes of the UTF16LE encoded string. This can be -1 for zero terminated UTF16LE string.
Returns
A wide string.

◆ FromUTF8()

static CFX_WideString CFX_WideString::FromUTF8 ( const char *  str,
FX_STRSIZE  len = -1 
)
static

Create a wide string from UTF-8 string (ASCII string compatible).

Parameters
[in]strA UTF8 string.
[in]lenThe length in bytes of the UTF8 string. This can be -1 for zero terminated UTF8 string.
Returns
A wide string.

◆ GetAt()

FX_WCHAR CFX_WideString::GetAt ( FX_STRSIZE  nIndex) const
inline

Retrieves a single wide character specified by an index number.

Parameters
[in]nIndexSpecifies the zero-based index in the wide string.
Returns
A single wide character.

◆ GetBuffer()

FX_LPWSTR CFX_WideString::GetBuffer ( FX_STRSIZE  len)

Get a buffer with specific number of characters allocated.

Parameters
[in]lenthe Length expected to get.


Returns
A wide character string pointer to the wide string.

◆ GetFloat()

FX_FLOAT CFX_WideString::GetFloat ( ) const

Convert to other data type.

Returns
A floating point number.

◆ GetInteger()

int CFX_WideString::GetInteger ( ) const

Convert to other data type.

Returns
A decimal number.

◆ GetLength()

FX_STRSIZE CFX_WideString::GetLength ( ) const
inline

Get number of characters, not bytes. Trailing zero not counted.

Returns
The number of characters.

◆ Insert()

FX_STRSIZE CFX_WideString::Insert ( FX_STRSIZE  index,
FX_WCHAR  ch 
)

Insert a wide character before specific position.

Parameters
[in]indexSpecifies the zero-based index in the wide string.
[in]chA single wide character.
Returns
The new length of the wide string.

◆ IsEmpty()

FX_BOOL CFX_WideString::IsEmpty ( ) const
inline

Check whether current string object is empty.

Returns
true means current string object is empty, while false means not.

◆ Left()

CFX_WideString CFX_WideString::Left ( FX_STRSIZE  count) const

Extracts the first (leftmost) count wide characters from this CFX_WideString object as a sub-string.

Parameters
[in]countThe count of wide characters expected to extract for the sub-string.
Returns
A CFX_WideString sub-string.

◆ LockBuffer()

FX_LPWSTR CFX_WideString::LockBuffer ( )

Lock and get the current string buffer, so the caller can modify the returned buffer. Caller can modified the returned buffer, and should call CFX_WideString::ReleaseBuffer after modification done.

Returns
A wide character string pointer to the wide string.

◆ MakeLower()

void CFX_WideString::MakeLower ( )

Change case of English letters to lower.

Returns
None.

◆ MakeUpper()

void CFX_WideString::MakeUpper ( )

Change case of English letters to upper.

Returns
None.

◆ Mid() [1/2]

CFX_WideString CFX_WideString::Mid ( FX_STRSIZE  first) const

Extracts a substring from this CFX_WideString object, starting at position nFirst (zero-based) to last.

Parameters
[in]firstSpecifies the zero-based index of the starting position in this CFX_WideString object.
Returns
A CFX_WideString sub-string.

◆ Mid() [2/2]

CFX_WideString CFX_WideString::Mid ( FX_STRSIZE  first,
FX_STRSIZE  count 
) const

Extracts a substring of count wide character from this CFX_WideString object, starting at position nFirst (zero-based) to last.

Parameters
[in]firstSpecifies the zero-based index of the starting position in this CFX_WideString object.
[in]countThe count of wide characters expected to extract for the sub-string.
Returns
A CFX_WideString sub-string.

◆ operator+=() [1/4]

const CFX_WideString& CFX_WideString::operator+= ( FX_LPCWSTR  str)

Concatenation(+=) operator overload. Concatenate a wide character string.

Parameters
[in]strThe wide character string.
Returns
A reference to current object itself.

◆ operator+=() [2/4]

const CFX_WideString& CFX_WideString::operator+= ( FX_WCHAR  ch)

Concatenation(+=) operator overload. Concatenate a single wide character.

Parameters
[in]chThe single wide character.
Returns
A reference to current object itself.

◆ operator+=() [3/4]

const CFX_WideString& CFX_WideString::operator+= ( const CFX_WideString str)

Concatenation(+=) operator overload. Concatenate a wide string.

Parameters
[in]strThe input wide string.
Returns
A reference to current object itself.

◆ operator+=() [4/4]

const CFX_WideString& CFX_WideString::operator+= ( const CFX_WideStringC str)

Concatenation(+=) operator overload. Concatenate a constant wide string.

Parameters
[in]strThe input wide string.
Returns
A reference to current object itself.

◆ operator=() [1/3]

const CFX_WideString& CFX_WideString::operator= ( FX_LPCWSTR  str)

Assignment(=) operator overload. From a wide character string.

Parameters
[in]strThe wide character string.
Returns
A reference to current object itself.

◆ operator=() [2/3]

const CFX_WideString& CFX_WideString::operator= ( const CFX_WideString stringSrc)

Assignment(=) operator overload. From a wide string.

Parameters
[in]stringSrcThe Input wide string.
Returns
A reference to current object itself.

◆ operator=() [3/3]

const CFX_WideString& CFX_WideString::operator= ( const CFX_WideStringC stringSrc)

Assignment(=) operator overload. From a const wide string.

Parameters
[in]stringSrcThe Input wide string.
Returns
A reference to current object itself.

◆ operator[]()

FX_WCHAR CFX_WideString::operator[] ( FX_STRSIZE  nIndex) const
inline

Subscript([]) operator overload. It retrieves a wide character specified by the zero-based index in nIndex.

Parameters
[in]nIndexSpecifies the zero-based index in the wide string.
Returns
A single wide character.

◆ ReleaseBuffer()

void CFX_WideString::ReleaseBuffer ( FX_STRSIZE  len = -1)

Release the buffer fetched by function CFX_WideString::GetBuffer or CFX_WideString::LockBuffer, and set the length of modified string.

Parameters
[in]lenLength expected to release to. -1 means that current string is assumed to be a zero-terminated string.
Returns
None.

◆ Remove()

FX_STRSIZE CFX_WideString::Remove ( FX_WCHAR  ch)

Remove all occurrence of a particular character.

Parameters
[in]chSpecified the character to be removed.
Returns
The number of characters removed.

◆ Replace()

FX_STRSIZE CFX_WideString::Replace ( FX_LPCWSTR  lpszOld,
FX_LPCWSTR  lpszNew 
)

Replace all patterns in the string with a new sub-string.

Parameters
[in]lpszOldSpecified the string to be matched and replaced in the wide string.
[in]lpszNewSpecified the string to replace.
Returns
The number of replaced patterns.

◆ Reserve()

void CFX_WideString::Reserve ( FX_STRSIZE  len)

Reserve a buffer that can hold specific number of characters.

Parameters
[in]lenthe Length expected to reserve.
Returns
None.
See also
CFX_ByteString::Reserve(FX_STRSIZE)

◆ Right()

CFX_WideString CFX_WideString::Right ( FX_STRSIZE  count) const

Extracts the last (rightmost) count wide characters from this CFX_WideString object as a sub-string.

Parameters
[in]countThe count of wide characters expected to extract for the sub-string.
Returns
A CFX_WideString sub-string.

◆ SetAt()

void CFX_WideString::SetAt ( FX_STRSIZE  nIndex,
FX_WCHAR  ch 
)

Overwrites a single wide character specified by an index number.

Parameters
[in]nIndexSpecifies the zero-based index in the wide string.
[in]chA single wide character.
Returns
None.

◆ TrimLeft() [1/3]

void CFX_WideString::TrimLeft ( )

Trim white spaces from the left side of the wide string.

Returns
None.

◆ TrimLeft() [2/3]

void CFX_WideString::TrimLeft ( FX_WCHAR  chTarget)

Trim continuous occurrences of specified character from left side of the wide string.

Parameters
[in]chTargetThe specified character.
Returns
None.

◆ TrimLeft() [3/3]

void CFX_WideString::TrimLeft ( FX_LPCWSTR  lpszTargets)

Trim continuous occurrences of specified characters from left side of the wide string.

Parameters
[in]lpszTargetsThe specified characters.
Returns
None.

◆ TrimRight() [1/3]

void CFX_WideString::TrimRight ( )

Trim white spaces from the right side of the wide string.

Returns
None.

◆ TrimRight() [2/3]

void CFX_WideString::TrimRight ( FX_WCHAR  chTarget)

Trim continuous occurrences of specified character from right side of the wide string.

Parameters
[in]chTargetThe specified character.
Returns
None.

◆ TrimRight() [3/3]

void CFX_WideString::TrimRight ( FX_LPCWSTR  lpszTargets)

Trim continuous occurrences of specified characters from right side of the wide string.

Parameters
[in]lpszTargetsThe specified characters.
Returns
None.

◆ UTF16LE_Encode()

CFX_ByteString CFX_WideString::UTF16LE_Encode ( FX_BOOL  bTerminate = true) const

Do UTF16LE encoding.

Parameters
[in]bTerminate
Returns
A byte string which represents UTF-16LE encoded memory block.

◆ UTF8Encode()

CFX_ByteString CFX_WideString::UTF8Encode ( ) const

Do UTF8 encoding.

Returns
A byte string.

◆ WStringLength()

static FX_STRSIZE CFX_WideString::WStringLength ( const unsigned short *  str)
static

Length of string.

Parameters
[in]strA string.
Returns
The length of string.