PdfDictionary Class

Namespace:
GemBox.Pdf.Objects
Assembly:
GemBox.Pdf.dll

Represents an associative table containing pairs of PdfBasicObjects, known as the PdfDictionaryEntry.

public sealed class PdfDictionary : PdfBasicCollection, IEnumerable<PdfDictionaryEntry>, IDictionary<PdfName, PdfBasicObject>, ICollection<KeyValuePair<PdfName, PdfBasicObject>>, IDictionary, ICollection, IReadOnlyDictionary<PdfName, PdfBasicObject>, IReadOnlyCollection<KeyValuePair<PdfName, PdfBasicObject>>, IEnumerable<KeyValuePair<PdfName, PdfBasicObject>>, IEnumerable
Public NotInheritable Class PdfDictionary
    Inherits PdfBasicCollection
    Implements IEnumerable(Of PdfDictionaryEntry), IDictionary(Of PdfName, PdfBasicObject), ICollection(Of KeyValuePair(Of PdfName, PdfBasicObject)), IDictionary, ICollection, IReadOnlyDictionary(Of PdfName, PdfBasicObject), IReadOnlyCollection(Of KeyValuePair(Of PdfName, PdfBasicObject)), IEnumerable(Of KeyValuePair(Of PdfName, PdfBasicObject)), IEnumerable
Inheritance:
System.Object
PdfDictionary
Implements
System.Collections.Generic.IEnumerable<PdfDictionaryEntry>
System.Collections.Generic.IDictionary<PdfName, PdfBasicObject>
System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<PdfName, PdfBasicObject>>
System.Collections.IDictionary
System.Collections.ICollection
System.Collections.Generic.IReadOnlyDictionary<PdfName, PdfBasicObject>
System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<PdfName, PdfBasicObject>>
System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<PdfName, PdfBasicObject>>
System.Collections.IEnumerable

Properties

Count

Gets the number of entries contained in the PdfDictionary.

public int Count { get; }
Public ReadOnly Property Count As Integer
Property Value
System.Int32

The number of entries contained in the PdfDictionary.

Item[PdfName]

Gets or sets the PdfBasicObject value associated with the specified PdfName key.

public PdfBasicObject this[PdfName key] { get; set; }
Public Property Item(key As PdfName) As PdfBasicObject
Parameters
key
PdfName

The PdfName key of the PdfBasicObject value to get or set.

Property Value
PdfBasicObject

The PdfBasicObject value associated with the specified PdfName key. If the specified key is not found, a get operation returns Null. A set operation overrides existing or adds a new entry with the specified PdfName key and PdfBasicObject value.

Exceptions
System.InvalidOperationException

The current PdfDictionary is read-only (IsReadOnly returns true).

System.ArgumentNullException

key or value is null.

System.ArgumentException

The value is already contained in some other PdfBasicObject or is PdfStream or is the current PdfDictionary.

Keys

Gets a collection containing the keys in the PdfDictionary.

public PdfDictionary.KeyCollection Keys { get; }
Public ReadOnly Property Keys As PdfDictionary.KeyCollection
Property Value
PdfDictionary.KeyCollection

A PdfDictionary.KeyCollection containing the keys in the PdfDictionary.

ObjectType

Gets the Dictionary value.

public override PdfBasicObjectType ObjectType { get; }
Public Overrides ReadOnly Property ObjectType As PdfBasicObjectType
Property Value
PdfBasicObjectType

The Dictionary value.

Overrides

Stream

Gets the PdfStream if this PdfDictionary is Dictionary or null otherwise.

public PdfStream Stream { get; }
Public ReadOnly Property Stream As PdfStream
Property Value
PdfStream

The PdfStream if this PdfDictionary is Dictionary or null otherwise.

See Also

Values

Gets a collection containing the values in the PdfDictionary.

public PdfDictionary.ValueCollection Values { get; }
Public ReadOnly Property Values As PdfDictionary.ValueCollection
Property Value
PdfDictionary.ValueCollection

A PdfDictionary.ValueCollection containing the values in the PdfDictionary.

Methods

Add(PdfName, PdfBasicObject)

Adds the specified key and value to the dictionary.

