pdftron::UString Class Reference

Represents text as a series of Unicode characters. More...

#include <UString.h>

List of all members.

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
}
 A descriptor for the 8-bit character buffer encoding. More...

Public Member Functions

 UString ()
 Create an empty string.
 UString (const UString &str)
 Create a new string from UString.
 UString (Unicode value)
 Create a new string from a single Unicode character.
 UString (const Unicode *value)
 Create a new string from a Unicode character buffer array.
 UString (const Unicode *value, int length)
 Create a new string from a Unicode character buffer array.
 UString (const char *buf, int buf_sz=-1, TextEncoding enc=e_ascii_enc)
 Create a new string from a 8-bit character buffer array.
 ~UString ()
 Destructor.
UStringoperator= (const UString &str)
 Assign a new string.
UStringoperator= (const char *ascii_str)
UStringAssign (const UString &uni)
 Assigns new character values to the contents of a string.
UStringAssign (const Unicode *uni, int buf_sz=-1)
UStringAssign2 (const char *buf, int buf_sz=-1, TextEncoding enc=e_ascii_enc)
UStringoperator+= (const UString &str)
 Append a string to this string.
UString Concat (const UString &str) const
 Concatenates the specified string to the end of this string.
int GetLength () const
 Returns the length of this string.
bool Empty () const
 Tests whether the string contains any characters.
const UnicodeGetBuffer () const
 Returns a pointer to the Unicode character buffer from this string.
int Compare (const UString &str, int max_length=-1) const
 Compares two strings.
int Compare (const char *ascii_string, int max_length=-1) const
 Compares two strings.
UString SubStr (int off=0, int count=-1) const
Unicode GetAt (int idx) const
 Provides a reference to the character with a specified index in a string.
void PushBack (Unicode ch)
 Adds an element to the end of the string.
void Resize (int count, Unicode ch= ' ')
 Specifies a new size for a string, appending or erasing elements as required.
void ToUpper ()
 Converts all characters in a string to uppercase.
void ToLower ()
 Converts all characters in a string to lowercase.
void Reserve (int count)
 Sets the capacity of the string to a number at least as great as a specified number.
const UnicodeCStr () const
 Converts the contents of a string as a C-style, null-terminated string.
bool IsInAscii () const
int ConvertToAscii (char *in_out_buf, int buf_sz, bool null_term) const
 Convert to ASCII C string.
int ConvertToUtf8 (char *in_out_buf, int buf_sz, bool null_term) const
 Convert to UTF8 C string.
std::string ConvertToAscii () const
 Convert to ASCII std::string.
std::string ConvertToUtf8 () const
 Convert to UTF8 encoded std::string.
int ConvertToPDFText (char *in_out_buf, int buf_sz, bool force_unicode=false) const
 Convert the Unicode string to 'PDF Text' string.

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.


Member Enumeration Documentation

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.


Constructor & Destructor Documentation

pdftron::UString::UString (  ) 

Create an empty string.

pdftron::UString::UString ( const UString str  ) 

Create a new string from UString.

Parameters:
str a UString.

pdftron::UString::UString ( Unicode  value  )  [explicit]

Create a new string from a single Unicode character.

Parameters:
value a Unicode character.

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

Create a new string from a Unicode character buffer array.

Parameters:
value - a NULL-terminated Unicode character array.

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.

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

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

Parameters:
value 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.
encoding the text encoding from which the 8-bit character sequence should be converted.

pdftron::UString::~UString (  ) 

Destructor.


Member Function Documentation

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

Assign a new string.

Parameters:
str a UString.

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

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.

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

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

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

Append a string to this string.

Parameters:
str a UString to append to this string.

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.

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.

bool pdftron::UString::Empty (  )  const

Tests whether the string contains any characters.

Returns:
true is the string is empty, false otherwise.

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.

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

int pdftron::UString::Compare ( const char *  ascii_string,
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. Since this method is optimized for performance, the ASCII character values are not converted in any way. The caller has to make sure that all ASCII characters are in the allowed range between 0 and 127. The ASCII string must be NULL-terminated. This function can't be used for language specific sorting.

Parameters:
ascii_string the 8-bit ASCII character string 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

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

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, so that a string of length n has an nth element at index n–1.

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.

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.

void pdftron::UString::ToUpper (  ) 

Converts all characters in a string to uppercase.

void pdftron::UString::ToLower (  ) 

Converts all characters in a string to lowercase.

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.

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

Converts the contents of a string as a C-style, null-terminated string.

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

bool pdftron::UString::IsInAscii (  )  const

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

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.

Referenced by pdftron::operator<<().

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.

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.

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.

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.


Friends And Related Function Documentation

UString operator+ ( const UString str1,
const UString str2 
) [friend]

bool operator== ( const UString rStr1,
const UString rStr2 
) [friend]

bool operator== ( const UString rStr1,
const Unicode pStr2 
) [friend]

bool operator== ( const Unicode pStr1,
const UString rStr2 
) [friend]

bool operator!= ( const UString rStr1,
const UString rStr2 
) [friend]

bool operator!= ( const UString rStr1,
const Unicode pStr2 
) [friend]

bool operator!= ( const Unicode pStr1,
const UString rStr2 
) [friend]

bool operator< ( const UString rStr1,
const UString rStr2 
) [friend]

bool operator> ( const UString rStr1,
const UString rStr2 
) [friend]

bool operator<= ( const UString rStr1,
const UString rStr2 
) [friend]

bool operator>= ( const UString rStr1,
const UString rStr2 
) [friend]


© 2002-2010 PDFTron Systems Inc.