PoDoFo::PdfString Class Reference

#include <PdfString.h>

Inheritance diagram for PoDoFo::PdfString:

PoDoFo::PdfDataType

List of all members.

Public Member Functions

 PdfString ()
 PdfString (const std::string &sString, const PdfEncoding *const pEncoding=NULL)
 PdfString (const char *pszString, const PdfEncoding *const pEncoding=NULL)
 PdfString (const wchar_t *pszString)
 PdfString (const char *pszString, long lLen, bool bHex=false, const PdfEncoding *const pEncoding=NULL)
 PdfString (const pdf_utf8 *pszStringUtf8)
 PdfString (const pdf_utf16be *pszStringUtf16)
 PdfString (const pdf_utf8 *pszStringUtf8, long lLen)
 PdfString (const pdf_utf16be *pszStringUtf16, long lLen)
 PdfString (const PdfString &rhs)
void SetHexData (const char *pszHex, long lLen=-1, PdfEncrypt *pEncrypt=NULL)
bool IsValid () const
bool IsHex () const
bool IsUnicode () const
const char * GetString () const
const pdf_utf16be * GetUnicode () const
const std::string & GetStringUtf8 () const
long GetLength () const
long GetUnicodeLength () const
long GetCharacterLength () const
void Write (PdfOutputDevice *pDevice, const PdfEncrypt *pEncrypt=NULL) const
const PdfStringoperator= (const PdfString &rhs)
bool operator> (const PdfString &rhs) const
bool operator< (const PdfString &rhs) const
bool operator== (const PdfString &rhs) const
bool operator!= (const PdfString &rhs) const
PdfString ToUnicode () const


Detailed Description

A string that can be written to a PDF document. If it contains binary data it is automatically converted into a hex string, otherwise a normal PDF string is written to the document.

PdfStrings representing text are either in PDFDocEncoding (ISO Latin1) encoded or UTF-16BE encoded.

PoDoFo contains methods to convert between these encodings. For convinience conversion to UTF-8 is possible to. Please not that strings are always stored as UTF-16BE or ISO Latin1 (PdfDocEncoding) in the PDF file.

UTF-16BE strings have to start with the byts 0xFE 0xFF to be recognized by PoDoFo as unicode strings.

PdfStrings is an implicitly shared class. As a reason it is very fast to copy PdfString objects.

The internal string buffer is guaranteed to be always terminated by 2 zeros.


Constructor & Destructor Documentation

PoDoFo::PdfString::PdfString (  ) 

Create an empty and invalid string

PoDoFo::PdfString::PdfString ( const std::string &  sString,
const PdfEncoding *const   pEncoding = NULL 
)

Construct a new PdfString from a std::string. The input string will be copied. If the first to bytes of the string are 0xFE and 0xFF this string is treated as UTF-16BE encoded unicode string.

Parameters:
sString the string to copy
pEncoding the encoding of this string, if it is no unicode string. This is ignored for unicode strings. If NULL PdfDocEncoding will be used as a default.

PoDoFo::PdfString::PdfString ( const char *  pszString,
const PdfEncoding *const   pEncoding = NULL 
)

Construct a new PdfString from a 0 terminated string. The input string will be copied.

Parameters:
pszString the string to copy
pEncoding the encoding of this string, if it is no unicode string. This is ignored for unicode strings. If NULL PdfDocEncoding will be used as a default.

PoDoFo::PdfString::PdfString ( const wchar_t *  pszString  ) 

Construct a new PdfString from a 0 terminated string. The input string will be copied.

Parameters:
pszString the string to copy

PoDoFo::PdfString::PdfString ( const char *  pszString,
long  lLen,
bool  bHex = false,
const PdfEncoding *const   pEncoding = NULL 
)

Construct a new PdfString from a string. The input string will be copied. If the first to bytes of the string are 0xFE and 0xFF this string is treated as UTF-16BE encoded unicode string.

Parameters:
pszString the string to copy
lLen length of the string data to encode
bHex if true the data will be hex encoded during writeout of the string and IsHex() will return true.
pEncoding the encoding of this string, if it is no unicode string. This is ignored for unicode strings. If NULL PdfDocEncoding will be used as a default.

PoDoFo::PdfString::PdfString ( const pdf_utf8 *  pszStringUtf8  ) 

Construct a new PdfString from an UTF-8 encoded string.

The string is converted to UTF-16BE internally.

Parameters:
pszStringUtf8 a UTF-8 encoded string.

PoDoFo::PdfString::PdfString ( const pdf_utf16be *  pszStringUtf16  ) 

Construct a new PdfString from an UTF-16be encoded zero terminated string.

Parameters:
pszStringUtf16 a UTF-16BE encoded string.

PoDoFo::PdfString::PdfString ( const pdf_utf8 *  pszStringUtf8,
long  lLen 
)

Construct a new PdfString from an UTF-8 encoded string.

The string is converted to UTF-16BE internally.

Parameters:
pszStringUtf8 a UTF-8 encoded string.
lLen number of bytes to convert

PoDoFo::PdfString::PdfString ( const pdf_utf16be *  pszStringUtf16,
long  lLen 
)

Construct a new PdfString from an UTF-16be encoded zero terminated string.

Parameters:
pszStringUtf16 a UTF-16BE encoded string.
lLen number of words to convert

PoDoFo::PdfString::PdfString ( const PdfString rhs  ) 

Copy an existing PdfString

Parameters:
rhs another PdfString to copy


