All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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 ()
 
UStringoperator= (const UString &str)
 
UStringoperator= (const char *ascii_str)
 
UStringAssign (const UString &uni)
 
UStringAssign (const Unicode *uni, int buf_sz=-1)
 
UStringAssign2 (const char *buf, int buf_sz=-1, TextEncoding enc=e_utf8)
 
UStringoperator+= (const UString &str)
 
UString Concat (const UString &str) const
 
int GetLength () const
 
bool Empty () const
 
const UnicodeGetBuffer () 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 UnicodeCStr () 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 *out_buf, int buf_sz, bool null_term) const
 
std::wstring ConvertToNativeWString () const
 
std::string ConvertToAscii () const
 
std::string ConvertToUtf8 () const
 
std::basic_string< UInt32ConvertToUtf32 () 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 26 of file UString.h.

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.

Definition at line 67 of file UString.h.

Constructor & Destructor Documentation

pdftron::UString::UString ( )

Create an empty string.

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

Create a new string from UString.

Parameters
stra UString.
pdftron::UString::UString ( Unicode  value)
explicit

Create a new string from a single Unicode character.

Parameters
valuea 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
valuea Unicode character array.
lengththe 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_utf8 
)

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

Parameters
valueAn 8-bit character array.
buf_szthe 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.
encodingthe text encoding from which the 8-bit character sequence should be converted.
pdftron::UString::UString ( const std::string &  str,
TextEncoding  enc = e_utf8 
)

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

Parameters
valueAn 8-bit character array.
encodingthe text encoding from which the 8-bit character sequence should be converted.
pdftron::UString::UString ( const std::wstring &  value)

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

Parameters
valuea string which will be converted to a new UString.
pdftron::UString::~UString ( )

Destructor

Member Function Documentation

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_utf8 
)
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
strthe 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
UString pdftron::UString::Concat ( const UString str) const

Concatenates the specified string to the end of this string.

Parameters
strthe 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::ConvertToAscii ( char *  in_out_buf,
int  buf_sz,
bool  null_term 
) const

Convert to ASCII C string.

Parameters
in_out_bufif 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_szSize 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_termto 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.
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::wstring pdftron::UString::ConvertToNativeWString ( ) const

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

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_bufif 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_szSize 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.
int pdftron::UString::ConvertToUtf32 ( UInt32 out_buf,
int  buf_sz,
bool  null_term 
) const

Convert to UTF32 C string.

Parameters
in_out_bufif 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_szSize 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_termto 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::basic_string<UInt32> pdftron::UString::ConvertToUtf32 ( ) const

Convert to UTF32 encoded std::string.

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

Convert to UTF8 C string.

Parameters
in_out_bufif 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_szSize 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_termto 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::ConvertToUtf8 ( ) const

Convert to UTF8 encoded std::string.

Note
A C++ utility method for quick and simple conversion to UTF8 std::string.
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.
bool pdftron::UString::Empty ( ) const

Tests whether the string contains any characters.

Returns
true is the string is empty, false otherwise.
Unicode pdftron::UString::GetAt ( int  idx) const

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

Parameters
idxThe 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.

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::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::IsInAscii ( ) const
Returns
true if all characters in the string are ASCII, false otherwise.
UString& pdftron::UString::operator+= ( const UString str)

Append a string to this string.

Parameters
stra UString to append to this string.
UString& pdftron::UString::operator= ( const UString str)

Assign a new string.

Parameters
stra UString.
UString& pdftron::UString::operator= ( const char *  ascii_str)
void pdftron::UString::PushBack ( Unicode  ch)

Adds an element to the end of the string.

Parameters
chThe character to be added to the end of the string.
void pdftron::UString::Reserve ( int  count)

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

Parameters
countThe number of characters for which memory is being reserved.
void pdftron::UString::Resize ( int  count,
Unicode  ch = ' ' 
)

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

Parameters
countThe new size of the string.
chThe value that appended characters are initialized with if additional elements are required.
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
offAn index locating the element at the position from which the copy of the string is made, with a default value of 0.
countThe 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.
void pdftron::UString::ToLower ( )

Converts all characters in a string to lowercase.

void pdftron::UString::ToUpper ( )

Converts all characters in a string to uppercase.

Friends And Related Function Documentation

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

Definition at line 366 of file UString.h.

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

Definition at line 367 of file UString.h.

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

Definition at line 368 of file UString.h.

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

Definition at line 140 of file UString.h.

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

Definition at line 369 of file UString.h.

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

Definition at line 371 of file UString.h.

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

Definition at line 363 of file UString.h.

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

Definition at line 364 of file UString.h.

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

Definition at line 365 of file UString.h.

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

Definition at line 370 of file UString.h.

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

Definition at line 372 of file UString.h.


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