#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 26 of file UString.h.

Member Enumeration Documentation

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 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

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_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.

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.

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.

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

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

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::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.

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_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.

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.

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_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::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

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.

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

str	a UString to append to this string.

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

Assign a new string.

Parameters

str	a 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

ch	The 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

count The 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

count	The new size of the string.
ch	The 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

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.

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:

Common/UString.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation