PoDoFo 0.7.0
Public Member Functions
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, pdf_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, pdf_long lLen)
 PdfString (const pdf_utf16be *pszStringUtf16, pdf_long lLen)
 PdfString (const PdfString &rhs)
void SetHexData (const char *pszHex, pdf_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
pdf_long GetLength () const
pdf_long GetUnicodeLength () const
pdf_long GetCharacterLength () const
void Write (PdfOutputDevice *pDevice, EPdfWriteMode eWriteMode, 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:
sStringthe string to copy
pEncodingthe 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:
pszStringthe string to copy
pEncodingthe 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:
pszStringthe string to copy
PoDoFo::PdfString::PdfString ( const char *  pszString,
pdf_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:
pszStringthe string to copy
lLenlength of the string data to encode
bHexif true the data will be hex encoded during writeout of the string and IsHex() will return true.
pEncodingthe 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:
pszStringUtf8a UTF-8 encoded string.
PoDoFo::PdfString::PdfString ( const pdf_utf16be *  pszStringUtf16)

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

Parameters:
pszStringUtf16a UTF-16BE encoded string.
PoDoFo::PdfString::PdfString ( const pdf_utf8 *  pszStringUtf8,
pdf_long  lLen 
)

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

The string is converted to UTF-16BE internally.

Parameters:
pszStringUtf8a UTF-8 encoded string.
lLennumber of bytes to convert
PoDoFo::PdfString::PdfString ( const pdf_utf16be *  pszStringUtf16,
pdf_long  lLen 
)

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

Parameters:
pszStringUtf16a UTF-16BE encoded string.
lLennumber of words to convert
PoDoFo::PdfString::PdfString ( const PdfString rhs)

Copy an existing PdfString

Parameters:
rhsanother PdfString to copy

Member Function Documentation

pdf_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

pdf_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
pdf_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:
rhscompare to this string object
Returns:
true if strings have different contents
bool PoDoFo::PdfString::operator< ( const PdfString rhs) const

Compare two PdfString objects

Parameters:
rhsanother PdfString to compare
Returns:
this object
const PdfString & PoDoFo::PdfString::operator= ( const PdfString rhs)

Copy an existing PdfString

Parameters:
rhsanother 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:
rhscompare 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:
rhsanother PdfString to compare
Returns:
this object
void PoDoFo::PdfString::SetHexData ( const char *  pszHex,
pdf_long  lLen = -1,
PdfEncrypt pEncrypt = NULL 
)

Set hex encoded data as the strings data.

Parameters:
pszHexmust be hex encoded data.
lLenlength 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.
pEncryptif !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,
EPdfWriteMode  eWriteMode,
const PdfEncrypt pEncrypt = NULL 
) const [virtual]

Write this PdfString in PDF format to a PdfOutputDevice

Parameters:
pDevicethe output device.
eWriteModeadditional options for writing this object
pEncryptan encryption object which is used to encrypt this object or NULL to not encrypt this object

Implements PoDoFo::PdfDataType.