Loading...
Searching...
No Matches
pdftron::UString Class Reference

`#include <UString.h>`

## Public Types
enum | TextEncoding { e_ascii_enc = 0 , e_pdfdoc_enc , e_winansii_enc , e_pdftext_enc , e_utf16be_enc , e_utf8 , e_no_enc }

## Public Member Functions
| UString ()
| UString (const UString &str)
| UString (Unicode value)
| UString (const Unicode *value)
| UString (const Unicode *value, int length)
| UString (const char *buf, int buf_sz=-1, TextEncoding enc=e_utf8)
| UString (const std::string &str, TextEncoding enc=e_utf8)
| UString (const std::wstring &value)
| ~UString ()
UString & | operator= (const UString &str)
UString & | operator= (const char *ascii_str)
UString & | Assign (const UString &uni)
UString & | Assign (const Unicode *uni, int buf_sz=-1)
UString & | Assign2 (const char *buf, int buf_sz=-1, TextEncoding enc=e_utf8)
UString & | operator+= (const UString &str)
UString | Concat (const UString &str) const
int | GetLength () const
bool | Empty () const
const Unicode * | GetBuffer () const
int | Compare (const UString &str, int max_length=-1) const
UString | SubStr (int off=0, int count=-1) const
Unicode | GetAt (int idx) const
void | PushBack (Unicode ch)
void | Resize (int count, Unicode ch=' ')
void | ToUpper ()
void | ToLower ()
void | Reserve (int count)
const Unicode * | CStr () const
bool | IsInAscii () const
int | ConvertToAscii (char *in_out_buf, int buf_sz, bool null_term) const
int | ConvertToUtf8 (char *in_out_buf, int buf_sz, bool null_term) const
int | ConvertToUtf32 (UInt32 *in_out_buf, int buf_sz, bool null_term) const
std::wstring | ConvertToNativeWString () const
std::string | ConvertToAscii () const
std::string | ConvertToUtf8 () const
std::basic_string< UInt32 > | ConvertToUtf32 () const
int | ConvertToPDFText (char *in_out_buf, int buf_sz, bool force_unicode=false) const

## Friends
UString | operator+ (const UString &str1, const UString &str2)
bool | operator== (const UString &rStr1, const UString &rStr2)
bool | operator== (const UString &rStr1, const Unicode *pStr2)
bool | operator== (const Unicode *pStr1, const UString &rStr2)
bool | operator!= (const UString &rStr1, const UString &rStr2)
bool | operator!= (const UString &rStr1, const Unicode *pStr2)
bool | operator!= (const Unicode *pStr1, const UString &rStr2)
bool | operator< (const UString &rStr1, const UString &rStr2)
bool | operator> (const UString &rStr1, const UString &rStr2)
bool | operator<= (const UString &rStr1, const UString &rStr2)
bool | operator>= (const UString &rStr1, const UString &rStr2)

## Detailed Description

Represents text as a series of Unicode characters.

Note
  Under .NET and Java environments the UString is mapped to built-in String types, so it is usually not necessary to directly use UString.
  UString-s are usually referred to as strings, but they should not be confused with the null-terminated C-strings.

Definition at line 27 of file UString.h.

## Member Enumeration Documentation

## ◆ TextEncoding

enum pdftron::UString::TextEncoding

A descriptor for the 8-bit character buffer encoding

Enumerator
e_ascii_enc | ASCII encoded text.
e_pdfdoc_enc | PDFDocEncoding. See Appendix 'D' in PDF Reference.
e_winansii_enc | WinAnsiiEncoding. See Appendix 'D' in PDF Reference.
e_pdftext_enc | Text represented as PDF Text (section 3.8.1 'Text Strings' in PDF Reference).
e_utf16be_enc | UTF-16BE (big-endian) encoding scheme.
e_utf8 | UTF-8 encoding scheme.
e_no_enc | No specific encoding.

Definition at line 68 of file UString.h.

## Constructor & Destructor Documentation

## ◆ UString() [1/8]

pdftron::UString::UString | ( |  | ) |

Create an empty string.

## ◆ UString() [2/8]

