pdftract/notes/bf-e4uvb-child-1-cmap-search.md

CMAP Entry Creation Code Locations

Search Date

2026-07-05

Summary

This document identifies all locations in the pdftract codebase where CMAP (Character Map) entries are created for glyphs.

1. ToUnicode CMap Entries (Character Code → Unicode Mappings)

Primary Entry Point

File: /home/coding/pdftract/crates/pdftract-core/src/font/cmap.rs

Function: ToUnicodeMap::add_mapping()
Lines: 86-88

/// Add a single mapping from source bytes to destination chars.
///
/// MARKER: CMAP entry creation point - this is where individual ToUnicode
/// mappings are stored. Called by parse_beginbfchar() and parse_beginbfrange().
/// See notes/bf-e4uvb-child-1.md for documentation.
pub fn add_mapping(&mut self, src: Vec<u8>, dst: Vec<char>) {
    self.mappings.insert(src, dst);
}

Call Sites

a) Single-Character Mappings (beginbfchar)

Function: CMapParser::parse_beginbfchar()
Line: 209
Purpose: Parses beginbfchar...endbfchar blocks for single character code → Unicode mappings

b) Range Mappings - Contiguous Form

Function: CMapParser::parse_beginbfrange()
Line: 292
Purpose: Expands contiguous ranges <lo> <hi> <dst> where each code in range maps to incrementing Unicode values

c) Range Mappings - Explicit Array Form

Function: CMapParser::parse_beginbfrange()
Line: 279
Purpose: Expands ranges with explicit arrays <lo> <hi> [<d0> <d1> ...] where each destination is specified individually

Parser Entry Point

Function: CMapParser::parse()
Lines: 136-185
Purpose: Main parser that calls parse_beginbfchar() and parse_beginbfrange() when encountering those keywords

---

2. Codespace Range Entries (Byte-Width Boundaries)

Primary Entry Point

File: /home/coding/pdftract/crates/pdftract-core/src/cmap/codespace.rs

Function: CodespaceParser::parse_codespace_block()
Lines: 282-357

Creation Point: Line 350

ranges.push(CodespaceRange::new(lo_arr, hi_arr, width as u8));

Purpose

Parses begincodespacerange...endcodespacerange blocks to define valid byte-width boundaries for multi-byte CJK encodings. Each CodespaceRange defines:

• lo: Low bound (inclusive)
• hi: High bound (inclusive)
• width: Byte width (1, 2, 3, or 4)

Constructor

Function: CodespaceRange::new()
Lines: 56-60
Purpose: Creates a single codespace range with validation

Parser Entry Point

Function: CodespaceParser::parse()
Lines: 233-279
Purpose: Main parser that calls parse_codespace_block() when encountering begincodespacerange keyword

---

3. Type1 Font Encoding Differences (Character Code → Glyph Name)

Primary Entry Point

File: /home/coding/pdftract/crates/pdftract-core/src/font/encoding.rs

Function: DifferencesOverlay::parse()
Lines: 163-209

Creation Point: Lines 196-199

PdfObject::Name(name) => {
    // Assign this name to the current cursor position
    // MARKER: CMAP entry creation point - Type1 font encoding differences.
    // See notes/bf-e4uvb-child-1.md for documentation.
    if cursor <= 255 {
        overlay.entries.push((cursor as u8, Arc::clone(name)));
    }
    cursor = cursor.saturating_add(1);
}

Purpose

Parses /Differences arrays from Type1 font encodings to create sparse overlays that override base encodings. Format: [n /Name1 /Name2 ... m /OtherName ...] where integers reset the position and subsequent names are assigned to consecutive codes.

Data Structure

Type: DifferencesOverlay
Lines: 129-232
Purpose: Stores sparse list of (code, glyph_name) overrides

---

File Path Summary

Purpose	File Path	Function	Line Range
ToUnicode add_mapping	crates/pdftract-core/src/font/cmap.rs	ToUnicodeMap::add_mapping()	86-88
ToUnicode bfchar call	crates/pdftract-core/src/font/cmap.rs	parse_beginbfchar()	209
ToUnicode bfrange explicit	crates/pdftract-core/src/font/cmap.rs	parse_beginbfrange()	279
ToUnicode bfrange contiguous	crates/pdftract-core/src/font/cmap.rs	parse_beginbfrange()	292
Codespace range creation	crates/pdftract-core/src/cmap/codespace.rs	parse_codespace_block()	350
Type1 differences overlay	crates/pdftract-core/src/font/encoding.rs	DifferencesOverlay::parse()	196-199

---

Related Files (Reference)

• Codespace module: /home/coding/pdftract/crates/pdftract-core/src/cmap/mod.rs
• Tokenizer: /home/coding/pdftract/crates/pdftract-core/src/cmap/tokenize.rs
• Font resolver: /home/coding/pdftract/crates/pdftract-core/src/font/resolver.rs
• Embedded fonts: /home/coding/pdftract/crates/pdftract-core/src/font/embedded.rs
• Predefined CMap: /home/coding/pdftract/crates/pdftract-core/src/font/predefined_cmap.rs

---

Test Files

• ToUnicode tests: crates/pdftract-core/src/font/cmap.rs (lines 507-732)
• Codespace tests: crates/pdftract-core/src/cmap/codespace.rs (lines 634-898)
• Encoding tests: crates/pdftract-core/src/font/encoding.rs (lines 371-669)

---

Bead Reference

This search was performed for bead bf-4hwap (explore task for CMAP entry creation).