PoDoFo  0.9.6
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 encoded either in PDFDocEncoding (ISO Latin1) or UTF-16BE.

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

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

PdfString 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 zero ('\0') bytes.

Constructor & Destructor Documentation

◆ PdfString() [1/10]

PoDoFo::PdfString::PdfString ( )

Create an empty and invalid string

◆ PdfString() [2/10]

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.

◆ PdfString() [3/10]

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

Construct a new PdfString from a 0-terminated C-style 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.

◆ PdfString() [4/10]

PoDoFo::PdfString::PdfString ( const wchar_t *  pszString,
pdf_long  lLen = -1 
)

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

Parameters
pszStringthe string to copy

◆ PdfString() [5/10]

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 two 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 writing out 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.

◆ PdfString() [6/10]

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
pszStringUtf8an UTF-8 encoded string.

◆ PdfString() [7/10]

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

Construct a new PdfString from an UTF-16BE encoded zero-terminated C-style string.

Parameters
pszStringUtf16an UTF-16BE encoded string.

◆ PdfString() [8/10]

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

◆ PdfString() [9/10]

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

◆ PdfString() [10/10]

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

Copy an existing PdfString

Parameters
rhsanother PdfString to copy

Member Function Documentation

◆ GetBuffer()

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 (zero size buffer, internally NULL, if PdfString::IsValid() returns false).

◆ GetCharacterLength()

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 return the number of bytes used for Unicode strings!

Returns
the number of characters in the string, returns zero if PdfString::IsValid() returns false

◆ GetLength()

pdf_long PoDoFo::PdfString::GetLength ( ) const
inline

The length of the string data returned by GetString() in bytes not including terminating zero ('\0') bytes.

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

◆ GetString()

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

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

The returned data is never hex-encoded and may contain '\0' bytes.

If IsUnicode() returns true, the return value points to a UTF-16BE string buffer with GetCharacterLength() characters (GetLength() bytes without the terminating '\0'). Better use GetUnicode() in this case. )

Returns
the string's contents which are guaranteed to be zero-terminated but might also contain '\0' bytes in the string.
See also
IsHex
IsUnicode
GetLength

◆ GetStringUtf8()

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

The contents of the string as UTF-8 string.

The string's contents are always returned as UTF-8 by this function. Works for Unicode strings and for non-Unicode strings.

This is the preferred way to access the string's contents.

Returns
the string's contents always as UTF-8, returns NULL if PdfString::IsValid() returns false

◆ GetUnicode()

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

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

The returned data is never hex-encoded any may contain '\0' bytes.

If IsUnicode() returns true, the return value points to a UTF-16BE string with GetCharacterLength() characters (GetLength() bytes without the terminating '\0' bytes).

If IsUnicode() returns false, the return value points to a PdfDocEncoding string buffer with GetLength() characters (so may well not be valid as UTF-16BE). Better use GetString() in this case.

Returns
the string's contents which are 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
GetUnicodeLength

◆ GetUnicodeLength()

pdf_long PoDoFo::PdfString::GetUnicodeLength ( ) const
inline

The length of the string data returned by GetUnicode() in characters not including the terminating zero ('\0') bytes.

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

◆ IsHex()

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)

◆ IsUnicode()

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

PdfStrings are either Latin1-encoded or UTF-16BE-encoded Unicode strings.

This function returns true if this is a Unicode string object.

Returns
true if this is a Unicode string.

◆ IsValid()

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

◆ operator!=()

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

Comparison operator

Parameters
rhscompare to this string object
Returns
true if strings have different contents

◆ operator<()

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

Compare two PdfString objects

Parameters
rhsanother PdfString to compare with
Returns
this object

◆ operator=()

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

Copy an existing PdfString

Parameters
rhsanother PdfString to copy
Returns
this object

◆ operator==()

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

◆ operator>()

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

Compare two PdfString objects

Parameters
rhsanother PdfString to compare with
Returns
this object

◆ SetHexData()

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 hex-decoding.

◆ ToUnicode()

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

◆ Write()

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.