pdftron::UString::UString | ( | const UString & | str | ) |

Create a new string from UString.

Parameters

  str | a UString.

## ◆ UString() [3/8]

pdftron::UString::UString | ( | Unicode | value | ) |
| explicit

Create a new string from a single Unicode character.

Parameters

  value | a Unicode character.

## ◆ UString() [4/8]

pdftron::UString::UString | ( | const Unicode * | value | ) |

Create a new string from a Unicode character buffer array.

Parameters

  value | - a NULL-terminated Unicode character array.

## ◆ UString() [5/8]

pdftron::UString::UString | ( | const Unicode * | value,
|  | int | length )

Create a new string from a Unicode character buffer array.

Parameters

  value | a Unicode character array.
  length | the number of character which should be copied. The character array length must be greater or equal than this value.

## ◆ UString() [6/8]

pdftron::UString::UString | ( | const char * | buf,
|  | int | buf_sz = -1,
|  | TextEncoding | enc = e_utf8 )

Create a new string from a 8-bit character buffer array.

Parameters

  buf | An 8-bit character array.
  buf_sz | the number of character which should be converted. The 8-bit character array length must be greater or equal than this value. A negative number means that the string is null terminated.
  enc | the text encoding from which the 8-bit character sequence should be converted.

## ◆ UString() [7/8]

pdftron::UString::UString | ( | const std::string & | str,
|  | TextEncoding | enc = e_utf8 )

Create a new string from a 8-bit std::string

Parameters

  str | An 8-bit std::string.
  enc | the text encoding from which the 8-bit character sequence should be converted.

## ◆ UString() [8/8]

pdftron::UString::UString | ( | const std::wstring & | value | ) |

Create a new string from a wide string native to the current compiler.

Parameters

  value | a string which will be converted to a new UString.

## ◆ ~UString()

pdftron::UString::~UString | ( |  | ) |

Destructor

## Member Function Documentation

## ◆ Assign() [1/2]

UString & pdftron::UString::Assign | ( | const Unicode * | uni,
|  | int | buf_sz = -1 )

## ◆ Assign() [2/2]

UString & pdftron::UString::Assign | ( | const UString & | uni | ) |

Assigns new character values to the contents of a string.

Returns
  A reference to the string object that is being assigned new characters.

## ◆ Assign2()

UString & pdftron::UString::Assign2 | ( | const char * | buf,
|  | int | buf_sz = -1,
|  | TextEncoding | enc = e_utf8 )

## ◆ Compare()

int pdftron::UString::Compare | ( | const UString & | str,
|  | int | max_length = -1 ) const

Compares two strings.

    The comparison is based on the numeric value of each character in
    the strings and return a value indicating their relationship.
    This function can't be used for language specific sorting.

Parameters

  str | the object to be compared.
  max_length | (optional parameter) the maximum count of characters to be compared. Negative number means that the entire string should be compared.

Returns
  0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument

## ◆ Concat()

UString pdftron::UString::Concat | ( | const UString & | str | ) | const

Concatenates the specified string to the end of this string.

Parameters

  str | the string that is concatenated to the end of this string.

Returns
  a string that represents the concatenation of this string followed by the string argument.

## ◆ ConvertToAscii() [1/2]

std::string pdftron::UString::ConvertToAscii | ( |  | ) | const

Convert to ASCII std::string.

Note
  A C++ utility method for quick and simple conversion to ASCII std::string.

## ◆ ConvertToAscii() [2/2]

int pdftron::UString::ConvertToAscii | ( | char * | in_out_buf,
|  | int | buf_sz,
|  | bool | null_term ) const

Convert to ASCII C string.

Parameters

  in_out_buf | if NULL the function returns the number of bytes required to store the ASCII string. If in_out_buf is not NULL the function will fill out the buffer with ASCII converted string.
  buf_sz | Size of the in_out_buf buffer, in bytes. If the length of the converted string exceeds the size that the buf_sz parameter specifies, the string is truncated to buf_sz-1 characters.
  null_term | to null terminate the converted string set this parameter to true.

Returns
  the number of bytes written in the buffer. If the buffer is too small to hold the converted string, the string is truncated to buf_sz-1.

