pdftron::SDF::NameTree Class Reference

#include <NameTree.h>

Public Member Functions
	NameTree (Obj name_tree)
	NameTree (const NameTree &d)
NameTree &	operator= (const NameTree &d)
bool	IsValid ()
NameTreeIterator	GetIterator (const UChar *key, int key_sz)
NameTreeIterator	GetIterator ()
Obj	GetValue (const UChar *key, int key_sz)
void	Put (const UChar *key, int key_sz, Obj value)
void	Erase (const UChar *key, int key_sz)
void	Erase (DictIterator &pos)
Obj	GetSDFObj () const

Static Public Member Functions
static NameTree	Create (class SDFDoc &doc, const std::string &name)
static NameTree	Find (class SDFDoc &doc, const std::string &name)

Protected Member Functions
	NameTree ()

Protected Attributes
TRN_NameTree	mp_obj

Detailed Description

A NameTree is a common data structure in PDF. See section 3.8.5 'Name Trees' in PDF Reference Manual for more details.

A name tree serves a similar purpose to a dictionary - associating keys and values - but by different means. NameTrees allow efficient storage of very large association collections (string/Obj* maps). A NameTree can have many more entries than a SDF/Cos dictionary can.

NameTree-s use SDF/Cos-style strings (not null-terminated C strings), which may use Unicode encoding etc.

*   PDFDoc doc("../Data/PDFReference.pdf");
*   NameTree dests = NameTree::Find(*doc.GetSDFDoc(), "Dests");
*   if (dests.IsValid()) {
*     // Traversing the NameTree
*     UString key;
*     for (DictIterator i = dests.GetIterator(); i.HasNext(); i.Next()) 
*        i.Key().GetAsPDFText(key); // ...
*   }
* 

Definition at line 47 of file NameTree.h.

Constructor & Destructor Documentation

pdftron::SDF::NameTree::NameTree

(

Obj

name_tree

)

Create a high level NameTree wrapper around an existing SDF/Cos NameTree. This does not copy the object.

Parameters

name_tree

SDF/Cos root of the NameTree object.

pdftron::SDF::NameTree::NameTree

(

const NameTree &

d

)

Copy constructor

pdftron::SDF::NameTree::NameTree ( )

inlineprotected

Definition at line 180 of file NameTree.h.

Member Function Documentation

static NameTree pdftron::SDF::NameTree::Create ( class SDFDoc &  doc, const std::string &  name  )

static

Retrieves the NameTree inside the '/Root/Names' dictionary with the specified key name, or creates it if it does not exist.

Parameters

doc	- The document in which the name tree is created.
name	- The name of the NameTree to create.

Returns

The newly created NameTree for the doc or an existing tree with the same key name.

Note

although it is possible to create a name tree anywhere in the document the convention is that all trees are located under '/Root/Names' dictionary.

void pdftron::SDF::NameTree::Erase	(	const UChar *	key,
		int	key_sz
	)

Removes the specified object from the tree. Does nothing if no object with that name exists.

Parameters

key	data buffer representing the key of the entry to be removed.
key_sz	The size (in bytes) of the key.

void pdftron::SDF::NameTree::Erase

(

DictIterator &

pos

)

Removes the NameTree entry pointed by the iterator.

Parameters

pos	ditionary iterator object that points to the NameTree entry to be removed.

static NameTree pdftron::SDF::NameTree::Find ( class SDFDoc &  doc, const std::string &  name  )

static

Retrieves a name tree, with the given key name, from the '/Root/Names' dictionary of the doc.

Parameters

doc	- The document in which to search for the name.
name	- The name of the name tree to find.

Returns

The requested NameTree. If the requested NameTree exists NameTree.IsValid() will return true, and false otherwise.

NameTreeIterator pdftron::SDF::NameTree::GetIterator	(	const UChar *	key,
		int	key_sz
	)

Search for the specified key in the NameTree.

Returns

If the key is present the function returns a NameTreeIterator the points to the given Key/Value pair. If the key is not found the function returns End() (a non-valid) iterator.

Parameters

key	data buffer representing the key to be found.
key_sz	The size (in bytes) of the key.

*   DictIterator i = dests.Find("MyKey", 5);
*   if (i.HasNext()) { 
*     UString key;
*     i.GetKey().GetAsPDFText(key); // ...
*     cout << "Value: " << i.GetValue().GetType() << endl;
*   }
* 

NameTreeIterator pdftron::SDF::NameTree::GetIterator

(

)

Returns

an iterator that addresses the first element in the NameTree. The iterator can be used to traverse all entries stored in the NameTree.

*  UString key;   
*  for (NameTreeIterator i = dests.GetIterator(); i.HasNext(); i.Next()) {
*    i.GetKey().GetAsPDFText(key); // ...
*  }
* 

Obj pdftron::SDF::NameTree::GetSDFObj

(

)

const

Returns

the object to the underlying SDF/Cos object. If the NameTree.IsValid() returns false the SDF/Cos object is NULL.

Obj pdftron::SDF::NameTree::GetValue	(	const UChar *	key,
		int	key_sz
	)

Search the NameTree for a given key.

Parameters

key	- a key to search for in the dictionary
key_sz	- the buffer size used to store the key.

Returns

null if the tree does not contain the specified key, otherwise return the corresponding value.

bool pdftron::SDF::NameTree::IsValid

(

)

Returns

whether this is a valid (non-null) NameTree. If the function returns false the underlying SDF/Cos object is null and the NameTree object should be treated as null as well.

NameTree& pdftron::SDF::NameTree::operator=

(

const NameTree &

d

)

Assignment operator

void pdftron::SDF::NameTree::Put	(	const UChar *	key,
		int	key_sz,
		Obj	value
	)

Puts a new entry in the name tree. If an entry with this key is already in the tree, it is replaced.

Parameters

key	data buffer representing the key of the new entry.
key_sz	The size (in bytes) of the key.
value	the value associated with the key. It can be any SDF::Obj.

Member Data Documentation

TRN_NameTree pdftron::SDF::NameTree::mp_obj

protected

Definition at line 180 of file NameTree.h.

---

The documentation for this class was generated from the following file:

• SDF/NameTree.h