Struct TextExtractor 

pub struct TextExtractor<'doc> { /* private fields */ }

Text extractor that processes content streams.

This structure maintains the graphics state stack and font information while processing operators to extract positioned text.

The extractor can work in two modes:

• Span mode (default): Extracts complete text strings as PDF provides them (PDF spec compliant)
• Character mode: Extracts individual characters (for special use cases)

Implementations

impl<'doc> TextExtractor<'doc>

pub fn new() -> Self

Create a new text extractor with default configuration.

Examples

use pdf_oxide::extractors::TextExtractor;

let extractor = TextExtractor::new();

pub fn with_config(config: TextExtractionConfig) -> Self

Create a new text extractor with custom configuration.

Arguments

• config - Configuration for text extraction heuristics

Examples

use pdf_oxide::extractors::{TextExtractor, TextExtractionConfig};

// Use custom space threshold
let config = TextExtractionConfig::with_space_threshold(-80.0);
let extractor = TextExtractor::with_config(config);

pub fn set_page_index(&mut self, page_index: u32)

Stamp this extractor with the page index it is processing.

Used so spans (and the lookup keys for /ActualText) carry the correct McidScope::Page(page_index) when the extractor is not currently inside a Form XObject.

pub fn with_merging_config(self, merging_config: SpanMergingConfig) -> Self

Create a new text extractor with custom merging configuration.

This allows fine-tuning how adjacent spans are merged and when spaces are inserted, useful for documents with unusual spacing patterns.

Arguments

• merging_config - Configuration for span merging thresholds

Examples

use pdf_oxide::extractors::{TextExtractor, SpanMergingConfig};

// Use aggressive space insertion for dense layouts
let config = SpanMergingConfig::aggressive();
let extractor = TextExtractor::new().with_merging_config(config);

pub fn set_resources(&mut self, resources: Object)

Set the resources dictionary for this extractor.

This allows the extractor to access XObjects and fonts during extraction.

pub fn set_document(&mut self, document: &'doc PdfDocument)

Set the document reference for loading XObjects.

pub fn take_mc_actualtext_mcids(&mut self) -> HashSet<u32>

Take ownership of the set of MCIDs whose marked-content sequence carried an inline /ActualText property on this extraction.

The set is observed by the BDC handler; this method drains it out so the document layer can stash it on a per-page side channel for the struct-tree-scope ActualText applier.

pub fn set_excluded_layers(&mut self, layers: HashSet<String>)

Set layer names (Optional Content Groups) to exclude from extraction.

Content within BDC/EMC scopes tagged “OC” whose OCG /Name matches one of the provided names will be suppressed during text extraction.

pub fn set_excluded_inks(&mut self, inks: HashSet<String>)

Set ink / separation names to exclude from extraction.

When the fill color space is a Separation or DeviceN whose ink name(s) intersect with any of the provided names, subsequent text is suppressed until the color space changes to a non-excluded one.

DeviceN behavior: For DeviceN color spaces (e.g. [/DeviceN [/Cyan /SpotGold] ...]), text is suppressed if ANY ink in the array matches — even process colors sharing the DeviceN definition. This is because tint values are not evaluated during extraction.

pub fn set_document_ptr(&mut self, doc: &'doc PdfDocument)

Convenience wrapper: identical to set_document.

pub fn prepare_for_span_extraction(&mut self)

Prepare for span extraction mode (same setup as extract_text_spans preamble).

pub fn execute_operator_public(&mut self, op: Operator) -> Result<()>

Public wrapper for execute_operator (normally private).

pub fn flush_public(&mut self) -> Result<()>

Public wrapper for flush_tj_span_buffer (normally private).

pub fn add_font(&mut self, name: String, font: FontInfo)

Add a font to the extractor.

Fonts must be added before processing content streams that reference them.

Arguments

• name - The font resource name (e.g., “F1”, “TT1”)
• font - The font information

Examples

let mut extractor = TextExtractor::new();
extractor.add_font("F1".to_string(), font);

pub fn get_font_set(&self) -> Vec<(String, Arc<FontInfo>)>

Return the current font set for caching purposes.

pub fn share_truetype_cmaps(&mut self)

Share TrueType cmap tables between fonts with matching base font names. When a CIDFontType2 Identity-H font has no truetype_cmap, borrow from another font on the same page with the same base font name (ignoring subset prefix).

pub fn extract_text_spans( &mut self, content_stream: &[u8], ) -> Result<Vec<TextSpan>>

Extract text from a content stream.

Parses the content stream and executes operators to extract positioned characters with Unicode mappings and font information.

Arguments

• content_stream - The raw content stream data (should be decoded first)

Returns

A vector of TextChar structures containing positioned characters.

Errors

Returns an error if the content stream cannot be parsed.

Examples

let mut extractor = TextExtractor::new();
let chars = extractor.extract(content_data)?;
println!("Extracted {} characters", chars.len());

Extract text as complete spans (PDF spec compliant).

This is the recommended method for text extraction. It extracts complete text strings as the PDF provides them via Tj/TJ operators, following the PDF specification ISO 32000-1:2008.

Benefits

• Avoids overlapping character issues
• Preserves PDF’s text positioning intent
• More robust for complex layouts
• Matches industry best practices

Arguments

• content_stream - The PDF content stream data

Returns

Vector of TextSpan objects in reading order

pub fn extract(&mut self, content_stream: &[u8]) -> Result<Vec<TextChar>>

Extract individual characters from a PDF content stream.

This is a low-level method that extracts characters one by one. For most use cases, prefer using extract_text_spans() which groups characters into text spans according to PDF semantics.

pub fn extract_owned(&mut self, content_stream: &[u8]) -> Result<Vec<TextChar>>

Same extraction as Self::extract, but hands the buffer over instead of copying it. Every TextChar owns a font_name String, so extract’s clone re-allocates once per glyph — measurable on long documents. Leaves self.chars empty, so callers that read char_count/chars afterwards must keep using Self::extract.

pub fn char_count(&self) -> usize

Get the number of extracted characters.

pub fn clear(&mut self)

Clear all extracted characters.

Trait Implementations

impl<'doc> Debug for TextExtractor<'doc>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'doc> Default for TextExtractor<'doc>

fn default() -> Self

Returns the “default value” for a type.