## ◆ ConvertToNativeWString()

std::wstring pdftron::UString::ConvertToNativeWString | ( |  | ) | const

Convert to std::wstring that is in the native representation of the current platform.

## ◆ ConvertToPDFText()

int pdftron::UString::ConvertToPDFText | ( | char * | in_out_buf,
|  | int | buf_sz,
|  | bool | force_unicode = false ) const

Convert the Unicode string to 'PDF Text' string.

PDF Text Strings are not used to represent page content, however they are used in text annotations, bookmark names, article names, document information etc. These strings are encoded in either PDFDocEncoding or Unicode character encoding. For more information on PDF Text Strings, please refer to section 3.8.1 'Text Strings' in PDF Reference.

Parameters

  in_out_buf | if NULL the function returns the number of bytes required to store the converted string. If in_out_buf is not NULL the function will fill out the buffer with PDF Text data.
  buf_sz | Size of the in_out_buf buffer, in bytes. If the length of the converted string exceeds the size that the buf_sz parameter specifies, the string is truncated to buf_sz characters.
  force_unicode | (optional) If true the string will always be converted as Unicode. If false (which is default) the function will first attempt to encode the sting using PDFDocEncoding. If the string can't be mapped to PDFDocEncoding it will be converted as Unicode.

Returns
  the number of bytes written in the buffer. If the buffer is too small to hold the converted string, the string is truncated to buf_sz.

## ◆ ConvertToUtf32() [1/2]

std::basic_string< UInt32 > pdftron::UString::ConvertToUtf32 | ( |  | ) | const

Convert to UTF32 encoded std::string.

## ◆ ConvertToUtf32() [2/2]

int pdftron::UString::ConvertToUtf32 | ( | UInt32 * | in_out_buf,
|  | int | buf_sz,
|  | bool | null_term ) const

Convert to UTF32 C string.

Parameters

  in_out_buf | if NULL the function returns the number of bytes required to store the UTF8 string. If in_out_buf is not NULL the function will fill out the buffer with UTF32 converted string.
  buf_sz | Size of the in_out_buf buffer, in bytes. If the length of the converted string exceeds the size that the buf_sz parameter specifies, the string is truncated to buf_sz-1 characters.
  null_term | to null terminate the converted string set this parameter to true.

Returns
  the number of bytes written in the buffer (including null terminator if specified). If the buffer is too small to hold the converted string, the string is truncated to buf_sz-1.

## ◆ ConvertToUtf8() [1/2]

std::string pdftron::UString::ConvertToUtf8 | ( |  | ) | const

Convert to UTF8 encoded std::string.

Note
  A C++ utility method for quick and simple conversion to UTF8 std::string.

## ◆ ConvertToUtf8() [2/2]

int pdftron::UString::ConvertToUtf8 | ( | char * | in_out_buf,
|  | int | buf_sz,
|  | bool | null_term ) const

Convert to UTF8 C string.

Parameters

  in_out_buf | if NULL the function returns the number of bytes required to store the UTF8 string. If in_out_buf is not NULL the function will fill out the buffer with UTF8 converted string.
  buf_sz | Size of the in_out_buf buffer, in bytes. If the length of the converted string exceeds the size that the buf_sz parameter specifies, the string is truncated to buf_sz-1 characters.
  null_term | to null terminate the converted string set this parameter to true.

Returns
  the number of bytes written in the buffer (including null terminator if specified). If the buffer is too small to hold the converted string, the string is truncated to buf_sz-1.

## ◆ CStr()

const Unicode * pdftron::UString::CStr | ( |  | ) | const

Returns the contents of a UString as a C-style, null-terminated Unicode string.

Note
  same as string::c_str() method in standard C++ library. All caveats apply here.

## ◆ Empty()

bool pdftron::UString::Empty | ( |  | ) | const

Tests whether the string contains any characters.

Returns
  true is the string is empty, false otherwise.

## ◆ GetAt()

Unicode pdftron::UString::GetAt | ( | int | idx | ) | const

Provides a reference to the character with a specified index in a string.

