# Class: NameTree

## PDFNet. NameTree

#### new NameTree()

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

### Methods

#### <static> create(doc, name)

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `doc` | PDFNet.SDFDoc | The document in which the name tree is created.
  `name` | string | The name of the NameTree to create.

  ##### Returns:

  A promise that resolves to the newly created NameTree for the doc or an existing tree with the same key name.

  Type
    PDFNet.NameTree

#### <static> createFromObj(name_tree)

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `name_tree` | PDFNet.Obj | SDF/Cos root of the NameTree object.

  ##### Returns:

  A promise that resolves to an object of type: "NameTree"

  Type
    PDFNet.NameTree

#### <static> find(doc, name)

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `doc` | PDFNet.SDFDoc | The document in which to search for the name.
  `name` | string | The name of the name tree to find.

  ##### Returns:

  A promise that resolves to the requested NameTree. If the requested NameTree exists NameTree.IsValid() will return true, and false otherwise.

  Type
    PDFNet.NameTree

#### copy()

  Assignment operator

  ##### Returns:

  A promise that resolves to an object of type: "NameTree"

  Type
    PDFNet.NameTree

#### erase(pos)

  Removes the NameTree entry pointed by the iterator.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pos` | PDFNet.DictIterator | ditionary iterator object that points to the NameTree entry to be removed.

#### eraseKey(key)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `key` | string |

#### getIterator(key)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `key` | string |

  ##### Returns:

  A promise that resolves to an object of type: "DictIterator"

  Type
    PDFNet.DictIterator

#### getIteratorBegin()

  ##### Returns:

  A promise that resolves to 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); // ...
       }

  Type
    PDFNet.DictIterator

#### getSDFObj()

  ##### Returns:

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

  Type
    PDFNet.Obj

#### getValue(key)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `key` | string |

  ##### Returns:

  A promise that resolves to an object of type: "Obj"

  Type
    PDFNet.Obj

#### isValid()

  ##### Returns:

  A promise that resolves to 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.

  Type
    boolean

#### put(key, value)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `key` | string |
  `value` | PDFNet.Obj |

#### Search results