class HexaPDF::PDFArray

Implementation of the PDF array type.

This is mainly done to provide automatic resolution of indirect object references when using the [] method. Therefore not all Array methods are implemented - use the value directly if other methods are needed.

See: PDF1.7 s7.3.6

Public Instance Methods

<<(data) click to toggle source

Append a value to the array.

# File lib/hexapdf/pdf_array.rb, line 104
def <<(data)
  value << data
end
array[index] → obj or nil click to toggle source
array[start, length] → new_array or nil
array[range] → new_array or nil

Returns the value at the given index, or a subarray using the given start and length, or a subarray specified by range.

This method should be used instead of direct access to a value because it provides some advantages:

  • References are automatically resolved.

  • Returns the native Ruby object for values with class HexaPDF::Object. However, all subclasses of HexaPDF::Object are returned as is (it makes no sense, for example, to return the hash that describes the Catalog instead of the Catalog object).

Note: Hash or Array values will always be returned as-is, i.e. not wrapped with Dictionary or PDFArray.

# File lib/hexapdf/pdf_array.rb, line 70
def [](arg1, arg2 = nil)
  data = arg2 ? value[arg1, arg2] : value[arg1]
  return if data.nil?

  if arg2 || arg1.kind_of?(Range)
    index = (arg2 ? arg1 : arg1.begin)
    data.map! {|item| process_entry(item, index).tap { index += 1 } }
  else
    process_entry(data, arg1)
  end
end
[]=(index, data) click to toggle source

Stores the data under the given index in the array.

If the current value for this index has the class HexaPDF::Object (and only this, no subclasses) and the given data has not (including subclasses), the data is stored inside the HexaPDF::Object.

# File lib/hexapdf/pdf_array.rb, line 87
def []=(index, data)
  if value[index].instance_of?(HexaPDF::Object) && !data.kind_of?(HexaPDF::Object) &&
      !data.kind_of?(HexaPDF::Reference)
    value[index].value = data
  else
    value[index] = data
  end
end
delete(object) click to toggle source

Deletes all values from the PDFArray that are equal to the given object.

Returns the last deleted item, or nil if no matching item is found.

# File lib/hexapdf/pdf_array.rb, line 121
def delete(object)
  value.delete(object)
end
delete_at(index) click to toggle source

Deletes the value at the given index.

# File lib/hexapdf/pdf_array.rb, line 114
def delete_at(index)
  value.delete_at(index)
end
each {|value| block} → array click to toggle source
each → Enumerator

Calls the given block once for every value of the array.

Note that the yielded value is already preprocessed like in [].

# File lib/hexapdf/pdf_array.rb, line 180
def each
  return to_enum(__method__) unless block_given?
  value.each_index {|index| yield(self[index]) }
  self
end
empty?() click to toggle source

Returns true if the array has no elements.

# File lib/hexapdf/pdf_array.rb, line 169
def empty?
  value.empty?
end
index(obj) → int or nil click to toggle source
index {|item| block } → int or nil
index → Enumerator

Returns the index of the first object such that object is == to obj, or, if a block is given, the index of the first object for which the block returns true.

# File lib/hexapdf/pdf_array.rb, line 158
def index(*obj, &block)
  find_index(*obj, &block)
end
insert(index, *objects) click to toggle source

Insert one or more values into the array at the given index.

# File lib/hexapdf/pdf_array.rb, line 109
def insert(index, *objects)
  value.insert(index, *objects)
end
length() click to toggle source

Returns the number of elements in the array.

# File lib/hexapdf/pdf_array.rb, line 163
def length
  value.length
end
Also aliased as: size
reject! {|item| block } → array or nil click to toggle source
reject! → Enumerator

Deletes all elements from the array for which the block returns true. If no changes were done, returns nil.

# File lib/hexapdf/pdf_array.rb, line 147
def reject!
  value.reject! {|item| yield(process_entry(item)) }
end
size()
Alias for: length
slice!(index) → obj or nil click to toggle source
slice!(start, length) → new_array or nil
slice!(range) → new_array or nil

Deletes the element(s) given by an index (and optionally a length) or by a range, and returns them or nil if the index is out of range.

# File lib/hexapdf/pdf_array.rb, line 132
def slice!(arg1, arg2 = nil)
  data = value.slice!(arg1, *arg2)
  if arg2 || arg1.kind_of?(Range)
    data.map! {|item| process_entry(item) }
  else
    process_entry(data)
  end
end
to_ary() click to toggle source

Returns an array containing the preprocessed values (like in []).

# File lib/hexapdf/pdf_array.rb, line 187
def to_ary
  each.to_a
end
values_at(*indices) click to toggle source

Returns the values at the given indices.

See [] for details

# File lib/hexapdf/pdf_array.rb, line 99
def values_at(*indices)
  indices.map! {|index| self[index] }
end

Private Instance Methods

process_entry(data, index = nil) click to toggle source

Processes the given array entry with index index.

# File lib/hexapdf/pdf_array.rb, line 203
def process_entry(data, index = nil)
  if data.kind_of?(HexaPDF::Reference)
    data = document.deref(data)
    value[index] = data if index
  end
  if data.instance_of?(HexaPDF::Object) || (data.kind_of?(HexaPDF::Object) && data.value.nil?)
    data = data.value
  end
  data
end