A wrapper around PDF strings. More...

Files
file	PDString.h

Data Structures
struct	PDString

Macros
#define	PDStringCreateBinaryFromString(string) PDStringCreateFromStringWithType(string, PDStringTypeBinary, false, false)

#define	PDStringEscapingCString(unescapedCString) PDAutorelease(PDStringCreateUnescaped(unescapedCString))

#define	PDStringWithCString(cString) PDAutorelease(PDStringCreate(cString))

#define	PDStringWithName(name) PDAutorelease(PDStringCreateWithName(name))

Typedefs
typedef struct PDString *	PDStringRef

Enumerations
enum	PDStringType { PDStringTypeEscaped = 1, PDStringTypeHex = 2, PDStringTypeBinary = 3, PDStringTypeName = 4 }

Functions
PDStringRef	PDStringCreate (char *string)

PDStringRef	PDStringCreateUnescaped (char *unescapedString)

PDStringRef	PDStringCreateWithName (char *name)

PDStringRef	PDStringCreateBinary (char *data, PDSize length)

PDStringRef	PDStringCreateWithHexString (char *hex)

PDStringRef	PDStringCreateFromStringWithType (PDStringRef string, PDStringType type, PDBool wrap, PDBool requireCopy)

PDStringRef	PDStringCreateUTF8Encoded (PDStringRef string)

PDStringRef	PDStringCreateUTF16Encoded (PDStringRef string)

PDStringRef	PDStringCopy (PDStringRef string)

PDStringEncoding	PDStringEncodingGetByName (const char *encodingName)

void	PDStringSetEncoding (PDStringRef string, PDStringEncoding encoding)

void	PDStringSetFont (PDStringRef string, PDFontRef font)

void	PDStringForceWrappedState (PDStringRef string, PDBool wrapped)

const char *	PDStringEscapedValue (PDStringRef string, PDBool wrap)

const char *	PDStringNameValue (PDStringRef string, PDBool wrap)

const char *	PDStringBinaryValue (PDStringRef string, PDSize *outLength)

const char *	PDStringHexValue (PDStringRef string, PDBool wrap)

PDBool	PDStringEqualsCString (PDStringRef string, const char *cString)

PDBool	PDStringEqualsString (PDStringRef string, PDStringRef string2)

PDBool	PDStringIsWrapped (PDStringRef string)

PDStringType	PDStringGetType (PDStringRef string)

PDStringEncoding	PDStringGetEncoding (PDStringRef string)

PDBool	PDStringIsEncrypted (PDStringRef string)

void	PDStringAttachCrypto (PDStringRef string, pd_crypto crypto, PDInteger objectID, PDInteger genNumber, PDBool encrypted)

PDStringRef	PDStringCreateEncrypted (PDStringRef string)

PDStringRef	PDStringCreateDecrypted (PDStringRef string)

PDDictionaryRef	PDStringLatinCharsetDict (void)

const char **	PDStringLatinRCharsetArray (void)

PDInteger	PDStringPrinter (void inst, char buf, PDInteger offs, PDInteger cap)

Variables
const unsigned char	PDStringLatinPDFToWin []

Detailed Description

A wrapper around PDF strings.

PDString objects exist to provide a unified way to maintain and convert between different string types. In particular, it is responsible for providing a means to escape and unescape content, as well as convert to and from hex strings (written as <abc123> in PDFs).

Data Structure Documentation

struct PDString

Internal string structure.

Data Fields
PDStringType	type
	Type of the string.

PDFontRef	font
	The font associated with the string.

PDStringEncoding	enc
	Encoding of the string.

PDSize	length
	Length of the string.

PDBool	wrapped
	Whether the string is wrapped.

char *	data
	Buffer containing string data.

PDStringRef	alt
	Alternative representation.

PDCryptoInstanceRef	ci
	Crypto instance.

PDBool	encrypted
	Flag indicating whether the string is encrypted or not; the value of this flag is UNDEFINED if ci == NULL.

Macro Definition Documentation

#define PDStringCreateBinaryFromString ( string ) PDStringCreateFromStringWithType(string, PDStringTypeBinary, false, false)

Short hand for creating a binary string from an existing PDStringRef

Parameters

string String whose binary form is desired

Returns: Binary PDString object

Typedef Documentation

typedef struct PDString* PDStringRef

A string object.

Enumeration Type Documentation

enum PDStringType

The type of a string.

