class HexaPDF::Type::ObjectStream

Parent

Represents PDF type ObjStm, object streams.

An object stream is a stream that can hold multiple indirect objects. Since the objects are stored inside the stream, filters can be used to compress the stream content and therefore represent the indirect objects more compactly than would be possible otherwise.

How are Object Streams Used?

When an indirect object that resides in an object stream needs to be loaded, the object stream itself is parsed and loaded and parse_stream is invoked to get an ObjectStream::Data object representing the stored indirect objects. After that the requested indirect object itself is loaded and returned using this ObjectStream::Data object. From a user's perspective nothing changes when an object is located inside an object stream instead of directly in a PDF file.

The indirect objects initially stored in the object stream are automatically added to the list of to-be-stored objects when parse_stream is invoked. Additional objects can be assigned to the object stream via add_object or deleted from it via delete_object.

Before an object stream is written, it is necessary to invoke write_objects so that the to-be-stored objects are serialized to the stream. This is automatically done by the Writer. A user thus only has to define which objects should reside in the object stream.

However, only objects that can be written to the object stream are actually written. The other objects are deleted from the object stream (#delete_object) and written normally.

See PDF1.7 s7.5.7

Public Instance Methods

add_object(ref)

Adds the given object to the list of objects that should be stored in this object stream.

The ref argument can either be a reference or any PDF object.

delete_object(ref)

Deletes the given object from the list of objects that should be stored in this object stream.

The ref argument can either be a reference or a PDF object.

object_index(obj)

Returns the index into the array containing the to-be-stored objects for the given reference/PDF object.

parse_stream()

Parses the stream and returns an ObjectStream::Data object that can be used for retrieving the objects defined by this object stream.

The object references are also added to this object stream so that they are included when the object gets written.

write_objects(revision) → obj_to_stm_hash

Writes the added objects to the stream and returns a hash mapping all written objects to this object stream.

There are some reasons why an added object may not be stored in the stream:

  • It has a generation number other than 0.

  • It is a stream object.

  • It doesn't reside in the given Revision object.

Such objects are additionally deleted from the list of to-be-stored objects and are later written as indirect objects.