pdftron::SDF::NameTree Class Reference

A NameTree is a common data structure in PDF. More...

#include <NameTree.h>

List of all members.

Public Member Functions

 NameTree (Obj name_tree)
 Create a high level NameTree wrapper around an existing SDF/Cos NameTree.
 NameTree (const NameTree &d)
 Copy constructor.
NameTreeoperator= (const NameTree &d)
 Assignment operator.
bool IsValid ()
NameTreeIterator GetIterator (const UChar *key, int key_sz)
 Search for the specified key in the NameTree.
NameTreeIterator GetIterator ()
Obj GetValue (const UChar *key, int key_sz)
 Search the NameTree for a given key.
void Put (const UChar *key, int key_sz, Obj value)
 Puts a new entry in the name tree.
void Erase (const UChar *key, int key_sz)
 Removes the specified object from the tree.
void Erase (DictIterator &pos)
 Removes the NameTree entry pointed by the iterator.
Obj GetSDFObj () const

Static Public Member Functions

static NameTree Create (class SDFDoc &doc, const std::string &name)
 Retrieves the NameTree inside the '/Root/Names' dictionary with the specified key name, or creates it if it does not exist.
static NameTree Find (class SDFDoc &doc, const std::string &name)
 Retrieves a name tree, with the given key name, from the '/Root/Names' dictionary of the doc.

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); // ...
   }

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 (  )  [inline, protected]


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.

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.

NameTree& pdftron::SDF::NameTree::operator= ( const NameTree d  ) 

Assignment operator.

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.

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::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.

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.
the value associated with the key. It can be any SDF::Obj.

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.

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.


Member Data Documentation

TRN_NameTree pdftron::SDF::NameTree::mp_obj [protected]


© 2002-2010 PDFTron Systems Inc.