Member Function Documentation

long PoDoFo::PdfString::GetCharacterLength (  )  const [inline]

Get the number of characters in the string.

This function returns the correct number of characters in the string for unicode and ansi strings. Always use this method if you want to know the number of characters in the string as GetLength() will returns the number of bytes used for unicode strings!

the number of characters in the string

long PoDoFo::PdfString::GetLength (  )  const [inline]

The length of the string data returned by GetString() in bytes not including terminating zeros.

Returns:
the length of the string.
See also:
GetCharacterLength to determine the number of characters in the string

const char * PoDoFo::PdfString::GetString (  )  const [inline]

The contents of the strings can be read by this function.

The returned data is never hex encoded may contain 0 bytes.

if IsUnicode() returns true, the return value points to a UTF-16BE string buffer with Length() characters. Better use GetUnicode() in this case.

Returns:
the strings contents which is guaranteed to be zero terminated but might also contain 0 bytes in the string.
See also:
IsHex

IsUnicode

Length

const std::string & PoDoFo::PdfString::GetStringUtf8 (  )  const [inline]

The contents of the string as UTF8 string.

The strings contents are always returned as UTF8 by this function. Works for unicode strings and for non unicode strings.

This is the prefered way to access the strings contents.

Returns:
the string contents always as UTF8.

const pdf_utf16be * PoDoFo::PdfString::GetUnicode (  )  const [inline]

The contents of the strings can be read by this function.

The returned data is never hex encoded any maycontain 0 bytes.

if IsUnicode() returns true, the return value points to a UTF-16BE string buffer with Length() characters. Better use GetUnicode() in this case.

Returns:
the strings contents which is guaranteed to be zero terminated but might also contain 0 bytes in the string.
See also:
IsHex

IsUnicode

Length

long PoDoFo::PdfString::GetUnicodeLength (  )  const [inline]

The length of the string data returned by GetUnicode() in characters not including the terminating zero

Returns:
the length of the string.
See also:
GetCharacterLength to determine the number of characters in the string

bool PoDoFo::PdfString::IsHex (  )  const [inline]

Check if this is a hex string.

If true the data will be hex encoded when the string is written to a PDF file.

Returns:
true if this is a hex string.
See also:
GetString() will return the raw string contents (not hex encoded)

bool PoDoFo::PdfString::IsUnicode (  )  const [inline]

PdfStrings are either Latin1 encoded or UTF-16BE encoded unicode strings. This functions returns true if this is a unicode string object.

Returns:
true if this is a unicode string.

bool PoDoFo::PdfString::IsValid (  )  const [inline]

The string is valid if no error in the constructor has occurred. If it is valid it is safe to call all the other member functions.

Returns:
true if this is a valid initialized PdfString

bool PoDoFo::PdfString::operator!= ( const PdfString rhs  )  const [inline]

Comparison operator

Parameters:
rhs compare to this string object
Returns:
true if strings have different contents

bool PoDoFo::PdfString::operator< ( const PdfString rhs  )  const

Compare two PdfString objects

Parameters:
rhs another PdfString to compare
Returns:
this object

const PdfString & PoDoFo::PdfString::operator= ( const PdfString rhs  ) 

Copy an existing PdfString

Parameters:
rhs another PdfString to copy
Returns:
this object

bool PoDoFo::PdfString::operator== ( const PdfString rhs  )  const

Comparison operator

UTF-8 and UTF-16BE encoded strings of the same data compare equal. Whether the string will be written out as hex is not considered - only the real "text" is tested for equality.

Parameters:
rhs compare to this string object
Returns:
true if both strings have the same contents

bool PoDoFo::PdfString::operator> ( const PdfString rhs  )  const

Compare two PdfString objects

Parameters:
rhs another PdfString to compare
Returns:
this object

void PoDoFo::PdfString::SetHexData ( const char *  pszHex,
long  lLen = -1,
PdfEncrypt pEncrypt = NULL 
)

Set hex encoded data as the strings data.

Parameters:
pszHex must be hex encoded data.
lLen length of the hex encoded data. if lLen == -1 then strlen( pszHex ) will be used as length of the hex data. pszHex has to be zero terminated in this case.
pEncrypt if !NULL assume the hex data is encrypted and should be decrypted after hexdecoding

PdfString PoDoFo::PdfString::ToUnicode (  )  const

Converts this string to a hex encoded string.

If IsHex returns true, a copy of this string is returned otherwise the strings data is hex encoded and returned.

Returns:
a hex encoded version of this string or this string if it is already hex ecoded.
See also:
IsHex Converts this string to a ascii string (not hex encoded)
If IsHex returns false, a copy of this string is returned otherwise the strings data is hex decoded and returned.

Returns:
a plain version of this string which is not hex encoded or this string if it is already a plain not hex encoded string.
See also:
IsHex Converts this string to a unicode string
If IsUnicode() returns true a copy of this string is returned otherwise the string data is converted to UTF-16be and returned.

Returns:
a unicode version of this string

void PoDoFo::PdfString::Write ( PdfOutputDevice pDevice,
const PdfEncrypt pEncrypt = NULL 
) const [virtual]

Write this PdfString in PDF format to a PdfOutputDevice

Parameters:
pDevice the output device.
pEncrypt an encryption object which is used to encrypt this object or NULL to not encrypt this object

Implements PoDoFo::PdfDataType.


Generated on Tue Jul 28 00:56:35 2009 for PoDoFo by  doxygen 1.5.9