PTNameTree

@interface PTNameTree : NSObject

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

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

    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.

    Declaration

    Objective-C

    + (PTNameTree *)Create:(PTSDFDoc *)doc name:(NSString *)name;

    Swift

    class func create(_ doc: PTSDFDoc!, name: String!) -> PTNameTree!

    Parameters

    doc

    - The document in which the name tree is created.
    name

    - The name of the NameTree to create.

    Return Value

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

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

    Declaration

    Objective-C

    + (PTNameTree *)Find:(PTSDFDoc *)doc name:(NSString *)name;

    Swift

    class func find(_ doc: PTSDFDoc!, name: String!) -> PTNameTree!

    Parameters

    doc

    - The document in which to search for the name.
    name

    - The name of the name tree to find.

    Return Value

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

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

    Declaration

    Objective-C

    - (instancetype)initWithName_tree:(PTObj *)name_tree;

    Swift

    init!(name_tree: PTObj!)

    Parameters

    name_tree

    SDF/Cos root of the NameTree object.

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    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.

  • Undocumented

    Declaration

    Objective-C

    - (PTDictIterator*)GetNameIteratorWithKey: (NSData*)key key_sz:  (int)key_sz;

    Swift

    func getNameIterator(withKey key: Data!, key_sz: Int32) -> PTDictIterator!

  • Search for the specified key in the NameTree.

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

    Declaration

    Objective-C

    - (PTDictIterator *)GetIterator;

    Swift

    func getIterator() -> PTDictIterator!

    Parameters

    key

    data buffer representing the key to be found.
    key_sz

    The size (in bytes) of the key.

    Return Value

    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.

  • Search the NameTree for a given key.

    Declaration

    Objective-C

    - (PTObj *)GetValue:(NSData *)key key_sz:(int)key_sz;

    Swift

    func getValue(_ key: Data!, key_sz: Int32) -> PTObj!

    Parameters

    key

    - a key to search for in the dictionary
    key_sz

    - the buffer size used to store the key.

    Return Value

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

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

    Declaration

    Objective-C

    - (void)Put:(NSData *)key key_sz:(int)key_sz value:(PTObj *)value;

    Swift

    func put(_ key: Data!, key_sz: Int32, value: PTObj!)

    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.

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

    Declaration

    Objective-C

    - (void)EraseNameTreeEntryWithKey:(NSData *)key key_sz:(int)key_sz;

    Swift

    func eraseNameTreeEntry(withKey key: Data!, key_sz: Int32)

    Parameters

    key

    data buffer representing the key of the entry to be removed.
    key_sz

    The size (in bytes) of the key.

  • Removes the NameTree entry pointed by the iterator.

    Declaration

    Objective-C

    - (void)EraseNameTreeEntryWithPos:(PTDictIterator *)pos;

    Swift

    func eraseNameTreeEntry(withPos pos: PTDictIterator!)

    Parameters

    pos

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

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

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