Enumerator
PDStringTypeEscaped	A regular string, escaped and NUL-terminated.
PDStringTypeHex	A HEX string, NUL-terminated.
PDStringTypeBinary	A binary string, which may or may not be NUL-terminated, and may contain any character.
PDStringTypeName	A regular string prefixed with a forward slash.

Function Documentation

void PDStringAttachCrypto	(	PDStringRef	string,
		pd_crypto	crypto,
		PDInteger	objectID,
		PDInteger	genNumber,
		PDBool	encrypted
	)

Attach a crypto object to the string, and associate the array with a specific object. The encrypted flag is used to determine if the PDString is encrypted or not in its current state.

Parameters

string	PDString instance whose crypto object is to be set
crypto	pd_crypto object
objectID	The object ID of the owning object
genNumber	Generation number of the owning object
encrypted	Whether string is encrypted or not, currently

const char* PDStringBinaryValue	(	PDStringRef	string,
		PDSize *	outLength
	)

Generate the binary value of string, writing its length to the PDSize pointed to by outLength and returning the binary value.

Note: The returned string should not be freed.; It is safe to pass a NULL string value. If string is NULL, NULL is returned.

Parameters

string	PDString instance
outLength	Pointer to PDSize object into which the length of the returned binary data is to be written. May be NULL.

Returns: C string pointer to binary data.

PDStringRef PDStringCopy ( PDStringRef string )

Create a copy of the given string.

Parameters

string String to copy

Returns: A new string, identical in every way to the original string

PDStringRef PDStringCreate ( char * string )

Create a PDString from an existing, escaped string.

Note: Ownership of the string is taken, and the string is freed when the PDString object is released.; Use PDStringCreateBinary for strings that need to be escaped, even if they're proper NUL-terminated strings.

Parameters

string NUL-terminated, escaped string optionally wrapped in parentheses.

Returns: New PDString instance for string

PDStringRef PDStringCreateBinary	(	char *	data,
		PDSize	length
	)

Create a PDString from an existing, unescaped or binary string of the given length.

Note: Ownership of the data is taken, and the data is freed when the PDString object is released.

Parameters

data	Data containing binary string
length	Length of the data, in bytes

Returns: New PDString instance for data

PDStringRef PDStringCreateDecrypted ( PDStringRef string )

Create a PDString by decrypting string.

Note: If string is not encrypted, it is retained and returned as is.

Parameters

string PDString instance

Returns: A retained decrypted PDStringRef for string

PDStringRef PDStringCreateEncrypted ( PDStringRef string )

Create a PDString by encrypting string.

Note: If string is already encrypted, or if no crypto has been attached, the string is retained and returned as is.

Parameters

string PDString instance to encrypt

Returns: A retained encrypted PDStringRef for string

PDStringRef PDStringCreateFromStringWithType	(	PDStringRef	string,
		PDStringType	type,
		PDBool	wrap,
		PDBool	requireCopy
	)

Create a PDString from an existing PDString instance, with an explicit type. In effect, this creates a new PDString object whose type matches the given type. This method is recommended for converting between types, unless the C string value is explicitly desired.

Note: If string is already of the given type, it is retained and returned as is.

Parameters

string	PDString instance used in transformation
type	String type to transform to
wrap	Whether the string should be wrapped ("()" for escaped, "<>" for hex)
requireCopy	If false, and if string matches the required type and wrap state, string is retained and returned, otherwise a copy of string is returned.

Returns: A PDString whose value is identical to that of string, and whose type is the given type

PDStringRef PDStringCreateUnescaped ( char * unescapedString )

Create a PDString from an existing, unescaped string by escaping the string and keeping the resulting value.

Parameters

unescapedString A string that needs to be, but is not currently, escaped.

Returns: New PDString instance for escaped variant of unescapedString

PDStringRef PDStringCreateUTF16Encoded ( PDStringRef string )

Create a UTF-16 encoded version of the given string. If the string has not had its encoding set, a wild (and often incorrect) guess is made.

See also: PDStringSetEncoding, PDStringSetFont

Parameters

string The string to convert to UTF-16

Returns: A new UTF-16 encoded version of string, or string itself (retained) if it is already UTF-16 encoded

PDStringRef PDStringCreateUTF8Encoded ( PDStringRef string )

Create a UTF-8 encoded version of the given string. If the string has not had its encoding set, a wild (and often incorrect) guess is made.

See also: PDStringSetEncoding, PDStringSetFont

Parameters

string The string to convert to UTF-8

