com.lowagie.text.pdf

## Class PdfArray

- java.lang.Object
- - com.lowagie.text.pdf.PdfObject
  - - com.lowagie.text.pdf.PdfArray

- Direct Known Subclasses:
    PdfBorderArray, PdfColor, PdfDashPattern, PdfDestination, PdfRectangle

      public class PdfArray
      extends PdfObject

  `PdfArray` is the PDF Array object.

  An array is a sequence of PDF objects. An array may contain a mixture of object types. An array is written as a left square bracket ([), followed by a sequence of objects, followed by a right square bracket (]).
  This object is described in the 'Portable Document Format Reference Manual version 1.7' section 3.2.5 (page 58).

  See Also:
    `PdfObject`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.ArrayList` | `arrayList` this is the actual array of PdfObjects

    - ### Fields inherited from class com.lowagie.text.pdf.PdfObject

      `ARRAY, BOOLEAN, bytes, DICTIONARY, INDIRECT, indRef, NAME, NOTHING, NULL, NUMBER, STREAM, STRING, TEXT_PDFDOCENCODING, TEXT_UNICODE, type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PdfArray()` Constructs an empty `PdfArray`-object.
    `PdfArray(java.util.ArrayList l)` Constructs a `PdfArray`, containing all elements of a specified `ArrayList`.
    `PdfArray(float[] values)` Constructs a `PdfArray`-object, containing all `float` values in a specified array.
    `PdfArray(int[] values)` Constructs a `PdfArray`-object, containing all `int` values in a specified array.
    `PdfArray(PdfArray array)` Constructs an `PdfArray`-object, containing all `PdfObject`s in a specified `PdfArray`.
    `PdfArray(PdfObject object)` Constructs an `PdfArray`-object, containing 1 `PdfObject`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(float[] values)` Adds an array of `float` values to end of the `PdfArray`.
    `boolean` | `add(int[] values)` Adds an array of `int` values to end of the `PdfArray`.
    `void` | `add(int index, PdfObject element)` Inserts the specified element at the specified position.
    `boolean` | `add(PdfObject object)` Adds a `PdfObject` to the end of the `PdfArray`.
    `void` | `addFirst(PdfObject object)` Inserts a `PdfObject` at the beginning of the `PdfArray`.
    `boolean` | `contains(PdfObject object)` Checks if the `PdfArray` already contains a certain `PdfObject`.
    `java.util.ArrayList` | `getArrayList()` Deprecated.
    `PdfArray` | `getAsArray(int idx)` Returns a `PdfObject` as a `PdfArray`, resolving indirect references.
    `PdfBoolean` | `getAsBoolean(int idx)` Returns a `PdfObject` as a `PdfBoolean`, resolving indirect references.
    `PdfDictionary` | `getAsDict(int idx)` Returns a `PdfObject` as a `PdfDictionary`, resolving indirect references.
    `PdfIndirectReference` | `getAsIndirectObject(int idx)` Returns a `PdfObject` as a `PdfIndirectReference`.
    `PdfName` | `getAsName(int idx)` Returns a `PdfObject` as a `PdfName`, resolving indirect references.
    `PdfNumber` | `getAsNumber(int idx)` Returns a `PdfObject` as a `PdfNumber`, resolving indirect references.
    `PdfStream` | `getAsStream(int idx)` Returns a `PdfObject` as a `PdfStream`, resolving indirect references.
    `PdfString` | `getAsString(int idx)` Returns a `PdfObject` as a `PdfString`, resolving indirect references.
    `PdfObject` | `getDirectObject(int idx)` Returns the `PdfObject` with the specified index, resolving a possible indirect reference to a direct object.
    `PdfObject` | `getPdfObject(int idx)` Returns the `PdfObject` with the specified index.
    `boolean` | `isEmpty()` Returns `true` if the array is empty.
    `java.util.ListIterator` | `listIterator()` Returns the list iterator for the array.
    `PdfObject` | `remove(int idx)` Remove the element at the specified position from the array.
    `PdfObject` | `set(int idx, PdfObject obj)` Overwrites a specified location of the array, returning the previous value
    `int` | `size()` Returns the number of entries in the array.
    `void` | `toPdf(PdfWriter writer, java.io.OutputStream os)` Writes the PDF representation of this `PdfArray` as an array of `byte` to the specified `OutputStream`.
    `java.lang.String` | `toString()` Returns a string representation of this `PdfArray`.

    - ### Methods inherited from class com.lowagie.text.pdf.PdfObject

      `canBeInObjStm, getBytes, getIndRef, isArray, isBoolean, isDictionary, isIndirect, isName, isNull, isNumber, isStream, isString, length, setContent, setIndRef, type`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### arrayList

          protected java.util.ArrayList arrayList

      this is the actual array of PdfObjects

  - ### Constructor Detail

    - #### PdfArray

          public PdfArray()

      Constructs an empty `PdfArray`-object.

    - #### PdfArray

          public PdfArray(PdfObject object)

      Constructs an `PdfArray`-object, containing 1 `PdfObject`.
      Parameters:
        `object` - a `PdfObject` that has to be added to the array

    - #### PdfArray

          public PdfArray(float[] values)

      Constructs a `PdfArray`-object, containing all `float` values in a specified array. The `float` values are internally converted to `PdfNumber` objects.
      Parameters:
        `values` - an array of `float` values to be added

    - #### PdfArray

          public PdfArray(int[] values)

      Constructs a `PdfArray`-object, containing all `int` values in a specified array. The `int` values are internally converted to `PdfNumber` objects.
      Parameters:
        `values` - an array of `int` values to be added

    - #### PdfArray

          public PdfArray(java.util.ArrayList l)

      Constructs a `PdfArray`, containing all elements of a specified `ArrayList`.
      Parameters:
        `l` - an `ArrayList` with `PdfObject`s to be added to the array
      Throws:
        `java.lang.ClassCastException` - if the `ArrayList` contains something that isn't a `PdfObject`
      Since:
        2.1.3

    - #### PdfArray

          public PdfArray(PdfArray array)

      Constructs an `PdfArray`-object, containing all `PdfObject`s in a specified `PdfArray`.
      Parameters:
        `array` - a `PdfArray` to be added to the array

  - ### Method Detail

    - #### toPdf

          public void toPdf(PdfWriter writer,
                   java.io.OutputStream os)
                     throws java.io.IOException

      Writes the PDF representation of this `PdfArray` as an array of `byte` to the specified `OutputStream`.
      Overrides:
        `toPdf` in class `PdfObject`
      Parameters:
        `writer` - for backwards compatibility
        `os` - the `OutputStream` to write the bytes to.
      Throws:
        `java.io.IOException`

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this `PdfArray`. The string representation consists of a list of all `PdfObject`s contained in this `PdfArray`, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (comma and space).
      Overrides:
        `toString` in class `PdfObject`
      Returns:
        the string representation of this `PdfArray`

    - #### set

          public PdfObject set(int idx,
                      PdfObject obj)

      Overwrites a specified location of the array, returning the previous value
      Parameters:
        `idx` - The index of the element to be overwritten
        `obj` - new value for the specified index
      Returns:
        the previous value
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the specified position doesn't exist
      Since:
        2.1.5

    - #### remove

          public PdfObject remove(int idx)

      Remove the element at the specified position from the array. Shifts any subsequent elements to the left (subtracts one from their indices).
      Parameters:
        `idx` - The index of the element to be removed.
      Throws:
        `java.lang.IndexOutOfBoundsException` - the specified position doesn't exist
      Since:
        2.1.5

    - #### getArrayList

          public java.util.ArrayList getArrayList()

      Deprecated.
      Get the internal arrayList for this PdfArray. Not Recommended.
      Returns:
        the internal ArrayList. Naughty Naughty.

    - #### size

          public int size()

      Returns the number of entries in the array.
      Returns:
        the size of the ArrayList

    - #### isEmpty

          public boolean isEmpty()

      Returns `true` if the array is empty.
      Returns:
        `true` if the array is empty
      Since:
        2.1.5

    - #### add

          public boolean add(PdfObject object)

      Adds a `PdfObject` to the end of the `PdfArray`. The `PdfObject` will be the last element.
      Parameters:
        `object` - `PdfObject` to add
      Returns:
        always `true`

    - #### add

          public boolean add(float[] values)

      Adds an array of `float` values to end of the `PdfArray`. The values will be the last elements. The `float` values are internally converted to `PdfNumber` objects.
      Parameters:
        `values` - An array of `float` values to add
      Returns:
        always `true`

    - #### add

          public boolean add(int[] values)

      Adds an array of `int` values to end of the `PdfArray`. The values will be the last elements. The `int` values are internally converted to `PdfNumber` objects.
      Parameters:
        `values` - An array of `int` values to add
      Returns:
        always `true`

    - #### add

          public void add(int index,
                 PdfObject element)

      Inserts the specified element at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Parameters:
        `index` - The index at which the specified element is to be inserted
        `element` - The element to be inserted
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the specified index is larger than the last position currently set, plus 1.
      Since:
        2.1.5

    - #### addFirst

          public void addFirst(PdfObject object)

      Inserts a `PdfObject` at the beginning of the `PdfArray`. The `PdfObject` will be the first element, any other elements will be shifted to the right (adds one to their indices).
      Parameters:
        `object` - The `PdfObject` to add

    - #### contains

          public boolean contains(PdfObject object)

      Checks if the `PdfArray` already contains a certain `PdfObject`.
      Parameters:
        `object` - The `PdfObject` to check
      Returns:
        `true`

    - #### listIterator

          public java.util.ListIterator listIterator()

      Returns the list iterator for the array.
      Returns:
        a ListIterator

    - #### getPdfObject

          public PdfObject getPdfObject(int idx)

      Returns the `PdfObject` with the specified index. A possible indirect references is not resolved, so the returned `PdfObject` may be either a direct object or an indirect reference, depending on how the object is stored in the `PdfArray`.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        A `PdfObject`

    - #### getDirectObject

          public PdfObject getDirectObject(int idx)

      Returns the `PdfObject` with the specified index, resolving a possible indirect reference to a direct object. Thus this method will never return a `PdfIndirectReference` object.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        A direct `PdfObject` or `null`

    - #### getAsDict

          public PdfDictionary getAsDict(int idx)

      Returns a `PdfObject` as a `PdfDictionary`, resolving indirect references. The object corresponding to the specified index is retrieved and resolvedto a direct object. If it is a `PdfDictionary`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfDictionary` object, or `null`

    - #### getAsArray

          public PdfArray getAsArray(int idx)

      Returns a `PdfObject` as a `PdfArray`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfArray`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfArray` object, or `null`

    - #### getAsStream

          public PdfStream getAsStream(int idx)

      Returns a `PdfObject` as a `PdfStream`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfStream`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfStream` object, or `null`

    - #### getAsString

          public PdfString getAsString(int idx)

      Returns a `PdfObject` as a `PdfString`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfString`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfString` object, or `null`

    - #### getAsNumber

          public PdfNumber getAsNumber(int idx)

      Returns a `PdfObject` as a `PdfNumber`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfNumber`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfNumber` object, or `null`

    - #### getAsName

          public PdfName getAsName(int idx)

      Returns a `PdfObject` as a `PdfName`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfName`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfName` object, or `null`

    - #### getAsBoolean

          public PdfBoolean getAsBoolean(int idx)

      Returns a `PdfObject` as a `PdfBoolean`, resolving indirect references. The object corresponding to the specified index is retrieved and resolved to a direct object. If it is a `PdfBoolean`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfBoolean` object, or `null`

    - #### getAsIndirectObject

          public PdfIndirectReference getAsIndirectObject(int idx)

      Returns a `PdfObject` as a `PdfIndirectReference`. The object corresponding to the specified index is retrieved. If it is a `PdfIndirectReference`, it is cast down and returned as such. Otherwise `null` is returned.
      Parameters:
        `idx` - The index of the `PdfObject` to be returned
      Returns:
        the corresponding `PdfIndirectReference` object, or `null`