Skip to main content

read_fonts/tables/
aat.rs

1//! Apple Advanced Typography common tables.
2//!
3//! See <https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6Tables.html>
4
5include!("../../generated/generated_aat.rs");
6
7/// Predefined classes.
8///
9/// See <https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6Tables.html>
10pub mod class {
11    pub const END_OF_TEXT: u8 = 0;
12    pub const OUT_OF_BOUNDS: u8 = 1;
13    pub const DELETED_GLYPH: u8 = 2;
14}
15
16impl Lookup0<'_> {
17    pub fn values<T: LookupValue>(&self) -> Result<&[BigEndian<T>], ReadError> {
18        let data = self.values_data();
19        let data_len = data.len();
20        let n_elems = data_len / T::RAW_BYTE_LEN;
21        let len_in_bytes = n_elems * T::RAW_BYTE_LEN;
22        FontData::new(&data[..len_in_bytes])
23            .cursor()
24            .read_array::<BigEndian<T>>(n_elems)
25    }
26    #[inline]
27    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
28        self.values::<T>()?
29            .get(index as usize)
30            .map(|val| val.get())
31            .ok_or(ReadError::OutOfBounds)
32    }
33}
34
35/// Lookup segment for format 2.
36#[derive(Copy, Clone, bytemuck::AnyBitPattern)]
37#[repr(C, packed)]
38pub struct LookupSegment2<T>
39where
40    T: LookupValue,
41{
42    /// Last glyph index in this segment.
43    pub last_glyph: BigEndian<u16>,
44    /// First glyph index in this segment.
45    pub first_glyph: BigEndian<u16>,
46    /// The lookup value.
47    pub value: BigEndian<T>,
48}
49
50/// Note: this requires `LookupSegment2` to be `repr(packed)`.
51impl<T: LookupValue> FixedSize for LookupSegment2<T> {
52    const RAW_BYTE_LEN: usize = std::mem::size_of::<Self>();
53}
54
55impl Lookup2<'_> {
56    #[inline]
57    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
58        let segments = self.segments::<T>()?;
59        let ix = match segments.binary_search_by(|segment| segment.first_glyph.get().cmp(&index)) {
60            Ok(ix) => ix,
61            Err(ix) => ix.saturating_sub(1),
62        };
63        let segment = segments.get(ix).ok_or(ReadError::OutOfBounds)?;
64        if (segment.first_glyph.get()..=segment.last_glyph.get()).contains(&index) {
65            let value = segment.value;
66            return Ok(value.get());
67        }
68        Err(ReadError::OutOfBounds)
69    }
70
71    pub fn segments<T: LookupValue>(&self) -> Result<&[LookupSegment2<T>], ReadError> {
72        FontData::new(self.segments_data())
73            .cursor()
74            .read_array(self.n_units() as usize)
75    }
76}
77
78impl Lookup4<'_> {
79    #[inline]
80    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
81        let segments = self.segments();
82        let ix = match segments.binary_search_by(|segment| segment.first_glyph.get().cmp(&index)) {
83            Ok(ix) => ix,
84            Err(ix) => ix.saturating_sub(1),
85        };
86        let segment = segments.get(ix).ok_or(ReadError::OutOfBounds)?;
87        if (segment.first_glyph.get()..=segment.last_glyph.get()).contains(&index) {
88            let base_offset = segment.value_offset() as usize;
89            let offset = base_offset
90                + index
91                    .checked_sub(segment.first_glyph())
92                    .ok_or(ReadError::OutOfBounds)? as usize
93                    * T::RAW_BYTE_LEN;
94            return self.offset_data().read_at(offset);
95        }
96        Err(ReadError::OutOfBounds)
97    }
98    pub fn segment_values<T: LookupValue>(
99        &self,
100        segment: usize,
101    ) -> Result<&[BigEndian<T>], ReadError> {
102        let segment = self.segments().get(segment).ok_or(ReadError::OutOfBounds)?;
103        let base_offset = segment.value_offset() as usize;
104        let n_elems = segment
105            .last_glyph
106            .get()
107            .checked_sub(segment.first_glyph.get())
108            .ok_or(ReadError::MalformedData(
109                "invalid segment in format 4 AAT lookup table",
110            ))? as usize
111            + 1;
112        self.offset_data()
113            .read_array::<BigEndian<T>>(base_offset..base_offset + n_elems * T::RAW_BYTE_LEN)
114    }
115}
116
117/// Lookup single record for format 6.
118#[derive(Copy, Clone, bytemuck::AnyBitPattern)]
119#[repr(C, packed)]
120pub struct LookupSingle<T>
121where
122    T: LookupValue,
123{
124    /// The glyph index.
125    pub glyph: BigEndian<u16>,
126    /// The lookup value.
127    pub value: BigEndian<T>,
128}
129
130/// Note: this requires `LookupSingle` to be `repr(packed)`.
131impl<T: LookupValue> FixedSize for LookupSingle<T> {
132    const RAW_BYTE_LEN: usize = std::mem::size_of::<Self>();
133}
134
135impl Lookup6<'_> {
136    #[inline]
137    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
138        let entries = self.entries::<T>()?;
139        if let Ok(ix) = entries.binary_search_by_key(&index, |entry| entry.glyph.get()) {
140            let entry = &entries[ix];
141            let value = entry.value;
142            return Ok(value.get());
143        }
144        Err(ReadError::OutOfBounds)
145    }
146
147    pub fn entries<T: LookupValue>(&self) -> Result<&[LookupSingle<T>], ReadError> {
148        FontData::new(self.entries_data())
149            .cursor()
150            .read_array(self.n_units() as usize)
151    }
152}
153
154impl Lookup8<'_> {
155    #[inline]
156    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
157        index
158            .checked_sub(self.first_glyph())
159            .and_then(|ix| {
160                self.value_array()
161                    .get(ix as usize)
162                    .map(|val| T::from_u16(val.get()))
163            })
164            .ok_or(ReadError::OutOfBounds)
165    }
166}
167
168impl Lookup10<'_> {
169    #[inline]
170    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
171        let ix = index
172            .checked_sub(self.first_glyph())
173            .ok_or(ReadError::OutOfBounds)? as usize;
174        let unit_size = self.unit_size() as usize;
175        let offset = ix.wrapping_mul(unit_size);
176        let mut cursor = FontData::new(self.values_data()).cursor();
177        cursor.advance_by(offset);
178        let val = match unit_size {
179            1 => cursor.read::<u8>()? as u32,
180            2 => cursor.read::<u16>()? as u32,
181            4 => cursor.read::<u32>()?,
182            _ => {
183                return Err(ReadError::MalformedData(
184                    "invalid unit_size in format 10 AAT lookup table",
185                ))
186            }
187        };
188        Ok(T::from_u32(val))
189    }
190}
191
192impl Lookup<'_> {
193    #[inline]
194    pub fn value<T: LookupValue>(&self, index: u16) -> Result<T, ReadError> {
195        match self {
196            Lookup::Format0(lookup) => lookup.value::<T>(index),
197            Lookup::Format2(lookup) => lookup.value::<T>(index),
198            Lookup::Format4(lookup) => lookup.value::<T>(index),
199            Lookup::Format6(lookup) => lookup.value::<T>(index),
200            Lookup::Format8(lookup) => lookup.value::<T>(index),
201            Lookup::Format10(lookup) => lookup.value::<T>(index),
202        }
203    }
204}
205
206#[derive(Clone)]
207pub struct TypedLookup<'a, T> {
208    pub lookup: Lookup<'a>,
209    _marker: std::marker::PhantomData<fn() -> T>,
210}
211
212impl<T: LookupValue> TypedLookup<'_, T> {
213    /// Returns the value associated with the given index.
214    pub fn value(&self, index: u16) -> Result<T, ReadError> {
215        self.lookup.value::<T>(index)
216    }
217}
218
219impl<T> ReadArgs for TypedLookup<'_, T> {
220    type Args = ();
221}
222
223impl<'a, T> FontRead<'a> for TypedLookup<'a, T> {
224    fn read_with_args(data: FontData<'a>, _: ()) -> Result<Self, ReadError> {
225        Ok(Self {
226            lookup: Lookup::read(data)?,
227            _marker: std::marker::PhantomData,
228        })
229    }
230}
231
232/// Trait for values that can be read from lookup tables.
233pub trait LookupValue: Copy + Scalar + bytemuck::AnyBitPattern {
234    fn from_u16(v: u16) -> Self;
235    fn from_u32(v: u32) -> Self;
236}
237
238impl LookupValue for u16 {
239    fn from_u16(v: u16) -> Self {
240        v
241    }
242
243    fn from_u32(v: u32) -> Self {
244        // intentionally truncates
245        v as _
246    }
247}
248
249impl LookupValue for u32 {
250    fn from_u16(v: u16) -> Self {
251        v as _
252    }
253
254    fn from_u32(v: u32) -> Self {
255        v
256    }
257}
258
259impl LookupValue for GlyphId16 {
260    fn from_u16(v: u16) -> Self {
261        GlyphId16::from(v)
262    }
263
264    fn from_u32(v: u32) -> Self {
265        // intentionally truncates
266        GlyphId16::from(v as u16)
267    }
268}
269
270pub type LookupU16<'a> = TypedLookup<'a, u16>;
271pub type LookupU32<'a> = TypedLookup<'a, u32>;
272pub type LookupGlyphId<'a> = TypedLookup<'a, GlyphId16>;
273
274/// Empty data type for a state table entry with no payload.
275///
276/// Note: this type is only intended for use as the type parameter for
277/// `StateEntry`. The inner field is private and this type cannot be
278/// constructed outside of this module.
279#[derive(Copy, Clone, bytemuck::AnyBitPattern, Debug)]
280pub struct NoPayload(());
281
282impl FixedSize for NoPayload {
283    const RAW_BYTE_LEN: usize = 0;
284}
285
286/// Entry in an (extended) state table.
287#[derive(Clone, Debug)]
288pub struct StateEntry<T = NoPayload> {
289    /// Index of the next state.
290    pub new_state: u16,
291    /// Flag values are table specific.
292    pub flags: u16,
293    /// Payload is table specific.
294    pub payload: T,
295}
296
297impl<T: bytemuck::AnyBitPattern + FixedSize> ReadArgs for StateEntry<T> {
298    type Args = ();
299}
300
301impl<'a, T: bytemuck::AnyBitPattern + FixedSize> FontRead<'a> for StateEntry<T> {
302    fn read_with_args(data: FontData<'a>, _: ()) -> Result<Self, ReadError> {
303        let mut cursor = data.cursor();
304        let new_state = cursor.read()?;
305        let flags = cursor.read()?;
306        let remaining = cursor.remaining().ok_or(ReadError::OutOfBounds)?;
307        let payload = *remaining.read_ref_at(0)?;
308        Ok(Self {
309            new_state,
310            flags,
311            payload,
312        })
313    }
314}
315
316impl<T> FixedSize for StateEntry<T>
317where
318    T: FixedSize,
319{
320    // Two u16 fields + payload
321    const RAW_BYTE_LEN: usize = u16::RAW_BYTE_LEN + u16::RAW_BYTE_LEN + T::RAW_BYTE_LEN;
322}
323
324/// Table for driving a finite state machine for layout.
325///
326/// The input to the state machine consists of the current state
327/// and a glyph class. The output is an [entry](StateEntry) containing
328/// the next state and a payload that is dependent on the type of
329/// layout action being performed.
330///
331/// See <https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6Tables.html#StateHeader>
332/// for more detail.
333#[derive(Clone)]
334pub struct StateTable<'a, T = NoPayload> {
335    pub header: StateHeader<'a>,
336    pub n_classes: usize,
337    class_first_glyph: u16,
338    class_array: &'a [u8],
339    state_array: &'a [u8],
340    entry_table: &'a [u8],
341    /// floor(2^32 / n_classes) + 1: exact reciprocal for dividends < 2^16,
342    /// so the per-transition new-state conversion avoids a hardware divide.
343    n_classes_magic: u64,
344    _marker: std::marker::PhantomData<fn() -> T>,
345}
346
347impl<T> StateTable<'_, T> {
348    pub const HEADER_LEN: usize = u16::RAW_BYTE_LEN * 4;
349}
350
351impl<T> StateTable<'_, T>
352where
353    T: FixedSize + bytemuck::AnyBitPattern,
354{
355    /// Returns the class table entry for the given glyph identifier.
356    pub fn class(&self, glyph_id: GlyphId16) -> Result<u8, ReadError> {
357        let glyph_id = glyph_id.to_u16();
358        if glyph_id == 0xFFFF {
359            return Ok(class::DELETED_GLYPH);
360        }
361        glyph_id
362            .checked_sub(self.class_first_glyph)
363            .and_then(|ix| self.class_array.get(ix as usize).copied())
364            .ok_or(ReadError::OutOfBounds)
365    }
366
367    /// Returns the first covered glyph and its consecutive class values.
368    pub fn class_mappings(&self) -> (u16, &'_ [u8]) {
369        (self.class_first_glyph, self.class_array)
370    }
371
372    /// Returns the entry for the given state and class.
373    #[inline(always)]
374    pub fn entry(&self, state: u16, class: u8) -> Result<StateEntry<T>, ReadError> {
375        let mut class = class as usize;
376        if class >= self.n_classes {
377            class = class::OUT_OF_BOUNDS as usize;
378        }
379        let entry_ix = self
380            .state_array
381            .get(state as usize * self.n_classes + class)
382            .copied()
383            .ok_or(ReadError::OutOfBounds)? as usize;
384        let entry_offset = entry_ix.wrapping_mul(StateEntry::<T>::RAW_BYTE_LEN);
385        let entry_data = self
386            .entry_table
387            .get(entry_offset..)
388            .ok_or(ReadError::OutOfBounds)?;
389        let mut entry = StateEntry::read(FontData::new(entry_data))?;
390        // For legacy state tables, the newState is a byte offset into
391        // the state array. Convert this to an index for consistency.
392        let offset = self.header.state_array_offset().to_u32() as i32;
393        let diff = entry.new_state as i32 - offset;
394        let new_state = if diff >= 0 {
395            // Multiply by the precomputed reciprocal instead of dividing;
396            // exact for all dividends below 2^16, and this is the per-
397            // transition hot path of legacy state machines.
398            ((diff as u64 * self.n_classes_magic) >> 32) as i32
399        } else {
400            diff / self.n_classes as i32
401        };
402        entry.new_state = new_state.try_into().map_err(|_| ReadError::OutOfBounds)?;
403        Ok(entry)
404    }
405
406    /// Reads scalar values that are referenced from state table entries.
407    pub fn read_value<S: Scalar>(&self, offset: usize) -> Result<S, ReadError> {
408        self.header.offset_data().read_at::<S>(offset)
409    }
410}
411
412/// Pre-resolved byte offsets of a legacy [StateTable]'s components, relative
413/// to the table start.
414#[derive(Clone, Copy, Debug, Default)]
415pub struct LegacyStateTableParts {
416    pub n_classes: u16,
417    pub class_table_offset: u16,
418    pub state_array_offset: u16,
419    pub entry_table_offset: u16,
420}
421
422impl LegacyStateTableParts {
423    /// Reads the header of a legacy state table at the start of `data`.
424    pub fn read(data: FontData) -> Result<Self, ReadError> {
425        let header = StateHeader::read(data)?;
426        Ok(Self {
427            n_classes: header.state_size(),
428            class_table_offset: header.class_table_offset().to_u32() as u16,
429            state_array_offset: header.state_array_offset().to_u32() as u16,
430            entry_table_offset: header.entry_table_offset().to_u32() as u16,
431        })
432    }
433}
434
435impl<'a, T> StateTable<'a, T> {
436    /// Builds the state table from `data` and offsets previously captured
437    /// with [LegacyStateTableParts::read] on the same data.
438    #[inline]
439    pub fn from_parts(
440        data: FontData<'a>,
441        parts: &LegacyStateTableParts,
442    ) -> Result<Self, ReadError> {
443        let n_classes = parts.n_classes as usize;
444        if n_classes == 0 {
445            return Err(ReadError::MalformedData("empty AAT state table"));
446        }
447        let class_table = ClassSubtable::read(
448            data.split_off(parts.class_table_offset as usize)
449                .ok_or(ReadError::OutOfBounds)?,
450        )?;
451        let class_first_glyph = class_table.first_glyph();
452        let class_array = class_table.class_array();
453        let state_array = data
454            .as_bytes()
455            .get(parts.state_array_offset as usize..)
456            .ok_or(ReadError::OutOfBounds)?;
457        let entry_table = data
458            .as_bytes()
459            .get(parts.entry_table_offset as usize..)
460            .ok_or(ReadError::OutOfBounds)?;
461        Ok(Self {
462            header: StateHeader::read(data)?,
463            n_classes,
464            class_first_glyph,
465            class_array,
466            state_array,
467            entry_table,
468            n_classes_magic: (1u64 << 32) / n_classes as u64 + 1,
469            _marker: std::marker::PhantomData,
470        })
471    }
472}
473
474impl<'a> StateTable<'a, NoPayload> {
475    /// Reads a state table whose entries carry no payload.
476    ///
477    /// This exists so that `StateTable::read(data)` still resolves without
478    /// naming the payload type: a type parameter's default does not apply in a
479    /// path expression, only in type position. Without it, adding the payload
480    /// parameter would have broken every existing caller.
481    ///
482    /// Remove this at the next breaking release, so that callers name the
483    /// payload as they do for `ExtendedStateTable`.
484    pub fn read(data: FontData<'a>) -> Result<Self, ReadError> {
485        <Self as FontRead<'a>>::read(data)
486    }
487}
488
489impl<T> ReadArgs for StateTable<'_, T> {
490    type Args = ();
491}
492
493impl<'a, T> FontRead<'a> for StateTable<'a, T> {
494    fn read_with_args(data: FontData<'a>, _: ()) -> Result<Self, ReadError> {
495        let header = StateHeader::read(data)?;
496        // Each state has a 1-byte entry per class so state_size == n_classes
497        let n_classes = header.state_size() as usize;
498        if n_classes == 0 {
499            // This will result in a divide by 0 in all cases
500            return Err(ReadError::MalformedData("empty AAT state table"));
501        }
502        let class_table = header.class_table()?;
503        let class_first_glyph = class_table.first_glyph();
504        let class_array = class_table.class_array();
505        let state_array = header.state_array()?.data();
506        let entry_table = header.entry_table()?.data();
507        Ok(Self {
508            header: StateHeader::read(data)?,
509            n_classes,
510            class_first_glyph,
511            class_array,
512            state_array,
513            entry_table,
514            n_classes_magic: (1u64 << 32) / n_classes as u64 + 1,
515            _marker: std::marker::PhantomData,
516        })
517    }
518}
519
520#[derive(Clone)]
521pub struct ExtendedStateTable<'a, T = NoPayload> {
522    pub n_classes: usize,
523    pub class_table: LookupU16<'a>,
524    state_array: &'a [BigEndian<u16>],
525    entry_table: &'a [u8],
526    _marker: std::marker::PhantomData<fn() -> T>,
527}
528
529impl<T> ExtendedStateTable<'_, T> {
530    pub const HEADER_LEN: usize = u32::RAW_BYTE_LEN * 4;
531}
532
533/// Table for driving a finite state machine for layout.
534///
535/// The input to the state machine consists of the current state
536/// and a glyph class. The output is an [entry](StateEntry) containing
537/// the next state and a payload that is dependent on the type of
538/// layout action being performed.
539///
540/// See <https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6Tables.html#StateHeader>
541/// for more detail.
542impl<T> ExtendedStateTable<'_, T>
543where
544    T: FixedSize + bytemuck::AnyBitPattern,
545{
546    /// Returns the class table entry for the given glyph identifier.
547    #[inline]
548    pub fn class(&self, glyph_id: GlyphId) -> Result<u16, ReadError> {
549        let glyph_id: u16 = glyph_id
550            .to_u32()
551            .try_into()
552            .map_err(|_| ReadError::OutOfBounds)?;
553        if glyph_id == 0xFFFF {
554            return Ok(class::DELETED_GLYPH as u16);
555        }
556        self.class_table.value(glyph_id)
557    }
558
559    /// Returns the entry for the given state and class.
560    #[inline]
561    pub fn entry(&self, state: u16, class: u16) -> Result<StateEntry<T>, ReadError> {
562        let mut class = class as usize;
563        if class >= self.n_classes {
564            class = class::OUT_OF_BOUNDS as usize;
565        }
566        let state_ix = (state as usize)
567            .wrapping_mul(self.n_classes)
568            .wrapping_add(class);
569        let entry_ix = self
570            .state_array
571            .get(state_ix)
572            .copied()
573            .ok_or(ReadError::OutOfBounds)?
574            .get() as usize;
575        let entry_offset = entry_ix.wrapping_mul(StateEntry::<T>::RAW_BYTE_LEN);
576        let entry_data = self
577            .entry_table
578            .get(entry_offset..)
579            .ok_or(ReadError::OutOfBounds)?;
580        StateEntry::read(FontData::new(entry_data))
581    }
582}
583
584/// Pre-resolved byte offsets of an [ExtendedStateTable]'s components,
585/// relative to the table start. Lifetime-free, so callers can cache it and
586/// rebuild the table with [ExtendedStateTable::from_parts] without re-reading
587/// and re-validating the header.
588#[derive(Clone, Copy, Debug, Default)]
589pub struct StateTableParts {
590    pub n_classes: u32,
591    pub class_table_offset: u32,
592    pub state_array_offset: u32,
593    pub entry_table_offset: u32,
594}
595
596impl StateTableParts {
597    /// Reads the header of an extended state table at the start of `data`.
598    pub fn read(data: FontData) -> Result<Self, ReadError> {
599        let header = StxHeader::read(data)?;
600        Ok(StateTableParts {
601            n_classes: header.n_classes(),
602            class_table_offset: header.class_table_offset().to_u32(),
603            state_array_offset: header.state_array_offset().to_u32(),
604            entry_table_offset: header.entry_table_offset().to_u32(),
605        })
606    }
607}
608
609impl<'a, T> ExtendedStateTable<'a, T> {
610    /// Builds the state table from `data` and offsets previously captured
611    /// with [StateTableParts::read] on the same data.
612    #[inline]
613    pub fn from_parts(data: FontData<'a>, parts: &StateTableParts) -> Result<Self, ReadError> {
614        let class_table = LookupU16::read(
615            data.split_off(parts.class_table_offset as usize)
616                .ok_or(ReadError::OutOfBounds)?,
617        )?;
618        let state_array = safe_read_array_to_end(&data, parts.state_array_offset as usize)?;
619        let entry_table = data
620            .as_bytes()
621            .get(parts.entry_table_offset as usize..)
622            .ok_or(ReadError::OutOfBounds)?;
623        Ok(Self {
624            n_classes: parts.n_classes as usize,
625            class_table,
626            state_array,
627            entry_table,
628            _marker: std::marker::PhantomData,
629        })
630    }
631}
632
633impl<T> ReadArgs for ExtendedStateTable<'_, T> {
634    type Args = ();
635}
636
637impl<'a, T> FontRead<'a> for ExtendedStateTable<'a, T> {
638    fn read_with_args(data: FontData<'a>, _: ()) -> Result<Self, ReadError> {
639        let header = StxHeader::read(data)?;
640        let n_classes = header.n_classes() as usize;
641        let class_table = header.class_table()?;
642        let state_array = header.state_array()?.data();
643        let entry_table = header.entry_table()?.data();
644        Ok(Self {
645            n_classes,
646            class_table,
647            state_array,
648            entry_table,
649            _marker: std::marker::PhantomData,
650        })
651    }
652}
653
654/// Reads an array of T from the given FontData, ensuring that the byte length
655/// is a multiple of the size of T.
656///
657/// Many of the `morx` subtables have arrays without associated lengths so we
658/// simply read to the end of the available data. The `FontData::read_array`
659/// method will fail if the byte range provided is not exact so this helper
660/// allows us to force the lengths to an acceptable value.
661pub(crate) fn safe_read_array_to_end<'a, T: bytemuck::AnyBitPattern + FixedSize>(
662    data: &FontData<'a>,
663    offset: usize,
664) -> Result<&'a [T], ReadError> {
665    let len = data
666        .len()
667        .checked_sub(offset)
668        .ok_or(ReadError::OutOfBounds)?;
669    let end = offset + len / T::RAW_BYTE_LEN * T::RAW_BYTE_LEN;
670    data.read_array(offset..end)
671}
672
673#[cfg(test)]
674mod tests {
675    use font_test_data::bebuffer::BeBuffer;
676
677    use super::*;
678
679    #[test]
680    fn lookup_format_0() {
681        #[rustfmt::skip]
682        let words = [
683            0_u16, // format
684            0, 2, 4, 6, 8, 10, 12, 14, 16, // maps all glyphs to gid * 2
685        ];
686        let mut buf = BeBuffer::new();
687        buf = buf.extend(words);
688        let lookup = LookupU16::read(buf.data().into()).unwrap();
689        for gid in 0..=8 {
690            assert_eq!(lookup.value(gid).unwrap(), gid * 2);
691        }
692        assert!(lookup.value(9).is_err());
693    }
694
695    // Taken from example 2 at https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6morx.html
696    #[test]
697    fn lookup_format_2() {
698        #[rustfmt::skip]
699        let words = [
700            2_u16, // format
701            6,     // unit size (6 bytes)
702            3,     // number of units
703            12,    // search range
704            1,     // entry selector
705            6,     // range shift
706            22, 20, 4, // First segment, mapping glyphs 20 through 22 to class 4
707            24, 23, 5, // Second segment, mapping glyph 23 and 24 to class 5
708            28, 25, 6, // Third segment, mapping glyphs 25 through 28 to class 6
709        ];
710        let mut buf = BeBuffer::new();
711        buf = buf.extend(words);
712        let lookup = LookupU16::read(buf.data().into()).unwrap();
713        let expected = [(20..=22, 4), (23..=24, 5), (25..=28, 6)];
714        for (range, class) in expected {
715            for gid in range {
716                assert_eq!(lookup.value(gid).unwrap(), class);
717            }
718        }
719        for fail in [0, 10, 19, 29, 0xFFFF] {
720            assert!(lookup.value(fail).is_err());
721        }
722    }
723
724    #[test]
725    fn lookup_format_4() {
726        #[rustfmt::skip]
727        let words = [
728            4_u16, // format
729            6,     // unit size (6 bytes)
730            3,     // number of units
731            12,    // search range
732            1,     // entry selector
733            6,     // range shift
734            22, 20, 30, // First segment, mapping glyphs 20 through 22 to mapped data at offset 30
735            24, 23, 36, // Second segment, mapping glyph 23 and 24 to mapped data at offset 36
736            28, 25, 40, // Third segment, mapping glyphs 25 through 28 to mapped data at offset 40
737            // mapped data
738            3, 2, 1,
739            100, 150,
740            8, 6, 7, 9
741        ];
742        let mut buf = BeBuffer::new();
743        buf = buf.extend(words);
744        let lookup = LookupU16::read(buf.data().into()).unwrap();
745        let expected = [
746            (20, 3),
747            (21, 2),
748            (22, 1),
749            (23, 100),
750            (24, 150),
751            (25, 8),
752            (26, 6),
753            (27, 7),
754            (28, 9),
755        ];
756        for (in_glyph, out_glyph) in expected {
757            assert_eq!(lookup.value(in_glyph).unwrap(), out_glyph);
758        }
759        for fail in [0, 10, 19, 29, 0xFFFF] {
760            assert!(lookup.value(fail).is_err());
761        }
762    }
763
764    // Taken from example 1 at https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6morx.html
765    #[test]
766    fn lookup_format_6() {
767        #[rustfmt::skip]
768        let words = [
769            6_u16, // format
770            4,     // unit size (4 bytes)
771            4,     // number of units
772            16,    // search range
773            2,     // entry selector
774            0,     // range shift
775            50, 600, // Input glyph 50 maps to glyph 600
776            51, 601, // Input glyph 51 maps to glyph 601
777            201, 602, // Input glyph 201 maps to glyph 602
778            202, 900, // Input glyph 202 maps to glyph 900
779        ];
780        let mut buf = BeBuffer::new();
781        buf = buf.extend(words);
782        let lookup = LookupU16::read(buf.data().into()).unwrap();
783        let expected = [(50, 600), (51, 601), (201, 602), (202, 900)];
784        for (in_glyph, out_glyph) in expected {
785            assert_eq!(lookup.value(in_glyph).unwrap(), out_glyph);
786        }
787        for fail in [0, 10, 49, 52, 203, 0xFFFF] {
788            assert!(lookup.value(fail).is_err());
789        }
790    }
791
792    #[test]
793    fn lookup_format_8() {
794        #[rustfmt::skip]
795        let words = [
796            8_u16, // format
797            201,   // first glyph
798            7,     // glyph count
799            3, 8, 2, 9, 1, 200, 60, // glyphs 201..209 mapped to these values
800        ];
801        let mut buf = BeBuffer::new();
802        buf = buf.extend(words);
803        let lookup = LookupU16::read(buf.data().into()).unwrap();
804        let expected = &words[3..];
805        for (gid, expected) in (201..209).zip(expected) {
806            assert_eq!(lookup.value(gid).unwrap(), *expected);
807        }
808        for fail in [0, 10, 200, 210, 0xFFFF] {
809            assert!(lookup.value(fail).is_err());
810        }
811    }
812
813    #[test]
814    fn lookup_format_10() {
815        #[rustfmt::skip]
816        let words = [
817            10_u16, // format
818            4,      // unit size, use 4 byte values
819            201,   // first glyph
820            7,     // glyph count
821        ];
822        // glyphs 201..209 mapped to these values
823        let mapped = [3_u32, 8, 2902384, 9, 1, u32::MAX, 60];
824        let mut buf = BeBuffer::new();
825        buf = buf.extend(words).extend(mapped);
826        let lookup = LookupU32::read(buf.data().into()).unwrap();
827        for (gid, expected) in (201..209).zip(mapped) {
828            assert_eq!(lookup.value(gid).unwrap(), expected);
829        }
830        for fail in [0, 10, 200, 210, 0xFFFF] {
831            assert!(lookup.value(fail).is_err());
832        }
833    }
834
835    #[test]
836    fn extended_state_table() {
837        #[rustfmt::skip]
838        let header = [
839            6_u32, // number of classes
840            20, // byte offset to class table
841            56, // byte offset to state array
842            92, // byte offset to entry array
843            0, // padding
844        ];
845        #[rustfmt::skip]
846        let class_table = [
847            6_u16, // format
848            4,     // unit size (4 bytes)
849            5,     // number of units
850            16,    // search range
851            2,     // entry selector
852            0,     // range shift
853            50, 4, // Input glyph 50 maps to class 4
854            51, 4, // Input glyph 51 maps to class 4
855            80, 5, // Input glyph 80 maps to class 5
856            201, 4, // Input glyph 201 maps to class 4
857            202, 4, // Input glyph 202 maps to class 4
858            !0, !0
859        ];
860        #[rustfmt::skip]
861        let state_array: [u16; 18] = [
862            0, 0, 0, 0, 0, 1,
863            0, 0, 0, 0, 0, 1,
864            0, 0, 0, 0, 2, 1,
865        ];
866        #[rustfmt::skip]
867        let entry_table: [u16; 12] = [
868            0, 0, u16::MAX, u16::MAX,
869            2, 0, u16::MAX, u16::MAX,
870            0, 0, u16::MAX, 0,
871        ];
872        let buf = BeBuffer::new()
873            .extend(header)
874            .extend(class_table)
875            .extend(state_array)
876            .extend(entry_table);
877        let table = ExtendedStateTable::<ContextualData>::read(buf.data().into()).unwrap();
878        // check class lookups
879        let [class_50, class_80, class_201] =
880            [50, 80, 201].map(|gid| table.class(GlyphId::new(gid)).unwrap());
881        assert_eq!(class_50, 4);
882        assert_eq!(class_80, 5);
883        assert_eq!(class_201, 4);
884        // initial state
885        let entry = table.entry(0, 4).unwrap();
886        assert_eq!(entry.new_state, 0);
887        assert_eq!(entry.payload.current_index, !0);
888        // entry (state 0, class 5) should transition to state 2
889        let entry = table.entry(0, 5).unwrap();
890        assert_eq!(entry.new_state, 2);
891        // from state 2, we transition back to state 0 when class is not 5
892        // this also enables an action (payload.current_index != -1)
893        let entry = table.entry(2, 4).unwrap();
894        assert_eq!(entry.new_state, 0);
895        assert_eq!(entry.payload.current_index, 0);
896    }
897
898    #[derive(Copy, Clone, Debug, bytemuck::AnyBitPattern)]
899    #[repr(C, packed)]
900    struct ContextualData {
901        _mark_index: BigEndian<u16>,
902        current_index: BigEndian<u16>,
903    }
904
905    impl FixedSize for ContextualData {
906        const RAW_BYTE_LEN: usize = 4;
907    }
908
909    // Take from example at <https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6kern.html>
910    // with class table trimmed to 4 glyphs
911    #[test]
912    fn state_table() {
913        #[rustfmt::skip]
914        let header = [
915            7_u16, // number of classes
916            10, // byte offset to class table
917            18, // byte offset to state array
918            40, // byte offset to entry array
919            64, // byte offset to value array (unused here)
920        ];
921        #[rustfmt::skip]
922        let class_table = [
923            3_u16, // first glyph
924            4, // number of glyphs
925        ];
926        let classes = [1u8, 2, 3, 4];
927        #[rustfmt::skip]
928        let state_array: [u8; 22] = [
929            2, 0, 0, 2, 1, 0, 0,
930            2, 0, 0, 2, 1, 0, 0,
931            2, 3, 3, 2, 3, 4, 5,
932            0, // padding
933        ];
934        #[rustfmt::skip]
935        let entry_table: [u16; 10] = [
936            // The first column are offsets from the beginning of the state
937            // table to some position in the state array
938            18, 0x8112,
939            32, 0x8112,
940            18, 0x0000,
941            32, 0x8114,
942            18, 0x8116,
943        ];
944        let buf = BeBuffer::new()
945            .extend(header)
946            .extend(class_table)
947            .extend(classes)
948            .extend(state_array)
949            .extend(entry_table);
950        let table = StateTable::<NoPayload>::read(buf.data().into()).unwrap();
951        // check class lookups
952        for i in 0..4u8 {
953            assert_eq!(table.class(GlyphId16::from(i as u16 + 3)).unwrap(), i + 1);
954        }
955        // (state, class) -> (new_state, flags)
956        let cases = [
957            ((0, 4), (2, 0x8112)),
958            ((2, 1), (2, 0x8114)),
959            ((1, 3), (0, 0x0000)),
960            ((2, 5), (0, 0x8116)),
961        ];
962        for ((state, class), (new_state, flags)) in cases {
963            let entry = table.entry(state, class).unwrap();
964            assert_eq!(
965                entry.new_state, new_state,
966                "state {state}, class {class} should map to new state {new_state} (got {})",
967                entry.new_state
968            );
969            assert_eq!(
970                entry.flags, flags,
971                "state {state}, class {class} should map to flags 0x{flags:X} (got 0x{:X})",
972                entry.flags
973            );
974        }
975    }
976}