public void Add(PdfName key, PdfBasicObject value)
Public Sub Add(key As PdfName, value As PdfBasicObject)
Parameters
key
PdfName

The key of the entry to add.

value
PdfBasicObject

The value of the entry to add. The value cannot be null. Use Null value instead.

Exceptions
System.InvalidOperationException

The current PdfDictionary is read-only (IsReadOnly returns true).

System.ArgumentNullException

key or value is null.

System.ArgumentException

An entry with the same key already exists in the PdfDictionary or value is already contained in some other PdfBasicObject or is PdfStream or is the current PdfDictionary.

Clear()

Removes all keys and values from the PdfDictionary.

public void Clear()
Public Sub Clear
Exceptions
System.InvalidOperationException

The current PdfDictionary is read-only (IsReadOnly returns true).

Clone(Boolean)

Makes a deep clone of the PdfDictionary with optionally cloning descendant PdfIndirectObjects.

public PdfDictionary Clone(bool shallowIndirect)
Public Function Clone(shallowIndirect As Boolean) As PdfDictionary
Parameters
shallowIndirect
System.Boolean

if set to true descendant PdfIndirectObjects won't be cloned.

Returns
PdfDictionary

A deep clone of the PdfDictionary.

Clone(Func<PdfIndirectObject, PdfBasicObject>)

Makes a deep clone of the PdfDictionary with parameter that controls the cloning of PdfIndirectObjects.

public PdfDictionary Clone(Func<PdfIndirectObject, PdfBasicObject> indirectObjectClone)
Public Function Clone(indirectObjectClone As Func(Of PdfIndirectObject, PdfBasicObject)) As PdfDictionary
Parameters
indirectObjectClone
System.Func<PdfIndirectObject, PdfBasicObject>

A parameter that controls the cloning of PdfIndirectObjects.

Returns
PdfDictionary

A deep clone of the PdfDictionary.

ContainsKey(PdfName)

Determines whether the PdfDictionary contains the specified key.

public bool ContainsKey(PdfName key)
Public Function ContainsKey(key As PdfName) As Boolean
Parameters
key
PdfName

The key to locate in the PdfDictionary.

Returns
System.Boolean

true if the PdfDictionary contains an entry with the specified key; otherwise, false.

Exceptions
System.ArgumentNullException

key is null.

Create()

Creates a new instance of the PdfDictionary class.

public static PdfDictionary Create()
Public Shared Function Create As PdfDictionary
Returns
PdfDictionary

A new instance of the PdfDictionary class.

Remarks

GemBox.Pdf assembly doesn't publicly expose constructors for types assignable from PdfObject (except PdfDocument), PdfContentElement, and PdfBasicObject types. These types are instead instantiated either through static Create or other factory methods.

Reasons for this is to support either the current or future extensibility of the type without affecting backward compatibility and without using composition to reduce the number of object allocations.

For example, PdfNumber type is implemented as PdfInteger and internal PdfReal type. When using Create(Double) method, GemBox.Pdf assembly is able to create either PdfReal or PdfInteger, or return a cached instance of PdfInteger available for an implementation-defined interval of integers, thus reducing memory overhead.

PdfString and PdfName types have several internal implementations that reduce the number of System.Array allocations.

PdfArray type is currently implemented as a dynamic array. In the future, GemBox.Pdf assembly might provide an internal implementation that is immutable (without a need to use composition) to reduce memory overhead and optimize cloning operation.

PdfDictionary type is currently implemented as a hash table with a separate chaining collision resolution. In the future, GemBox.Pdf assembly might provide an internal implementation that uses dynamic array (without a need to use composition) if number of entries is small, to reduce memory overhead and, potentially, improve performance.

All these current and future implementations would not be possible in a backward compatible way (without unnecessary usage of composition) if constructors were publicly exposed.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

Create(PdfDictionaryEntry[])

Creates a new instance of the PdfDictionary class that contains PdfDictionaryEntry copied from the specified collection and has sufficient capacity to accommodate the number of entries copied.

public static PdfDictionary Create(params PdfDictionaryEntry[] collection)
Public Shared Function Create(ParamArray collection As PdfDictionaryEntry()) As PdfDictionary
Parameters
collection
PdfDictionaryEntry[]
Returns
PdfDictionary

