PdfArray Class

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

Represents a one-dimensional collection of PdfBasicObjects arranged sequentially.

public sealed class PdfArray : PdfBasicCollection, IList<PdfBasicObject>, ICollection<PdfBasicObject>, IEnumerable<PdfBasicObject>, IList, ICollection, IEnumerable
Public NotInheritable Class PdfArray
    Inherits PdfBasicCollection
    Implements IList(Of PdfBasicObject), ICollection(Of PdfBasicObject), IEnumerable(Of PdfBasicObject), IList, ICollection, IEnumerable
Inheritance:
PdfArray

Properties

Count

Gets the number of PdfBasicObjects contained in the PdfArray.

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

The number of PdfBasicObjects contained in the PdfArray.

Item[Int32]

Gets or sets the PdfBasicObject at the specified index.

public PdfBasicObject this[int index] { get; set; }
Public Property Item(index As Integer) As PdfBasicObject
Parameters
index
Int32

The zero-based index of the PdfBasicObject to get or set.

Property Value
PdfBasicObject

The PdfBasicObject at the specified index.

Exceptions
InvalidOperationException

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

ArgumentOutOfRangeException

index is less than 0 or index is equal to or greater than Count.

ArgumentNullException

value is null.

ArgumentException

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

ObjectType

Gets the Array value.

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

The Array value.

Overrides

Methods

Add(PdfBasicObject)

Adds a PdfBasicObject to the end of the PdfArray.

public void Add(PdfBasicObject item)
Public Sub Add(item As PdfBasicObject)
Parameters
item
PdfBasicObject

The PdfBasicObject to be added to the end of the PdfArray. The value cannot be null. Use Null value instead.

Exceptions
InvalidOperationException

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

ArgumentNullException

item is null.

ArgumentException

item is already contained in some other PdfBasicObject or is PdfStream or is the current PdfArray.

Clear()

Removes all PdfBasicObjects from the PdfArray.

public void Clear()
Public Sub Clear
Exceptions
InvalidOperationException

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

Clone(Boolean)

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

public PdfArray Clone(bool shallowIndirect)
Public Function Clone(shallowIndirect As Boolean) As PdfArray
Parameters
shallowIndirect
Boolean

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

Returns
PdfArray

A deep clone of the PdfArray.

Clone(Func<PdfIndirectObject, PdfBasicObject>)

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

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

A parameter that controls the cloning of PdfIndirectObjects.

Returns
PdfArray

A deep clone of the PdfArray.

Contains(PdfBasicObject)

Determines whether a PdfBasicObject is in the PdfArray.

public bool Contains(PdfBasicObject item)
Public Function Contains(item As PdfBasicObject) As Boolean
Parameters
item
PdfBasicObject

The PdfBasicObject to locate in the PdfArray.

Returns
Boolean

true if item is found in the PdfArray; otherwise, false.

CopyTo(PdfBasicObject[], Int32)

Copies the entire PdfArray to a compatible one-dimensional array, starting at the specified index of the target array.

public void CopyTo(PdfBasicObject[] array, int arrayIndex)
Public Sub CopyTo(array As PdfBasicObject(), arrayIndex As Integer)
Parameters
array
PdfBasicObject[]

The one-dimensional Array that is the destination of the PdfBasicObjects copied from PdfArray. The Array must have zero-based indexing.

arrayIndex
Int32

The zero-based index in array at which copying begins.

Exceptions
ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of PdfBasicObjects in the source PdfArray is greater than the available space from arrayIndex to the end of the destination array.

Create()

Creates a new instance of the PdfArray class.

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

A new instance of the PdfArray 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 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(Int32)

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

public static PdfArray Create(int capacity)
Public Shared Function Create(capacity As Integer) As PdfArray
Parameters
capacity
Int32

The number of PdfBasicObjects that the new array can initially store.

Returns
PdfArray

A new instance of the PdfArray 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 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
ArgumentOutOfRangeException

capacity is less than 0.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

Create<T>(T[])

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

public static PdfArray Create<T>(params T[] collection)
    where T : PdfBasicObject
Public Shared Function Create(Of T As PdfBasicObject)(ParamArray collection As T()) As PdfArray
Parameters
collection
T[]
Returns
PdfArray

A new instance of the PdfArray class that contains PdfBasicObjects copied from the specified collection.

Type Parameters
T

The type of PdfBasicObjects in the 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 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
ArgumentNullException

collection is null or one of the collection's element is null.

ArgumentException

One of the collection's element is already contained in some other PdfBasicObject or is PdfStream or is the current PdfArray.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

Create<T>(IEnumerable<T>)

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

public static PdfArray Create<T>(IEnumerable<T> collection)
    where T : PdfBasicObject
Public Shared Function Create(Of T As PdfBasicObject)(collection As IEnumerable(Of T)) As PdfArray
Parameters
collection
IEnumerable<T>

The collection whose PdfBasicObjects are copied to the new array.

Returns
PdfArray

A new instance of the PdfArray class that contains PdfBasicObjects copied from the specified collection.

Type Parameters
T

The type of PdfBasicObjects in the 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 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
ArgumentNullException

collection is null or one of the collection's element is null.

ArgumentException

One of the collection's element is already contained in some other PdfBasicObject or is PdfStream or is the current PdfArray.

See Also
GemBox.Pdf.Objects.IPdfAttachedObject

GetEnumerator()

Returns an enumerator that iterates through the PdfArray.

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

IndexOf(PdfBasicObject)

Searches for the specified PdfBasicObject and returns the zero-based index of the first occurrence within the entire PdfArray.

public int IndexOf(PdfBasicObject item)
Public Function IndexOf(item As PdfBasicObject) As Integer
Parameters
item
PdfBasicObject

The PdfBasicObject to locate in the PdfArray.

Returns
Int32

The zero-based index of the first occurrence of item within the entire PdfArray, if found; otherwise, –1.

Insert(Int32, PdfBasicObject)

Inserts a PdfBasicObject into the PdfArray at the specified index.

public void Insert(int index, PdfBasicObject item)
Public Sub Insert(index As Integer, item As PdfBasicObject)
Parameters
index
Int32

The zero-based index at which item should be inserted.

item
PdfBasicObject

The PdfBasicObject to insert. The value cannot be null. Use Null value instead.

Exceptions
InvalidOperationException

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

ArgumentOutOfRangeException

index is less than 0 or index is greater than Count.

ArgumentNullException

item is null.

ArgumentException

item is already contained in some other PdfBasicObject or is PdfStream or is the current PdfArray.

Remove(PdfBasicObject)

Removes the first occurrence of a specific PdfBasicObject from the PdfArray.

public bool Remove(PdfBasicObject item)
Public Function Remove(item As PdfBasicObject) As Boolean
Parameters
item
PdfBasicObject

The PdfBasicObject to remove from the PdfArray.

Returns
Boolean

true if item is successfully removed; otherwise, false. This method also returns false if item was not found in the PdfArray.

Exceptions
InvalidOperationException

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

RemoveAt(Int32)

Removes the PdfBasicObject at the specified index of the PdfArray.

public void RemoveAt(int index)
Public Sub RemoveAt(index As Integer)
Parameters
index
Int32

The zero-based index of the PdfBasicObject to remove.

Exceptions
InvalidOperationException

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

ArgumentOutOfRangeException

index is less than 0 or index is equal to or greater than Count.

ToString()

Returns a String that represents this PdfArray instance.

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

A String that represents this PdfArray 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).

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(Object)

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

(Inherited from PdfBasicContainer)

GetHashCode()

Returns a hash code for this PdfBasicContainer instance.

(Inherited from PdfBasicContainer)

Implements

See Also