Skip to main content

read_fonts/ps/cff/
charset.rs

1//! CFF charset support.
2
3use crate::ps::string::Sid;
4use crate::{FontData, FontRead, GlyphId};
5
6#[doc(inline)]
7pub use super::v1::{
8    CharsetFormat0 as Format0, CharsetFormat1 as Format1, CharsetFormat2 as Format2,
9    CharsetRange1 as Range1, CharsetRange2 as Range2, CustomCharset,
10};
11
12/// Character set for mapping from glyph to string identifiers.
13///
14/// See <https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf#page=21>
15#[derive(Clone)]
16pub struct Charset<'a> {
17    kind: CharsetKind<'a>,
18    num_glyphs: u32,
19}
20
21impl<'a> Charset<'a> {
22    pub fn new(cff_data: FontData<'a>, charset_offset: usize, num_glyphs: u32) -> Option<Self> {
23        let kind = match charset_offset {
24            0 => CharsetKind::IsoAdobe,
25            1 => CharsetKind::Expert,
26            2 => CharsetKind::ExpertSubset,
27            _ => {
28                let data = cff_data.split_off(charset_offset)?;
29                CharsetKind::Custom(CustomCharset::read(data).ok()?)
30            }
31        };
32        Some(Self { kind, num_glyphs })
33    }
34
35    pub fn kind(&self) -> &CharsetKind<'a> {
36        &self.kind
37    }
38
39    pub fn num_glyphs(&self) -> u32 {
40        self.num_glyphs
41    }
42
43    /// Returns the string identifier for the given glyph identifier.
44    pub fn string_id(&self, glyph_id: GlyphId) -> Option<Sid> {
45        let gid = glyph_id.to_u32();
46        if gid >= self.num_glyphs {
47            return None;
48        }
49        match &self.kind {
50            CharsetKind::IsoAdobe => {
51                // The ISOAdobe charset is an identity mapping of gid->sid up
52                // to 228 entries
53                // <https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf#page=45>
54                if gid <= 228 {
55                    Some(Sid::new(gid as u16))
56                } else {
57                    None
58                }
59            }
60            CharsetKind::Expert => EXPERT_CHARSET.get(gid as usize).copied().map(Sid::new),
61            CharsetKind::ExpertSubset => EXPERT_SUBSET_CHARSET
62                .get(gid as usize)
63                .copied()
64                .map(Sid::new),
65            CharsetKind::Custom(custom) => match custom {
66                CustomCharset::Format0(fmt) => fmt.string_id(glyph_id),
67                CustomCharset::Format1(fmt) => fmt.string_id(glyph_id),
68                CustomCharset::Format2(fmt) => fmt.string_id(glyph_id),
69            },
70        }
71    }
72
73    /// Returns the glyph identifier for the given string identifier.
74    ///
75    /// Returns `None` if no glyph of the font has the string identifier.
76    pub fn glyph_id(&self, string_id: Sid) -> Option<GlyphId> {
77        // The charset only describes the font's glyphs, so data past them is
78        // not part of it.
79        self.glyph_id_unbounded(string_id)
80            .filter(|gid| gid.to_u32() < self.num_glyphs)
81    }
82
83    fn glyph_id_unbounded(&self, string_id: Sid) -> Option<GlyphId> {
84        let sid = string_id.to_u16();
85        match &self.kind {
86            CharsetKind::IsoAdobe => {
87                // The ISOAdobe charset is an identity mapping of gid->sid up
88                // to 228 entries
89                // <https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf#page=45>
90                if sid <= 228 {
91                    Some(GlyphId::from(sid))
92                } else {
93                    None
94                }
95            }
96            CharsetKind::Expert => EXPERT_CHARSET
97                .iter()
98                .position(|n| *n == sid)
99                .map(|pos| GlyphId::new(pos as u32)),
100            CharsetKind::ExpertSubset => EXPERT_SUBSET_CHARSET
101                .iter()
102                .position(|n| *n == sid)
103                .map(|pos| GlyphId::new(pos as u32)),
104            CharsetKind::Custom(custom) => match custom {
105                CustomCharset::Format0(fmt) => fmt.glyph_id(string_id),
106                CustomCharset::Format1(fmt) => fmt.glyph_id(string_id),
107                CustomCharset::Format2(fmt) => fmt.glyph_id(string_id),
108            },
109        }
110    }
111
112    /// Returns an iterator over all of the glyph and string identifier
113    /// mappings.
114    pub fn iter(&self) -> Iter<'a> {
115        match &self.kind {
116            CharsetKind::IsoAdobe
117            | CharsetKind::Expert
118            | CharsetKind::ExpertSubset
119            | CharsetKind::Custom(CustomCharset::Format0(_)) => {
120                Iter(IterKind::Simple(self.clone(), 0))
121            }
122            CharsetKind::Custom(CustomCharset::Format1(custom)) => Iter(IterKind::Custom1(
123                RangeIter::new(custom.ranges(), self.num_glyphs),
124            )),
125            CharsetKind::Custom(CustomCharset::Format2(custom)) => Iter(IterKind::Custom2(
126                RangeIter::new(custom.ranges(), self.num_glyphs),
127            )),
128        }
129    }
130}
131
132/// Predefined and custom character sets.
133#[derive(Clone)]
134pub enum CharsetKind<'a> {
135    IsoAdobe,
136    Expert,
137    ExpertSubset,
138    Custom(CustomCharset<'a>),
139}
140
141impl Format0<'_> {
142    fn string_id(&self, glyph_id: GlyphId) -> Option<Sid> {
143        let gid = glyph_id.to_u32() as usize;
144        if gid == 0 {
145            Some(Sid::new(0))
146        } else {
147            self.glyph().get(gid - 1).map(|id| Sid::new(id.get()))
148        }
149    }
150
151    fn glyph_id(&self, string_id: Sid) -> Option<GlyphId> {
152        if string_id.to_u16() == 0 {
153            return Some(GlyphId::NOTDEF);
154        }
155        self.glyph()
156            .iter()
157            .position(|n| n.get() == string_id.to_u16())
158            .map(|n| GlyphId::from((n as u16).saturating_add(1)))
159    }
160}
161
162impl Format1<'_> {
163    fn string_id(&self, glyph_id: GlyphId) -> Option<Sid> {
164        string_id_from_ranges(self.ranges(), glyph_id)
165    }
166
167    fn glyph_id(&self, string_id: Sid) -> Option<GlyphId> {
168        glyph_id_from_ranges(self.ranges(), string_id)
169    }
170}
171
172impl Format2<'_> {
173    fn string_id(&self, glyph_id: GlyphId) -> Option<Sid> {
174        string_id_from_ranges(self.ranges(), glyph_id)
175    }
176
177    fn glyph_id(&self, string_id: Sid) -> Option<GlyphId> {
178        glyph_id_from_ranges(self.ranges(), string_id)
179    }
180}
181
182fn string_id_from_ranges<T: CharsetRange>(ranges: &[T], glyph_id: GlyphId) -> Option<Sid> {
183    let mut gid = glyph_id.to_u32();
184    // The notdef glyph isn't explicitly mapped so we need to special case
185    // it and add -1 and +1 at a few places when processing ranges
186    if gid == 0 {
187        return Some(Sid::new(0));
188    }
189    gid -= 1;
190    let mut end = 0u32;
191    // Each range provides the string ids for `n_left + 1` glyphs with
192    // the sequence of string ids starting at `first`. Since the counts
193    // are cumulative, we must scan them all in order until we find
194    // the range that contains our requested glyph.
195    for range in ranges {
196        let next_end = range
197            .n_left()
198            .checked_add(1)
199            .and_then(|span| end.checked_add(span))?;
200        if gid < next_end {
201            return (gid - end)
202                .checked_add(range.first())
203                .and_then(|sid| sid.try_into().ok())
204                .map(Sid::new);
205        }
206        end = next_end;
207    }
208    None
209}
210
211fn glyph_id_from_ranges<T: CharsetRange>(ranges: &[T], string_id: Sid) -> Option<GlyphId> {
212    let sid = string_id.to_u16() as u32;
213    // notdef glyph is not explicitly mapped
214    if sid == 0 {
215        return Some(GlyphId::NOTDEF);
216    }
217    let mut gid = 1u32;
218    for range in ranges {
219        let first = range.first();
220        let n_left = range.n_left();
221        let last = first.checked_add(n_left)?;
222        if first <= sid && sid <= last {
223            gid = gid.checked_add(sid - first)?;
224            return Some(GlyphId::new(gid));
225        }
226        gid = n_left
227            .checked_add(1)
228            .and_then(|span| gid.checked_add(span))?;
229    }
230    None
231}
232
233/// Trait that unifies ranges for formats 1 and 2 so that we can implement
234/// the tricky search logic once.
235trait CharsetRange {
236    fn first(&self) -> u32;
237    fn n_left(&self) -> u32;
238}
239
240impl CharsetRange for Range1 {
241    fn first(&self) -> u32 {
242        self.first.get() as u32
243    }
244
245    fn n_left(&self) -> u32 {
246        self.n_left as u32
247    }
248}
249
250impl CharsetRange for Range2 {
251    fn first(&self) -> u32 {
252        self.first.get() as u32
253    }
254
255    fn n_left(&self) -> u32 {
256        self.n_left.get() as u32
257    }
258}
259
260/// Iterator over the glyph and string identifier mappings in a character set.
261#[derive(Clone)]
262pub struct Iter<'a>(IterKind<'a>);
263
264impl Iterator for Iter<'_> {
265    type Item = (GlyphId, Sid);
266
267    fn next(&mut self) -> Option<Self::Item> {
268        match &mut self.0 {
269            IterKind::Simple(charset, cur) => {
270                let gid = GlyphId::new(*cur);
271                let sid = charset.string_id(gid)?;
272                *cur = cur.checked_add(1)?;
273                Some((gid, sid))
274            }
275            IterKind::Custom1(custom) => custom.next(),
276            IterKind::Custom2(custom) => custom.next(),
277        }
278    }
279}
280
281#[derive(Clone)]
282enum IterKind<'a> {
283    /// Predefined sets and custom format 0 are just array lookups so we use
284    /// the builtin mapping function.
285    Simple(Charset<'a>, u32),
286    Custom1(RangeIter<'a, Range1>),
287    Custom2(RangeIter<'a, Range2>),
288}
289
290/// Custom iterator for range based formats.
291///
292/// Each individual lookup requires a linear scan through the ranges so this
293/// provides a more efficient code path for iteration.
294#[derive(Clone)]
295struct RangeIter<'a, T> {
296    ranges: std::slice::Iter<'a, T>,
297    num_glyphs: u32,
298    gid: u32,
299    first: u32,
300    end: u32,
301    prev_end: u32,
302}
303
304impl<'a, T> RangeIter<'a, T>
305where
306    T: CharsetRange,
307{
308    fn new(ranges: &'a [T], num_glyphs: u32) -> Self {
309        let mut ranges = ranges.iter();
310        let (first, end) = next_range(&mut ranges).unwrap_or_default();
311        Self {
312            ranges,
313            num_glyphs,
314            gid: 0,
315            first,
316            end,
317            prev_end: 0,
318        }
319    }
320
321    fn next(&mut self) -> Option<(GlyphId, Sid)> {
322        if self.gid >= self.num_glyphs {
323            return None;
324        }
325        // The notdef glyph isn't explicitly mapped so we need to special case
326        // it and add -1 and +1 at a few places when processing ranges
327        if self.gid == 0 {
328            self.gid += 1;
329            return Some((GlyphId::new(0), Sid::new(0)));
330        }
331        let gid = self.gid - 1;
332        self.gid = self.gid.checked_add(1)?;
333        while gid >= self.end {
334            let (first, end) = next_range(&mut self.ranges)?;
335            self.prev_end = self.end;
336            self.first = first;
337            self.end = self.prev_end.checked_add(end)?;
338        }
339        let sid = self
340            .first
341            .checked_add(gid.checked_sub(self.prev_end)?)?
342            .try_into()
343            .ok()?;
344        Some((GlyphId::new(gid + 1), Sid::new(sid)))
345    }
346}
347
348fn next_range<T: CharsetRange>(ranges: &mut std::slice::Iter<T>) -> Option<(u32, u32)> {
349    ranges.next().and_then(|range| {
350        range
351            .n_left()
352            .checked_add(1)
353            .map(|span| (range.first(), span))
354    })
355}
356
357/// See "Expert" charset at <https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf#page=47>
358#[rustfmt::skip]
359const EXPERT_CHARSET: &[u16] = &[
360      0,    1,  229,  230,  231,  232,  233,  234,  235,  236,  237,  238,   13,   14,   15,   99,
361    239,  240,  241,  242,  243,  244,  245,  246,  247,  248,   27,   28,  249,  250,  251,  252,
362    253,  254,  255,  256,  257,  258,  259,  260,  261,  262,  263,  264,  265,  266,  109,  110,
363    267,  268,  269,  270,  271,  272,  273,  274,  275,  276,  277,  278,  279,  280,  281,  282,
364    283,  284,  285,  286,  287,  288,  289,  290,  291,  292,  293,  294,  295,  296,  297,  298,
365    299,  300,  301,  302,  303,  304,  305,  306,  307,  308,  309,  310,  311,  312,  313,  314,
366    315,  316,  317,  318,  158,  155,  163,  319,  320,  321,  322,  323,  324,  325,  326,  150,
367    164,  169,  327,  328,  329,  330,  331,  332,  333,  334,  335,  336,  337,  338,  339,  340,
368    341,  342,  343,  344,  345,  346,  347,  348,  349,  350,  351,  352,  353,  354,  355,  356,
369    357,  358,  359,  360,  361,  362,  363,  364,  365,  366,  367,  368,  369,  370,  371,  372,
370    373,  374,  375,  376,  377,  378,
371];
372
373/// See "Expert Subset" charset at <https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf#page=49>
374#[rustfmt::skip]
375const EXPERT_SUBSET_CHARSET: &[u16] = &[
376      0,    1,  231,  232,  235,  236,  237,  238,   13,   14,   15,   99,  239,  240,  241,  242,
377    243,  244,  245,  246,  247,  248,   27,   28,  249,  250,  251,  253,  254,  255,  256,  257,
378    258,  259,  260,  261,  262,  263,  264,  265,  266,  109,  110,  267,  268,  269,  270,  272,
379    300,  301,  302,  305,  314,  315,  158,  155,  163,  320,  321,  322,  323,  324,  325,  326,
380    150,  164,  169,  327,  328,  329,  330,  331,  332,  333,  334,  335,  336,  337,  338,  339,
381    340,  341,  342,  343,  344,  345,  346
382];
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387    use font_test_data::bebuffer::BeBuffer;
388
389    #[derive(Clone, Copy)]
390    struct TestRange {
391        first: u32,
392        n_left: u32,
393    }
394
395    impl CharsetRange for TestRange {
396        fn first(&self) -> u32 {
397            self.first
398        }
399
400        fn n_left(&self) -> u32 {
401            self.n_left
402        }
403    }
404
405    #[test]
406    fn iso_adobe_charset() {
407        // Offset of 0 signifies the ISOAdobe charset
408        let charset_offset = 0;
409        let num_glyphs = 64;
410        // This is an identity mapping
411        let expected = |gid: GlyphId| Some(gid.to_u32());
412        test_simple_mapping(charset_offset, num_glyphs, expected);
413    }
414
415    #[test]
416    fn expert_charset() {
417        // Offset 1 signifies the expert charset
418        let charset_offset = 1;
419        let num_glyphs = 64;
420        // This is an array based mapping
421        let expected = |gid: GlyphId| {
422            EXPERT_CHARSET
423                .get(gid.to_u32() as usize)
424                .map(|id| *id as u32)
425        };
426        test_simple_mapping(charset_offset, num_glyphs, expected);
427    }
428
429    #[test]
430    fn expert_subset_charset() {
431        // Offset 2 signifies the expert subset charset
432        let charset_offset = 2;
433        let num_glyphs = 64;
434        // This is an array based mapping
435        let expected = |gid: GlyphId| {
436            EXPERT_SUBSET_CHARSET
437                .get(gid.to_u32() as usize)
438                .map(|id| *id as u32)
439        };
440        test_simple_mapping(charset_offset, num_glyphs, expected);
441    }
442
443    // Common test setup for identity or array based charset mappings
444    fn test_simple_mapping(
445        charset_offset: usize,
446        num_glyphs: u32,
447        expected: impl Fn(GlyphId) -> Option<u32>,
448    ) {
449        let charset = Charset::new(FontData::new(&[]), charset_offset, num_glyphs).unwrap();
450        for gid in 0..num_glyphs {
451            let gid = GlyphId::new(gid);
452            let sid = expected(gid).unwrap();
453            assert_eq!(charset.string_id(gid).unwrap().to_u16() as u32, sid);
454            assert_eq!(charset.glyph_id(Sid::new(sid as _)).unwrap(), gid);
455        }
456        // Don't map glyphs beyond num_glyphs
457        for gid in num_glyphs..u16::MAX as u32 {
458            assert_eq!(charset.string_id(GlyphId::new(gid)), None);
459        }
460    }
461
462    #[test]
463    fn custom_mapping_format0() {
464        let mut buf = BeBuffer::new();
465        let num_glyphs = 6;
466        // Add some padding so we can generate an offset greater than 2
467        buf = buf.extend([0u8; 4]);
468        // format 0
469        buf = buf.push(0u8);
470        // glyph array: each sid is gid * 2
471        buf = buf.extend([2u16, 4, 6, 8, 10]);
472        let charset = Charset::new(FontData::new(buf.data()), 4, num_glyphs).unwrap();
473        // Test lookup code path
474        for gid in 0..num_glyphs {
475            assert_eq!(
476                charset.string_id(GlyphId::new(gid)).unwrap().to_u16() as u32,
477                gid * 2
478            )
479        }
480        // Test iterator code path
481        for (gid, sid) in charset.iter() {
482            assert_eq!(sid.to_u16() as u32, gid.to_u32() * 2);
483        }
484        assert_eq!(charset.iter().count() as u32, num_glyphs);
485        // Test out of bounds glyphs
486        for gid in num_glyphs..u16::MAX as u32 {
487            assert_eq!(charset.string_id(GlyphId::new(gid)), None);
488        }
489    }
490
491    #[test]
492    fn custom_mapping_format1() {
493        let mut buf = BeBuffer::new();
494        let num_glyphs = 7;
495        // Add some padding so we can generate an offset greater than 2
496        buf = buf.extend([0u8; 4]);
497        // format 1
498        buf = buf.push(1u8);
499        // Three disjoint range mappings
500        buf = buf.push(8u16).push(2u8);
501        buf = buf.push(1200u16).push(0u8);
502        buf = buf.push(20u16).push(1u8);
503        let expected_sids = [0, 8, 9, 10, 1200, 20, 21];
504        test_range_mapping(buf.data(), num_glyphs, &expected_sids);
505    }
506
507    #[test]
508    fn custom_mapping_format2() {
509        let mut buf = BeBuffer::new();
510        // Add some padding so we can generate an offset greater than 2
511        buf = buf.extend([0u8; 4]);
512        // format 2
513        buf = buf.push(2u8);
514        // Three disjoint range mappings
515        buf = buf.push(8u16).push(2u16);
516        buf = buf.push(1200u16).push(0u16);
517        buf = buf.push(20u16).push(800u16);
518        let mut expected_sids = vec![0, 8, 9, 10, 1200];
519        for i in 0..=800 {
520            expected_sids.push(i + 20);
521        }
522        let num_glyphs = expected_sids.len() as u32;
523        test_range_mapping(buf.data(), num_glyphs, &expected_sids);
524    }
525
526    // Common code for testing range based mappings
527    fn test_range_mapping(data: &[u8], num_glyphs: u32, expected_sids: &[u32]) {
528        let charset = Charset::new(FontData::new(data), 4, num_glyphs).unwrap();
529        // Test lookup code path
530        for (gid, sid) in expected_sids.iter().enumerate() {
531            assert_eq!(
532                charset.string_id(GlyphId::new(gid as _)).unwrap().to_u16() as u32,
533                *sid
534            )
535        }
536        // Test iterator code path
537        assert!(charset.iter().eq(expected_sids
538            .iter()
539            .enumerate()
540            .map(|(gid, sid)| (GlyphId::new(gid as u32), Sid::new(*sid as u16)))));
541        assert_eq!(charset.iter().count() as u32, num_glyphs);
542        // Test out of bounds glyphs
543        for gid in num_glyphs..u16::MAX as u32 {
544            assert_eq!(charset.string_id(GlyphId::new(gid)), None);
545        }
546        // Test reverse mapping
547        for (gid, sid) in expected_sids.iter().enumerate() {
548            assert_eq!(
549                charset.glyph_id(Sid::new(*sid as u16)),
550                Some(GlyphId::new(gid as u32))
551            );
552        }
553    }
554
555    // A range may cover more string ids than the font has glyphs, and data
556    // after the last range the glyphs need is not part of the charset. No
557    // string id maps to a glyph past the end of the font.
558    #[test]
559    fn glyph_ids_stop_at_the_glyph_count() {
560        let mut buf = BeBuffer::new();
561        buf = buf.extend([0u8; 4]);
562        // format 1: sids 8..=10 cover glyphs 1 to 3, then a range past them
563        buf = buf.push(1u8);
564        buf = buf.push(8u16).push(5u8);
565        buf = buf.push(300u16).push(4u8);
566        let charset = Charset::new(FontData::new(buf.data()), 4, 4).unwrap();
567        assert_eq!(charset.glyph_id(Sid::new(10)), Some(GlyphId::new(3)));
568        assert_eq!(charset.glyph_id(Sid::new(11)), None);
569        assert_eq!(charset.glyph_id(Sid::new(300)), None);
570    }
571
572    #[test]
573    fn string_id_from_ranges_overflow_does_not_panic() {
574        // Don't panic on overflow!
575        let ranges = [TestRange {
576            first: 42,
577            n_left: u32::MAX,
578        }];
579        assert_eq!(string_id_from_ranges(&ranges, GlyphId::new(1)), None);
580    }
581
582    #[test]
583    fn glyph_id_from_ranges_overflow_does_not_panic() {
584        // Don't panic on overflow!
585        let ranges = [
586            TestRange {
587                first: 2,
588                n_left: 0,
589            },
590            TestRange {
591                first: 2,
592                n_left: u32::MAX - 2,
593            },
594        ];
595        assert_eq!(glyph_id_from_ranges(&ranges, Sid::new(1)), None);
596    }
597
598    #[test]
599    fn next_range_overflow_does_not_panic() {
600        // Don't panic on overflow!
601        let ranges = [TestRange {
602            first: 7,
603            n_left: u32::MAX,
604        }];
605        let mut iter = ranges.iter();
606        assert_eq!(next_range(&mut iter), None);
607    }
608}