A new instance of the PdfDictionary class that contains PdfDictionaryEntry copied from the specified collection.

Remarks

GemBox.Pdf assembly doesn't publicly expose constructors for types assignable from PdfObject (except PdfDocument), PdfContentElement, and PdfBasicObject types. These types are instead instantiated either through static Create or other factory methods.

Reasons for this is to support either the current or future extensibility of the type without affecting backward compatibility and without using composition to reduce the number of object allocations.

For example, PdfNumber type is implemented as PdfInteger and internal PdfReal type. When using Create(Double) method, GemBox.Pdf assembly is able to create either PdfReal or PdfInteger, or return a cached instance of PdfInteger available for an implementation-defined interval of integers, thus reducing memory overhead.

PdfString and PdfName types have several internal implementations that reduce the number of System.Array allocations.

PdfArray type is currently implemented as a dynamic array. In the future, GemBox.Pdf assembly might provide an internal implementation that is immutable (without a need to use composition) to reduce memory overhead and optimize cloning operation.

PdfDictionary type is currently implemented as a hash table with a separate chaining collision resolution. In the future, GemBox.Pdf assembly might provide an internal implementation that uses dynamic array (without a need to use composition) if number of entries is small, to reduce memory overhead and, potentially, improve performance.

All these current and future implementations would not be possible in a backward compatible way (without unnecessary usage of composition) if constructors were publicly exposed.

Exceptions
System.ArgumentNullException

collection is null or one of the collection's entries has null key or value.

System.ArgumentException

One of the collection's entries value is already contained in some other PdfBasicObject or is PdfStream or is the current PdfDictionary.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

Create(IEnumerable<PdfDictionaryEntry>)

Creates a new instance of the PdfDictionary class that contains PdfDictionaryEntry copied from the specified collection and has sufficient capacity to accommodate the number of entries copied.

public static PdfDictionary Create(IEnumerable<PdfDictionaryEntry> collection)
Public Shared Function Create(collection As IEnumerable(Of PdfDictionaryEntry)) As PdfDictionary
Parameters
collection
System.Collections.Generic.IEnumerable<PdfDictionaryEntry>

The collection whose PdfDictionaryEntry are copied to the new dictionary.

Returns
PdfDictionary

A new instance of the PdfDictionary class that contains PdfDictionaryEntry copied from the specified collection.

Remarks

GemBox.Pdf assembly doesn't publicly expose constructors for types assignable from PdfObject (except PdfDocument), PdfContentElement, and PdfBasicObject types. These types are instead instantiated either through static Create or other factory methods.

Reasons for this is to support either the current or future extensibility of the type without affecting backward compatibility and without using composition to reduce the number of object allocations.

For example, PdfNumber type is implemented as PdfInteger and internal PdfReal type. When using Create(Double) method, GemBox.Pdf assembly is able to create either PdfReal or PdfInteger, or return a cached instance of PdfInteger available for an implementation-defined interval of integers, thus reducing memory overhead.

PdfString and PdfName types have several internal implementations that reduce the number of System.Array allocations.

PdfArray type is currently implemented as a dynamic array. In the future, GemBox.Pdf assembly might provide an internal implementation that is immutable (without a need to use composition) to reduce memory overhead and optimize cloning operation.

PdfDictionary type is currently implemented as a hash table with a separate chaining collision resolution. In the future, GemBox.Pdf assembly might provide an internal implementation that uses dynamic array (without a need to use composition) if number of entries is small, to reduce memory overhead and, potentially, improve performance.

All these current and future implementations would not be possible in a backward compatible way (without unnecessary usage of composition) if constructors were publicly exposed.

Exceptions
System.ArgumentNullException

collection is null or one of the collection's entries has null key or value.

System.ArgumentException

One of the collection's entries value is already contained in some other PdfBasicObject or is PdfStream or is the current PdfDictionary.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

Create(Int32)

Creates a new instance of the PdfDictionary class that is empty and has the specified initial capacity.

public static PdfDictionary Create(int capacity)
Public Shared Function Create(capacity As Integer) As PdfDictionary
Parameters
capacity
System.Int32

