Show / Hide Table of Contents

# Class 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.

##### Inheritance

object
NameTree

##### Implements

IDisposable

##### Inherited Members

object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()

###### Namespace: pdftron.SDF

###### Assembly: PDFNet.dll

##### Syntax

    public class NameTree : IDisposable

### Constructors

#### NameTree(Obj)

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

##### Declaration

    public NameTree(Obj name_tree)

##### Parameters

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

### Methods

#### Create(SDFDoc, string)

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

##### Declaration

    public static NameTree Create(SDFDoc doc, string name)

##### Parameters

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

##### Returns

Type | Description
--- | ---
NameTree | The newly created NameTree for the doc or an exising tree with the same key name.

##### Remarks

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.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Dispose()

Releases all resources used by the NameTree

##### Declaration

    public override sealed void Dispose()

#### Dispose(bool)

##### Declaration

    [HandleProcessCorruptedStateExceptions]
    protected virtual void Dispose(bool A_0)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | A_0 |

#### Erase(byte[])

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

##### Declaration

    public void Erase(byte[] key)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | key | data buffer representing the key of the entry to be removed.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Erase(NameTreeIterator)

Removes the NameTree entry pointed by the iterator.

##### Declaration

    public void Erase(NameTreeIterator pos)

##### Parameters

Type | Name | Description
--- | --- | ---
NameTreeIterator | pos | the pos

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### ~NameTree()

Allows an NameTree to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

##### Declaration

    protected ~NameTree()

#### Find(SDFDoc, string)

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

##### Declaration

    public static NameTree Find(SDFDoc doc, string name)

##### Parameters

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

##### Returns

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

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetIterator()

Gets the iterator.

##### Declaration

    public NameTreeIterator GetIterator()

##### Returns

Type | Description
--- | ---
NameTreeIterator | an iterator to the first key/value pair (i.e. NNTreeData) in the document. You can use the increment operator on the returned iterator to traverese all entries stored under the NameTree.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetIterator(byte[])

Search for the specified key in the NameTree.

##### Declaration

    public NameTreeIterator GetIterator(byte[] key)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | key | data buffer representing the key to be found.

##### Returns

Type | Description
--- | ---
NameTreeIterator | 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.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetSDFObj()

Gets the SDFObj.

##### Declaration

    public Obj GetSDFObj()

##### Returns

Type | Description
--- | ---
Obj | the object to the underlying SDF/Cos object. If the NameTree.IsValid() returns false the SDF/Cos object is NULL.

#### GetValue(byte[])

Gets the value.

##### Declaration

    public Obj GetValue(byte[] key)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | key | the key

##### Returns

Type | Description
--- | ---
Obj | the value

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### IsValid()

Checks if is valid.

##### Declaration

    public bool IsValid()

##### Returns

Type | Description
--- | ---
bool | 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.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Put(byte[], Obj)

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

##### Declaration

    public void Put(byte[] key, Obj value)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | key | data buffer representing the key of the new entry.
Obj | value | the value

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Set(NameTree)

Sets value to the specified `NameTree`

##### Declaration

    public void Set(NameTree p)

##### Parameters

Type | Name | Description
--- | --- | ---
NameTree | p | `NameTree` object to set the value to

#### op_Assign(NameTree)

Assignment operator

##### Declaration

    public NameTree op_Assign(NameTree rhs)

##### Parameters

Type | Name | Description
--- | --- | ---
NameTree | rhs | `NameTree` object at the right of the operator

##### Returns

Type | Description
--- | ---
NameTree | `NameTree` object equal to the specified object

### Implements

IDisposable