class HexaPDF::Type::XRefStream


Represents PDF type XRef, cross-reference streams.

A cross-reference stream is used as a more compact representation for an cross-reference section and trailer dictionary. The trailer dictionary is incorporated into the stream dictionary and the cross-reference section entries are stored in the stream itself, compressed to save space.

How are Cross-reference Streams Used?

Cross-reference stream objects are only used when parsing or writing a PDF document.

When a file is read and a cross-reference stream is found, it is loaded and its information is stored in a HexaPDF::Revision object. So from a user’s perspective nothing changes when a cross-reference stream instead of a cross-reference section and trailer is encountered.

This also means that all information stored in a cross-reference stream between parsing and writing is discarded when the PDF document gets written!

Upon writing a revision it is checked whether that revision contains a cross-reference stream object. If it does the cross-reference stream object is updated with the cross-reference section and trailer information and then written. Otherwise a normal cross-reference section plus trailer are written.

See: PDF2.0 s7.5.8

Field Definitions

NameType/Allowed ValuesRequiredDefault Value
FilterSymbol or HexaPDF::PDFArray or Arrayfalsenil
DecodeParmsHexaPDF::Dictionary or HexaPDF::PDFArray or Hash or Arrayfalsenil
FHexaPDF::Type::FileSpecification or Hash or Stringfalsenil
FFilterSymbol or HexaPDF::PDFArray or Arrayfalsenil
FDecodeParmsHexaPDF::Dictionary or HexaPDF::PDFArray or Hash or Arrayfalsenil
IndexHexaPDF::PDFArray or Arrayfalsenil
WHexaPDF::PDFArray or Arraytruenil

Public Instance Methods


Returns a hash with the entries that represent the file trailer part of the cross-reference stream’s dictionary.

See: Type::Trailer

update_with_xref_section_and_trailer(xref_section, trailer)

Makes this cross-reference stream represent the data in the given HexaPDF::XRefSection and Type::Trailer.

The xref_section needs to contain an entry for this cross-reference stream and it is necessary that this entry is the one with the highest byte position (for calculating the correct /W entry).

The given cross-reference section is not stored but only used to rewrite the associated stream to reflect the cross-reference section. The dictionary is updated with the information from the trailer and the needed entries for the cross-reference section.

If there are changes to the cross-reference section or trailer, this method has to be invoked again.


Returns an XRefSection that represents the content of this cross-reference stream.

Each invocation returns a new XRefSection object based on the current data in the associated stream and dictionary.