The number of entries that the new dictionary can initially store.

Returns
PdfDictionary

A new instance of the PdfDictionary class that is empty and has the specified initial capacity.

Remarks

GemBox.Pdf assembly doesn't publicly expose constructors for types assignable from PdfObject (except PdfDocument), PdfContentElement, and PdfBasicObject types. These types are instead instantiated either through static Create or other factory methods.

Reasons for this is to support either the current or future extensibility of the type without affecting backward compatibility and without using composition to reduce the number of object allocations.

For example, PdfNumber type is implemented as PdfInteger and internal PdfReal type. When using Create(Double) method, GemBox.Pdf assembly is able to create either PdfReal or PdfInteger, or return a cached instance of PdfInteger available for an implementation-defined interval of integers, thus reducing memory overhead.

PdfString and PdfName types have several internal implementations that reduce the number of System.Array allocations.

PdfArray type is currently implemented as a dynamic array. In the future, GemBox.Pdf assembly might provide an internal implementation that is immutable (without a need to use composition) to reduce memory overhead and optimize cloning operation.

PdfDictionary type is currently implemented as a hash table with a separate chaining collision resolution. In the future, GemBox.Pdf assembly might provide an internal implementation that uses dynamic array (without a need to use composition) if number of entries is small, to reduce memory overhead and, potentially, improve performance.

All these current and future implementations would not be possible in a backward compatible way (without unnecessary usage of composition) if constructors were publicly exposed.

Exceptions
System.ArgumentOutOfRangeException

capacity is less than 0.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

GetEnumerator()

Returns an enumerator that iterates through the PdfDictionary.

public PdfDictionary.Enumerator GetEnumerator()
Public Function GetEnumerator As PdfDictionary.Enumerator
Returns
PdfDictionary.Enumerator

Remove(PdfName)

Removes the value with the specified key from the PdfDictionary.

public bool Remove(PdfName key)
Public Function Remove(key As PdfName) As Boolean
Parameters
key
PdfName

The key of the entry to remove.

Returns
System.Boolean

true if the key is found and the entry removed; otherwise, false. This method returns false if key is not found in the PdfDictionary.

Exceptions
System.InvalidOperationException

The current PdfDictionary is read-only (IsReadOnly returns true).

System.ArgumentNullException

key is null.

ToString()

Returns a System.String that represents this PdfDictionary instance.

public override string ToString()
Public Overrides Function ToString As String
Returns
System.String

A System.String that represents this PdfDictionary instance.

Overrides
Remarks

This method should be used primarily for debugging purposes and should be considered volatile (format of its return value might change in future versions).

TryGetValue(PdfName, out PdfBasicObject)

Gets the value associated with the specified key.

public bool TryGetValue(PdfName key, out PdfBasicObject value)
Public Function TryGetValue(key As PdfName, ByRef value As PdfBasicObject) As Boolean
Parameters
key
PdfName

The key of the value to get.

value
PdfBasicObject

When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the Null value.

Returns
System.Boolean

true if the PdfDictionary contains an entry with the specified key; otherwise, false.

Exceptions
System.ArgumentNullException

key is null.

Inherited Properties

Indirect

Gets the PdfIndirectObject if this PdfBasicContainer is Value or null otherwise.

(Inherited from PdfBasicContainer)

IsReadOnly

Gets a value indicating whether the PdfBasicContainer and all of its descendants are read-only.

(Inherited from PdfBasicContainer)

Null

Gets the single instance of Null type.

(Inherited from PdfBasicObject)

Inherited Methods

Equals(System.Object)

Determines whether the specified System.Object is equal to this PdfBasicContainer instance.

(Inherited from PdfBasicContainer)

GetHashCode()

Returns a hash code for this PdfBasicContainer instance.

(Inherited from PdfBasicContainer)

Implements

System.Collections.Generic.IEnumerable<T>
System.Collections.Generic.IDictionary<TKey, TValue>
System.Collections.Generic.ICollection<T>
System.Collections.IDictionary
System.Collections.ICollection
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue>
System.Collections.Generic.IReadOnlyCollection<T>
System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable

Examples

See Also