PoDoFo  0.9.4
Public Member Functions | List of all members
PoDoFo::PdfString Class Reference

#include <PdfString.h>

Inheritance diagram for PoDoFo::PdfString:
PoDoFo::PdfDataType

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, pdf_long lLen=-1)
 
 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
 
PdfRefCountedBufferGetBuffer (void)
 
- Public Member Functions inherited from PoDoFo::PdfDataType
virtual bool IsDirty () const
 
virtual void SetDirty (bool bDirty)
 
void SetImmutable (bool bImmutable)
 
bool GetImmutable () const
 

Additional Inherited Members

- Protected Member Functions inherited from PoDoFo::PdfDataType
 PdfDataType ()
 
void AssertMutable () 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,
pdf_long  lLen = -1 
)

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

PdfRefCountedBuffer & PoDoFo::PdfString::GetBuffer ( void  )

Returns internal buffer; do not free it, it's owned by the PdfString

Returns
internal buffer; do not free it, it's owned by the PdfString returns a NULL zero size buffer if PdfString::IsValid() returns false
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!

Returns
the number of characters in the string, returns zero if PdfString::IsValid() returns false
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, returns zero if PdfString::IsValid() returns false
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, returns NULL if PdfString::IsValid() returns false
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, returns NULL if PdfString::IsValid() returns false
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, returns zero if PdfString::IsValid() returns false
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. The default constructor PdfString() creates an invalid string, as do other constructors when passed a NULL char* or NULL wchar_t*. PdfString::StringNull uses the default constructor so is also invalid. 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 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, returns *this if if PdfString::IsValid() returns false
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.