CGPDFDictionary Reference

Overview

The CGPDFDictionaryRef opaque type encapsulates a PDF dictionary whose key-value pairs can specify any kind of PDF object, including another dictionary. Dictionary objects are the main building blocks of a PDF document. A key-value pair within a dictionary is called an entry. In a PDF dictionary, the key must be an array of characters. Within a given dictionary, the keys are unique—that is, no two keys in a single dictionary are equal (as determined by strcmp). The value associated with a key can be any kind of PDF object, including another dictionary. Dictionary objects are the main building blocks of a PDF document.

Many functions that retrieve values from a PDF dictionary take the form:

bool CGPDFDictionaryGet<DataType> (

 CGPDFDictionaryRef dictionary,

 const char *key,

 <DataType>Ref *value

);

These functions test whether there is an object associated with the specified key. If there is an object associated with the specified key, they test its data type. If there is no associated object, or if there is but it is not of the expected type, the function returns false. If there is an object associated with the specified key and it is of the expected type, the function returns true and the object is passed back in the value parameter.

This opaque type is not derived from CFType and therefore there are no functions for retaining and releasing it. CGPDFDictionary objects exist only as constituent parts of a CGPDFDocument object, and they are managed by their container.

Functions by Task

Applying a Function to All Entries

• CGPDFDictionaryApplyFunction

Getting Data from a Dictionary

• CGPDFDictionaryGetArray
• CGPDFDictionaryGetBoolean
• CGPDFDictionaryGetCount
• CGPDFDictionaryGetDictionary
• CGPDFDictionaryGetInteger
• CGPDFDictionaryGetName
• CGPDFDictionaryGetNumber
• CGPDFDictionaryGetObject
• CGPDFDictionaryGetStream
• CGPDFDictionaryGetString

Functions

CGPDFDictionaryApplyFunction

Applies a function to each entry in a dictionary.

void CGPDFDictionaryApplyFunction (
   CGPDFDictionaryRef dict,
   CGPDFDictionaryApplierFunction function,
   void *info
);

CGPDFDictionaryGetArray

Returns whether there is a PDF array associated with a specified key in a PDF dictionary and, if so, retrieves that array.

bool CGPDFDictionaryGetArray (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFArrayRef *value
);

CGPDFDictionaryGetBoolean

Returns whether there is a PDF Boolean value associated with a specified key in a PDF dictionary and, if so, retrieves the Boolean value.

bool CGPDFDictionaryGetBoolean (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFBoolean *value
);

CGPDFDictionaryGetCount

Returns the number of entries in a PDF dictionary.

size_t CGPDFDictionaryGetCount (
   CGPDFDictionaryRef dict
);

CGPDFDictionaryGetDictionary

Returns whether there is another PDF dictionary associated with a specified key in a PDF dictionary and, if so, retrieves that dictionary.

bool CGPDFDictionaryGetDictionary (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFDictionaryRef *value
);

CGPDFDictionaryGetInteger

Returns whether there is a PDF integer associated with a specified key in a PDF dictionary and, if so, retrieves that integer.

bool CGPDFDictionaryGetInteger (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFInteger *value
);

CGPDFDictionaryGetName

Returns whether an object with a specified key in a PDF dictionary is a PDF name reference (represented as a constant C string) and, if so, retrieves that name.

bool CGPDFDictionaryGetName (
   CGPDFDictionaryRef dict,
   const char *key,
   const char **value
);

CGPDFDictionaryGetNumber

Returns whether there is a PDF number associated with a specified key in a PDF dictionary and, if so, retrieves that number.

bool CGPDFDictionaryGetNumber (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFReal *value
);

CGPDFDictionaryGetObject

Returns whether there is a PDF object associated with a specified key in a PDF dictionary and, if so, retrieves that object.

bool CGPDFDictionaryGetObject (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFObjectRef *value
);

CGPDFDictionaryGetStream

Returns whether there is a PDF stream associated with a specified key in a PDF dictionary and, if so, retrieves that stream.

bool CGPDFDictionaryGetStream (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFStreamRef *value
);

CGPDFDictionaryGetString

Returns whether there is a PDF string associated with a specified key in a PDF dictionary and, if so, retrieves that string.

bool CGPDFDictionaryGetString (
   CGPDFDictionaryRef dict,
   const char *key,
   CGPDFStringRef *value
);

Callbacks

CGPDFDictionaryApplierFunction

Performs custom processing on a key-value pair from a PDF dictionary, using optional contextual information.

typedef void (*CGPDFDictionaryApplierFunction) (
   const char *key,
   CGPDFObjectRef value,
   void *info,
);
   

If you name your function MyFunction, you would declare it like this:

void MyFunction (
   const char *key,
   CGPDFObjectRef object,
   void *info
);

Data Types

CGPDFDictionaryRef

An opaque type that encapsulates a PDF dictionary.

typedef struct CGPDFDictionary *CGPDFDictionaryRef;