Parameters

  idx | The index of the position of the element to be referenced

Returns
  A reference to the character of the string at the position specified by the parameter index.

The first element of the string has an index of zero and the following elements are indexed consecutively by the positive integers.

## ◆ GetBuffer()

const Unicode * pdftron::UString::GetBuffer | ( |  | ) | const

Returns a pointer to the Unicode character buffer from this string. The string is not necessarily NULL terminated.

Returns
  a pointer to the Unicode characters buffer from this object. For an empty string return a non-null pointer that cannot be dereferenced.

## ◆ GetLength()

int pdftron::UString::GetLength | ( |  | ) | const

Returns the length of this string. The length is equal to the number of Unicode characters in this string.

Returns
  the length of the sequence of characters represented by this object.

## ◆ IsInAscii()

bool pdftron::UString::IsInAscii | ( |  | ) | const

Returns
  true if all characters in the string are ASCII, false otherwise.

## ◆ operator+=()

UString & pdftron::UString::operator+= | ( | const UString & | str | ) |

Append a string to this string.

Parameters

  str | a UString to append to this string.

## ◆ operator=() [1/2]

UString & pdftron::UString::operator= | ( | const char * | ascii_str | ) |

## ◆ operator=() [2/2]

UString & pdftron::UString::operator= | ( | const UString & | str | ) |

Assign a new string.

Parameters

  str | a UString.

## ◆ PushBack()

void pdftron::UString::PushBack | ( | Unicode | ch | ) |

Adds an element to the end of the string.

Parameters

  ch | The character to be added to the end of the string.

## ◆ Reserve()

void pdftron::UString::Reserve | ( | int | count | ) |

Sets the capacity of the string to a number at least as great as a specified number.

Parameters

  count | The number of characters for which memory is being reserved.

## ◆ Resize()

void pdftron::UString::Resize | ( | int | count,
|  | Unicode | ch = ' ' )

Specifies a new size for a string, appending or erasing elements as required.

Parameters

  count | The new size of the string.
  ch | The value that appended characters are initialized with if additional elements are required.

## ◆ SubStr()

UString pdftron::UString::SubStr | ( | int | off = 0,
|  | int | count = -1 ) const

Copies a substring of at most some number of characters from a string beginning from a specified position.

Parameters

  off | An index locating the element at the position from which the copy of the string is made, with a default value of 0.
  count | The number of characters that are to be copied if they are present. -1 means copy the entire string.

Returns
  A substring object that is a copy of elements of the string operand beginning at the position specified by the first argument.

## ◆ ToLower()

void pdftron::UString::ToLower | ( |  | ) |

Converts all characters in a string to lowercase.

## ◆ ToUpper()

void pdftron::UString::ToUpper | ( |  | ) |

Converts all characters in a string to uppercase.

## Friends And Related Symbol Documentation

## ◆ operator!= [1/3]

bool operator!= | ( | const Unicode * | pStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 369 of file UString.h.

## ◆ operator!= [2/3]

bool operator!= | ( | const UString & | rStr1,
|  | const Unicode * | pStr2 )
| friend

Definition at line 368 of file UString.h.

## ◆ operator!= [3/3]

bool operator!= | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 367 of file UString.h.

## ◆ operator+

UString operator+ | ( | const UString & | str1,
|  | const UString & | str2 )
| friend

Definition at line 141 of file UString.h.

## ◆ operator<

bool operator< | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 370 of file UString.h.

## ◆ operator<=

bool operator<= | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 372 of file UString.h.

## ◆ operator== [1/3]

bool operator== | ( | const Unicode * | pStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 366 of file UString.h.

## ◆ operator== [2/3]

bool operator== | ( | const UString & | rStr1,
|  | const Unicode * | pStr2 )
| friend

Definition at line 365 of file UString.h.

## ◆ operator== [3/3]

bool operator== | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 364 of file UString.h.

## ◆ operator>

bool operator> | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 371 of file UString.h.

## ◆ operator>=

bool operator>= | ( | const UString & | rStr1,
|  | const UString & | rStr2 )
| friend

Definition at line 373 of file UString.h.

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

- Common/UString.h