Returns: A new UTF-8 encoded version of string, or string itself (retained) if it is already UTF-8 encoded

PDStringRef PDStringCreateWithHexString ( char * hex )

Create a PDString from an existing hex string.

Note: Ownership of the data is taken, and the data is freed when the PDString object is released.

Parameters

hex	Hex string, optionally wrapped in less/greater-than signs.

Returns: New PDString instance for hex

PDStringRef PDStringCreateWithName ( char * name )

Create a PDString from an existing, escaped name. Names differ from regular strings in one single way: they have a slash prefix. Beyond that, they can be wrapped or non-wrapped, just like normal.

Parameters

name	Name string, with or without prefix slash, with or without wrapping.

Returns: New PDString instance for name

PDStringEncoding PDStringEncodingGetByName ( const char * encodingName )

Get the encoding type for the given encoding string.

Parameters

encodingName Encoding name

Returns: Encoding which may be PDStringEncodingUndefined if the given string was not recognized

PDBool PDStringEqualsString	(	PDStringRef	string,
		PDStringRef	string2
	)

Compare the two strings and determine if their content is equal, disregarding wrapping and representation type.

Parameters

string	First string to compare
string2	Second string to compare

Returns: Boolean value indicating whether the strings are equal

const char* PDStringEscapedValue	(	PDStringRef	string,
		PDBool	wrap
	)

Generate a C string containing the escaped contents of string and return it. If wrap is set, the string is wrapped in parentheses.

Note: The returned string should not be freed.; It is safe to pass a NULL string value. If string is NULL, NULL is returned.

Parameters

string	PDString instance
wrap	Whether or not the returned string should be enclosed in parentheses

Returns: Escaped NUL-terminated C string.

void PDStringForceWrappedState	(	PDStringRef	string,
		PDBool	wrapped
	)

Force the wrapped state of a string. Normally, when a regular string is set up, its 'wrapped' flag is set to true if the string is equal to "(whatever)", but in some rare instances, the wrapped string is "((value))", which unwrapped appears as "(value)", but is interpreted as "value"; wrapped = true.

Parameters

string	PDString
wrapped	The wrapped state of the PDString

const char* PDStringHexValue	(	PDStringRef	string,
		PDBool	wrap
	)

Generate a hex string based on the value of string, returning it.

Note: The returned string should not be freed.; It is safe to pass a NULL string value. If string is NULL, NULL is returned.

Parameters

string	PDString instance
wrap	Whether or not the returned string should be enclosed in less/greater-than signs

Returns: Hex string.

PDBool PDStringIsEncrypted ( PDStringRef string )

Determine if the given string is currently encrypted or not.

Parameters

string String to check

Returns: true if encrypted, false if not

PDDictionaryRef PDStringLatinCharsetDict ( void )

Retrieve the latin character set dictionary.

Returns: Latin character set dictionary

const char** PDStringLatinRCharsetArray ( void )

Retrieve the reversed latin character set dictionary. The dictionary is reversed, in that the keys are the code points and the values are the names. The dictionary is returned as a char* array with NULL in place of holes, if any.

Returns: Reversed Latin character set as a const char*[]

const char* PDStringNameValue	(	PDStringRef	string,
		PDBool	wrap
	)

Generate a C string containing the escaped contents of string as a name, i.e. with a forward slash preceding it. If wrap is set, the string (after forward slash) is wrapped in parentheses.

Note: The returned string should not be freed.; It is safe to pass a NULL string value. If string is NULL, NULL is returned.

Parameters

string	PDString instance
wrap	Whether or not the returned string should be enclosed in parentheses

Returns: Escaped NUL-terminated C string with a forward slash prefix.

void PDStringSetEncoding	(	PDStringRef	string,
		PDStringEncoding	encoding
	)

Set the encoding for the given string. Note that this does not convert the string in any way, it simply informs the system that this string is of the given encoding. To make conversions to other encodings, use PDStringCreate...Encoded().

Parameters

string	String whose encoding is being clarified
encoding	The encoding being used by the string

void PDStringSetFont	(	PDStringRef	string,
		PDFontRef	font
	)

Set the font used to represent the given string. This is primarily used to get the ToUnicode CID Map, used when translating a string into its UTF-8 sequence. The string adapts the encoding of the font, as if PDStringSetEncoding(string, PDFontGetEncoding(font)) had been issued. If font is NULL, the string uses its current encoding, but will discard its current font object, if any.

Parameters

string	String whose font is being set
font	Font object

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

Data Fields

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation