Allsorts

https://docs.rs/allsorts/0.16.1/allsorts/
Admin
Allsorts is a font parser, shaping engine, and subsetter for OpenType, WOFF, and WOFF2 fonts written...
Tokens:572,220
Snippets:6,311
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete Example: Loading Font, Mapping Text, and Applying Glyph Substitution

Source: https://docs.rs/allsorts/0.16.1/allsorts/gsub/fn.apply.html

This example demonstrates loading an OpenType font, mapping input text to glyphs, and then applying glyph substitution using the `gsub::apply` function. It includes setup for script and language tags, font file loading, and glyph buffer manipulation. Ensure the 'Klei.otf' font file is available in the 'tests/fonts/opentype/' directory.

```rust
use std::error::Error;
use std::sync::Arc;

use allsorts::binary::read::ReadScope;
use allsorts::error::ParseError;
use allsorts::font::{MatchingPresentation};
use allsorts::font_data::FontData;
use allsorts::gsub::{Features, GlyphOrigin, FeatureMask, RawGlyph, RawGlyphFlags};
use allsorts::tinyvec::tiny_vec;
use allsorts::unicode::VariationSelector;
use allsorts::DOTTED_CIRCLE;
use allsorts::{gsub, tag, Font};

fn shape(text: &str) -> Result<Vec<RawGlyph<()>>, Box<dyn Error>> {
    let script = tag::from_string("LATN")?;
    let lang = tag::from_string("DFLT")?;
    let buffer = std::fs::read("tests/fonts/opentype/Klei.otf")
        .expect("unable to read Klei.otf");
    let scope = ReadScope::new(&buffer);
    let font_file = scope.read::<FontData<'_>>()?;
    // Use a different index to access other fonts in a font collection (E.g. TTC)
    let provider = font_file.table_provider(0)?;
    let mut font = Font::new(provider)?;

    let opt_gsub_cache = font.gsub_cache()?;
    let opt_gpos_cache = font.gpos_cache()?;
    let opt_gdef_table = font.gdef_table()?;
    let opt_gdef_table = opt_gdef_table.as_ref().map(Arc::as_ref);

    // Map glyphs
    //
    // We look ahead in the char stream for variation selectors. If one is found it is used for
    // mapping the current glyph. When a variation selector is reached in the stream it is
    // skipped as it was handled as part of the preceding character.
    let mut chars_iter = text.chars().peekable();
    let mut glyphs = Vec::new();
    while let Some(ch) = chars_iter.next() {
        match VariationSelector::try_from(ch) {
            Ok(_) => {} // filter out variation selectors
            Err(()) => {
                let vs = chars_iter
                    .peek()
                    .and_then(|&next| VariationSelector::try_from(next).ok());
                let (glyph_index, used_variation) = font.lookup_glyph_index(
                    ch,
                    MatchingPresentation::NotRequired,
                    vs,
                );
                let glyph = RawGlyph {
                    unicodes: tiny_vec!([char; 1] => ch),
                    glyph_index: glyph_index,
                    liga_component_pos: 0,
                    glyph_origin: GlyphOrigin::Char(ch),
                    flags: RawGlyphFlags::empty(),
                    extra_data: (),
                    variation: Some(used_variation),
                };
                glyphs.push(glyph);
            }
        }
    }

    let (dotted_circle_index, _) = font.lookup_glyph_index(
        DOTTED_CIRCLE,
        MatchingPresentation::NotRequired,
        None,
    );

    // If the font was a variable font you would want to supply the variation tuple
    let tuple = None;

    // Apply gsub if table is present
    let num_glyphs = font.num_glyphs();
    if let Some(gsub_cache) = opt_gsub_cache {
        gsub::apply(
            dotted_circle_index,
            &gsub_cache,
            opt_gdef_table,
            script,
            Some(lang),
            &Features::Mask(FeatureMask::default()),
            tuple,
            num_glyphs,
            &mut glyphs,
        )?;
    }

    // This is where you would apply `gpos` if the table is present.

    Ok(glyphs)
}

match shape("This is the first example.") {
    Ok(glyphs) => {
        assert!(!glyphs.is_empty());
    }
    Err(err) => panic!("Unable to shape text: {}", err),
}

```

--------------------------------

### DebugVisitor Example Usage

Source: https://docs.rs/allsorts/0.16.1/allsorts/cff/charstring/struct.DebugVisitor.html

An example demonstrating how to use the DebugVisitor to process a CharString from an OpenType font.

```APIDOC
## Example

```rust
use allsorts::binary::read::ReadScope;
use allsorts::cff::charstring::{ArgumentsStack, CharStringVisitorContext, DebugVisitor};
use allsorts::cff::CFFError;
use allsorts::cff::{self, CFFFont, CFFVariant, CFF};
use allsorts::font::MatchingPresentation;
use allsorts::font_data::FontData;
use allsorts::tables::{OpenTypeData, OpenTypeFont};
use allsorts::{tag, Font};

fn main() -> Result<(), CFFError> {
    // Read the font
    let buffer = std::fs::read("tests/fonts/opentype/Klei.otf").unwrap();
    let otf = ReadScope::new(&buffer).read::<OpenTypeFont<'_>>()?;
    let offset_table = match otf.data {
        OpenTypeData::Single(ttf) => ttf,
        OpenTypeData::Collection(_) => unreachable!(),
    };

    let cff_table_data = offset_table
        .read_table(&otf.scope, tag::CFF)?
        .expect("missing CFF table");
    let cff = cff_table_data.read::<CFF<'_>>()?;

    // Glyph to visit
    let glyph_id = 741; // U+2116 NUMERO SIGN

    // Set up CharString visitor
    let font = &cff.fonts[0];
    let local_subrs = match &font.data {
        CFFVariant::CID(_) => None, // Will be resolved on request.
        CFFVariant::Type1(type1) => type1.local_subr_index.as_ref(),
    };

    let mut visitor = DebugVisitor;
    let variable = None;
    let mut ctx = CharStringVisitorContext::new(
        glyph_id,
        &font.char_strings_index,
        local_subrs,
        &cff.global_subr_index,
        variable,
    );
    let mut stack = ArgumentsStack {
        data: &mut [0.0; cff::MAX_OPERANDS],
        len: 0,
        max_len: cff::MAX_OPERANDS,
    };
    ctx.visit(CFFFont::CFF(font), &mut stack, &mut visitor)?;
    Ok(())
}
```
```

--------------------------------

### Example of using GlyfVisitorContext to visit glyph outlines

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/glyf/struct.GlyfVisitorContext.html

This example demonstrates loading a variable font, setting up variation coordinates, and using `GlyfVisitorContext` to visit the outlines of a specific glyph, outputting the outline commands to a `DebugVisitor`. It requires loading several font tables and setting up a `VariableGlyfContextStore`.

```rust
use std::fmt::Write;

use allsorts::binary::read::ReadScope;
use allsorts::error::ParseError;
use allsorts::outline::OutlineBuilder;
use allsorts::outline::OutlineSink;
use allsorts::tables::glyf::GlyfVisitorContext;
use allsorts::tables::glyf::LocaGlyf;
use allsorts::tables::glyf::VariableGlyfContext;
use allsorts::tables::glyf::VariableGlyfContextStore;
use allsorts::tables::variable_fonts::avar::AvarTable;
use allsorts::tables::variable_fonts::fvar::FvarTable;
use allsorts::tables::Fixed;
use allsorts::tables::FontTableProvider;
use allsorts::tables::OpenTypeFont;
use allsorts::tag;
use pathfinder_geometry::line_segment::LineSegment2F;
use pathfinder_geometry::vector::Vector2F;

struct DebugVisitor {
    outlines: String,
}

impl OutlineSink for DebugVisitor {
    fn move_to(&mut self, to: Vector2F) {
        writeln!(&mut self.outlines, "move_to({}, {})", to.x(), to.y()).unwrap();
    }

    fn line_to(&mut self, to: Vector2F) {
        writeln!(&mut self.outlines, "line_to({}, {})", to.x(), to.y()).unwrap();
    }

    fn quadratic_curve_to(&mut self, control: Vector2F, to: Vector2F) {
        writeln!(
            &mut self.outlines,
            "quad_to({}, {}, {}, {})",
            control.x(),
            control.y(),
            to.x(),
            to.y()
        )
        .unwrap();
    }

    fn cubic_curve_to(&mut self, control: LineSegment2F, to: Vector2F) {
        writeln!(
            &mut self.outlines,
            "curve_to({}, {}, {}, {}, {}, {})",
            control.from_x(),
            control.from_y(),
            control.to_x(),
            control.to_y(),
            to.x(),
            to.y()
        )
        .unwrap();
    }

    fn close(&mut self) {
        writeln!(&mut self.outlines, "close()").unwrap();
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let buffer = std::fs::read("tests/fonts/variable/Inter[slnt,wght].abc.ttf")?;
    let scope = ReadScope::new(&buffer);
    let font_file = scope.read::<OpenTypeFont<'_>>()?;
    let provider = font_file.table_provider(0)?;

    // Load the tables
    let fvar_data = provider.read_table_data(tag::FVAR)?;
    let fvar = ReadScope::new(&fvar_data).read::<FvarTable<'_>>().unwrap();
    let avar_data = provider.table_data(tag::AVAR)?;
    let avar = avar_data
        .as_ref()
        .map(|avar_data| ReadScope::new(avar_data).read::<AvarTable<'_>>())
        .transpose()?;
    let mut loca_glyf = LocaGlyf::load(&provider)?;
    let store = VariableGlyfContextStore::read(&provider)?;

    // Get the variation tuple
    //   Subfamily: ExtraBold Italic
    // Coordinates: [800.0, -10.0]
    let user_tuple = [Fixed::from(800), Fixed::from(-10)];
    let tuple = fvar.normalize(user_tuple.iter().copied(), avar.as_ref())?;

    // Visit the outlines
    let var_context = VariableGlyfContext::new(&store)?;
    let mut context = GlyfVisitorContext::new(&mut loca_glyf, Some(var_context));
    let mut visitor = DebugVisitor {
        outlines: String::new(),
    };

    context
        .visit(1, Some(&tuple), &mut visitor)
        .expect("error visiting glyph outline");

    let expected = "move_to(456, -26)
quad_to(310, -26, 204.5, 23.5)
quad_to(99, 73, 50.5, 174)
quad_to(2, 275, 27, 426)
quad_to(49, 554, 108.5, 641.5)
quad_to(168, 729, 255.5, 784)
quad_to(343, 839, 451, 868)
quad_to(559, 897, 677, 907)
quad_to(809, 919, 891.5, 933)
quad_to(974, 947, 1015, 972.5)
quad_to(1056, 998, 1065, 1044)
line_to(1065, 1049)
quad_to(1077, 1126, 1032, 1168)
quad_to(987, 1210, 897, 1210)
quad_to(801, 1210, 733, 1168)
quad_to(665, 1126, 638, 1052)
line_to(190, 1068)
quad_to(232, 1208, 334, 1318.5)
quad_to(436, 1429, 593.5, 1492.5)
quad_to(751, 1556, 958, 1556)
quad_to(1104, 1556, 1222, 1521.5)
quad_to(1340, 1487, 1421.5, 1421.5)
quad_to(1503, 1356, 1538, 1261)
quad_to(1573, 1166, 1553, 1044)
line_to(1378, 0)
line_to(918, 0)
line_to(954, 214)
line_to(942, 214)
quad_to(888, 136, 815.5, 82)
quad_to(743, 28, 653, 1)
quad_to(563, -26, 456, -26)
close()
move_to(662, 294)
quad_to(739, 294, 808, 326)
quad_to(877, 358, 924.5, 414.5)
quad_to(972, 471, 985, 546)
line_to(1008, 692)
quad_to(987, 681, 955, 672)
quad_to(923, 663, 887, 655.5)
quad_to(851, 648, 813.5, 641.5)
quad_to(776, 635, 742, 630)
quad_to(670, 619, 617, 596)
quad_to(564, 573, 532.5, 536.5)
quad_to(501, 500, 494, 450)
quad_to(482, 375, 529, 334.5)
quad_to(576, 294, 662, 294)
close()
";
    assert_eq!(visitor.outlines, expected);

    Ok(())
}

```

--------------------------------

### Option::and Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Demonstrates the `and` method, which returns `None` if either option is `None`, otherwise returns the second option.

```rust
let x = Some(2);
let y: Option<&str> = None;
assert_eq!(x.and(y), None);
```

```rust
let x: Option<u32> = None;
let y = Some("foo");
assert_eq!(x.and(y), None);
```

```rust
let x = Some(2);
let y = Some("foo");
assert_eq!(x.and(y), Some("foo"));
```

```rust
let x: Option<u32> = None;
let y: Option<&str> = None;
assert_eq!(x.and(y), None);
```

--------------------------------

### Option::or Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Demonstrates `or`, which returns the first option if it is `Some`, otherwise returns the second option. Arguments are eagerly evaluated.

```rust
let x = Some(2);
let y = None;
assert_eq!(x.or(y), Some(2));
```

```rust
let x = None;
let y = Some(100);
assert_eq!(x.or(y), Some(100));
```

```rust
let x = Some(2);
let y = Some(100);
assert_eq!(x.or(y), Some(2));
```

```rust
let x: Option<u32> = None;
let y = None;
assert_eq!(x.or(y), None);
```

--------------------------------

### Option::xor Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Shows `xor`, which returns `Some` if exactly one of the options is `Some`, otherwise returns `None`.

```rust
let x = Some(2);
let y: Option<u32> = None;
assert_eq!(x.xor(y), Some(2));
```

```rust
let x: Option<u32> = None;
let y = Some(2);
assert_eq!(x.xor(y), Some(2));
```

```rust
let x = Some(2);
let y = Some(2);
assert_eq!(x.xor(y), None);
```

```rust
let x: Option<u32> = None;
let y: Option<u32> = None;
assert_eq!(x.xor(y), None);
```

--------------------------------

### Implementations of ReadFrom

Source: https://docs.rs/allsorts/0.16.1/allsorts/binary/read/trait.ReadFrom.html

Examples of how the ReadFrom trait is implemented for various data structures, showing the specific binary types they read from.

```APIDOC
## Implementations of ReadFrom

### `impl ReadFrom for EbdtComponent`

*   `type ReadType = (U16Be, I8, I8)`

### `impl ReadFrom for SmallGlyphMetrics`

*   `type ReadType = ((U8, U8), (I8, I8, U8))`

### `impl ReadFrom for Range<u8, u8>`

*   `type ReadType = (U8, U8)`

### `impl ReadFrom for Range<u16, u8>`

*   `type ReadType = (U16Be, U8)`

### `impl ReadFrom for Range<u16, u16>`

*   `type ReadType = (U16Be, U16Be)`

### `impl ReadFrom for ClassRangeRecord`

*   `type ReadType = (U16Be, U16Be, U16Be)`

### `impl ReadFrom for CoverageRangeRecord`

*   `type ReadType = (U16Be, U16Be, U16Be)`

### `impl ReadFrom for FeatureTableSubstitutionRecord`

*   `type ReadType = (U16Be, U32Be)`

### `impl ReadFrom for EncodingRecord`

*   `type ReadType = (U16Be, U16Be, U32Be)`

### `impl ReadFrom for SequentialMapGroup`

*   `type ReadType = (U32Be, U32Be, U32Be)`

### `impl ReadFrom for SubHeader`

*   `type ReadType = ((U16Be, U16Be), (I16Be, U16Be))`

### `impl ReadFrom for Layer`

*   `type ReadType = (U16Be, U16Be)`

### `impl ReadFrom for StaticColorStop`

*   `type ReadType = (F2Dot14, U16Be, F2Dot14)`

### `impl ReadFrom for VarColorStop`

*   `type ReadType = (F2Dot14, U16Be, F2Dot14, U32Be)`

### `impl ReadFrom for ColorRecord`

*   `type ReadType = (U8, U8, U8, U8)`

### `impl ReadFrom for BoundingBox`

*   `type ReadType = ((I16Be, I16Be), (I16Be, I16Be))`

### `impl ReadFrom for CompositeGlyphFlag`

*   `type ReadType = U16Be`

### `impl ReadFrom for SimpleGlyphFlag`

*   `type ReadType = U8`

### `impl ReadFrom for ChainHeader`

*   `type ReadType = (U32Be, U32Be, U32Be, U32Be)`

### `impl ReadFrom for ContextualEntry`

*   `type ReadType = (U16Be, U16Be, U16Be, U16Be)`

### `impl ReadFrom for Feature`

*   `type ReadType = (U16Be, U16Be, U32Be, U32Be)`

### `impl ReadFrom for InsertionAction`

*   `type ReadType = U16Be`

### `impl ReadFrom for InsertionEntry`

*   `type ReadType = (U16Be, U16Be, U16Be, U16Be)`

### `impl ReadFrom for LigatureAction`

*   `type ReadType = U32Be`

### `impl ReadFrom for LigatureEntry`

*   `type ReadType = (U16Be, U16Be, U16Be)`

### `impl ReadFrom for LookupSegmentFmt2`

*   `type ReadType = (U16Be, U16Be, U16Be)`

### `impl ReadFrom for LookupSegmentFmt4`

*   `type ReadType = (U16Be, U16Be, U16Be)`

### `impl ReadFrom for LookupSingleFmt6`

*   `type ReadType = (U16Be, U16Be)`

### `impl ReadFrom for RearrangementEntry`

*   `type ReadType = (U16Be, U16Be)`

### `impl ReadFrom for SubtableHeader`

*   `type ReadType = (U32Be, U32Be, U32Be)`

### `impl ReadFrom for F2Dot14`

*   `type ReadType = I16Be`

### `impl ReadFrom for Fixed`

*   `type ReadType = I32Be`

### `impl ReadFrom for LangTagRecord`

*   `type ReadType = (U16Be, U16Be)`

### `impl ReadFrom for LongHorMetric`

*   `type ReadType = (U16Be, I16Be)`

### `impl ReadFrom for NameRecord`

*   `type ReadType = ((U16Be, U16Be, U16Be), (U16Be, U16Be, U16Be))`

### `impl ReadFrom for TableRecord`

*   `type ReadType = ((U32Be, U32Be), (U32Be, U32Be))`

### `impl ReadFrom for AxisValueMap`

*   `type ReadType = (F2Dot14, F2Dot14)`

### `impl ReadFrom for VariationAxisRecord`

*   `type ReadType = ((U32Be, Fixed, Fixed), (Fixed, U16Be, U16Be))`

### `impl ReadFrom for ValueRecord`

*   `type ReadType = (U32Be, U16Be, U16Be)`

### `impl ReadFrom for AxisRecord`

*   `type ReadType = (U32Be, U16Be, U16Be)`

### `impl ReadFrom for AxisValueTableFlags`

*   `type ReadType = U16Be`

### `impl ReadFrom for HmtxTableFlag`

*   `type ReadType = U8`

### `impl ReadFrom for TableDirectoryEntry`

*   `type ReadType = ((U32Be, U32Be, U32Be), (U32Be, U32Be))`
```

--------------------------------

### Get Raw Pointer to Slice Buffer

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/variable_fonts/fvar/struct.Tuple.html

Obtain a raw pointer to the start of the slice's buffer using `as_ptr`. Ensure the slice outlives the pointer and the memory is not mutated through it.

```rust
let x = &[1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
    }
}
```

--------------------------------

### Painter::new_path

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/trait.Painter.html

Starts a new path. Any previously defined path segments are discarded.

```rust
fn new_path(&mut self) -> Result<(), Self::Error>
```

--------------------------------

### ReadArrayCow Methods

Source: https://docs.rs/allsorts/0.16.1/allsorts/binary/read/enum.ReadArrayCow.html

Provides methods for interacting with the ReadArrayCow enum, such as getting its length, checking if it's empty, and reading or getting individual items.

```APIDOC
## ReadArrayCow::len

### Description
Returns the number of elements in the array.

### Signature
`pub fn len(&self) -> usize`

## ReadArrayCow::is_empty

### Description
Checks if the array is empty.

### Signature
`pub fn is_empty(&self) -> bool`

## ReadArrayCow::read_item

### Description
Reads an item at a specific index. Requires the host type to be `Copy`.

### Signature
`pub fn read_item(&self, index: usize) -> Result<T::HostType, ParseError>`

### Constraints
`T::HostType: Copy`

## ReadArrayCow::get_item

### Description
Gets an item at a specific index, returning an `Option`. Requires the host type to be `Copy`.

### Signature
`pub fn get_item(&self, index: usize) -> Option<<T as ReadUnchecked>::HostType>`

### Constraints
`T: ReadUnchecked`
`<T as ReadUnchecked>::HostType: Copy`

## ReadArrayCow::iter

### Description
Returns an iterator over the elements of the array.

### Signature
`pub fn iter<'b>(&'b self) -> ReadArrayCowIter<'a, 'b, T>`
```

--------------------------------

### Get Option as a Slice

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Use `as_slice()` to get a slice of the contained value if the Option is Some, or an empty slice if None. This unifies iteration over Options and slices.

```rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);

for i in [Some(1234_u16), None] {
    assert_eq!(i.as_ref(), i.as_slice().first());
}
```

--------------------------------

### MacStyle Initialization and Conversion

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/struct.MacStyle.html

Methods for creating MacStyle instances from scratch, from existing bit values, or from string names.

```APIDOC
## MacStyle Initialization and Conversion

### `empty()`
```rust
pub const fn empty() -> Self
```
Get a flags value with all bits unset.

### `all()`
```rust
pub const fn all() -> Self
```
Get a flags value with all known bits set.

### `from_bits(bits: u16)`
```rust
pub const fn from_bits(bits: u16) -> Option<Self>
```
Convert from a bits value. This method will return `None` if any unknown bits are set.

### `from_bits_truncate(bits: u16)`
```rust
pub const fn from_bits_truncate(bits: u16) -> Self
```
Convert from a bits value, unsetting any unknown bits.

### `from_bits_retain(bits: u16)`
```rust
pub const fn from_bits_retain(bits: u16) -> Self
```
Convert from a bits value exactly.

### `from_name(name: &str)`
```rust
pub fn from_name(name: &str) -> Option<Self>
```
Get a flags value with the bits of a flag with the given name set. This method will return `None` if `name` is empty or doesn’t correspond to any named flag.
```

--------------------------------

### Option::insert Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Demonstrates `insert`, which inserts a value into the option, returning a mutable reference. If the option already contains a value, it is dropped.

```rust
let mut opt = None;
let val = opt.insert(1);
assert_eq!(*val, 1);
assert_eq!(opt.unwrap(), 1);
let val = opt.insert(2);
assert_eq!(*val, 2);
*val = 3;
assert_eq!(opt.unwrap(), 3);
```

--------------------------------

### Get Mutable Option as a Slice

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Use `as_mut_slice()` to get a mutable slice of the contained value if the Option is Some, or an empty slice if None. This allows mutable iteration.

```rust
pub const fn as_mut_slice(&mut self) -> &mut [T]
```

--------------------------------

### ColorStop Conversions

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/struct.ColorStop.html

Demonstrates how to convert between ColorStop and other related types like StaticColorStop and VarColorStop.

```APIDOC
### impl From<StaticColorStop> for ColorStop

#### fn from(_: StaticColorStop) -> Self

Converts to this type from the input type.

### impl From<VarColorStop> for ColorStop

#### fn from(_: VarColorStop) -> Self

Converts to this type from the input type.
```

--------------------------------

### Painter::begin_layer

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/trait.Painter.html

Starts a new rendering layer. This is useful for grouping drawing operations or applying effects to a specific area.

```rust
fn begin_layer(&mut self) -> Result<(), Self::Error>
```

--------------------------------

### Get Strong Reference Count for Arc

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.LayoutCache.html

Use `Arc::strong_count` to get the number of strong (`Arc`) pointers to an allocation. This method is safe but the count can change concurrently.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```

--------------------------------

### Create a new WriteCounter

Source: https://docs.rs/allsorts/0.16.1/allsorts/binary/write/struct.WriteCounter.html

Instantiates a new, empty WriteCounter. This is the starting point for tracking byte writes.

```rust
pub fn new() -> Self>
```

--------------------------------

### ReadFrom Implementation for StaticColorStop

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/struct.StaticColorStop.html

Shows how to read a StaticColorStop from binary data.

```APIDOC
## impl ReadFrom for StaticColorStop

### Fields
- `ReadType`: (F2Dot14, U16Be, F2Dot14)

### fn read_from
- Parameters:
  - `stop_offset`: (F2Dot14)
  - `palette_index`: (u16)
  - `alpha`: (F2Dot14)
- Returns: `Self` (StaticColorStop)
```

--------------------------------

### Get Mutable Iterator Over Option Value

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Use iter_mut to get a mutable iterator that yields a mutable reference to the contained value if the Option is Some, or is empty if the Option is None.

```rust
let mut x = Some(4);
match x.iter_mut().next() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));

let mut x: Option<u32> = None;
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### CoverageRangeRecord

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/struct.CoverageRangeRecord.html

Represents a range of coverage, typically defined by start and end glyph indices and a start coverage index. It implements the ReadFrom trait for deserialization from binary data.

```APIDOC
## Struct CoverageRangeRecord

allsorts::layout

### Summary
```rust
pub struct CoverageRangeRecord { /* private fields */ }
```

### Trait Implementations

#### impl ReadFrom for CoverageRangeRecord

##### type ReadType = (U16Be, U16Be, U16Be)

##### fn read_from( (start_glyph, end_glyph, start_coverage_index): (u16, u16, u16), ) -> Self

Reads a CoverageRangeRecord from a tuple of unsigned 16-bit integers representing start glyph, end glyph, and start coverage index.
```

--------------------------------

### ReadFrom Implementation for ContextualEntry

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/morx/struct.ContextualEntry.html

Details how to read a ContextualEntry from binary data, specifying the expected data types and the read function.

```APIDOC
### impl ReadFrom for ContextualEntry

#### Type
`type ReadType = (U16Be, U16Be, U16Be, U16Be)`

#### Function
`fn read_from( (next_state, flags, mark_index, current_index): (u16, u16, u16, u16), ) -> Self`

Reads a ContextualEntry from a tuple of four u16 values.
```

--------------------------------

### type_id

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/struct.Fixed.html

Gets the `TypeId` of the Fixed struct.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
- `&self`: An immutable reference to the Fixed instance.

### Returns
- `TypeId`: The unique type identifier.
```

--------------------------------

### take

Source: https://docs.rs/allsorts/0.16.1/allsorts/binary/read/struct.ReadArrayIter.html

Creates an iterator that yields the first `n` elements.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Parameters
#### Path Parameters
- **n** (usize) - Required - The maximum number of elements to yield.

### Returns
- Take<Self>: An iterator that yields at most `n` elements.
```

--------------------------------

### Try-New-In with Allocator

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.LayoutCache.html

Shows how to attempt constructing an `Arc` with a specific allocator, returning a `Result` that indicates success or an allocation error. This allows for fallible allocation.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let five = Arc::try_new_in(5, System)?;
```

--------------------------------

### FeatureMask::bits

Source: https://docs.rs/allsorts/0.16.1/allsorts/gsub/struct.FeatureMask.html

Gets the underlying bits value of the FeatureMask.

```APIDOC
## FeatureMask::bits

### Description
Gets the underlying `u64` bits value of the `FeatureMask`.

### Signature
`fn bits(&self) -> u64`
```

--------------------------------

### Reading VarColorStop from Data

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/struct.VarColorStop.html

Demonstrates how to read a VarColorStop struct from binary data using the `read_from` method.

```APIDOC
## impl ReadFrom for VarColorStop

### fn read_from

Reads a `VarColorStop` from the provided tuple of values.

#### Parameters

*   `(stop_offset, palette_index, alpha, var_index_base)`: A tuple containing:
    *   `stop_offset: F2Dot14` - The offset of the color stop.
    *   `palette_index: u16` - The index into the color palette.
    *   `alpha: F2Dot14` - The alpha value for the color stop.
    *   `var_index_base: u32` - The base index for variable color data.
```

--------------------------------

### Arc::strong_count

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.LayoutCache.html

Gets the number of strong (`Arc`) pointers to this allocation.

```APIDOC
## Arc::strong_count

### Description
Gets the number of strong (`Arc`) pointers to this allocation.

### Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the strong count at any time, including potentially between calling this method and acting on the result.

### Signature
`pub fn strong_count(this: &Arc<T>) -> usize`

### Example
```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```
```

--------------------------------

### Example Usage of DebugVisitor

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/struct.DebugVisitor.html

Demonstrates how to use DebugVisitor to visit and print COLR glyph data from a font file. Ensure the 'tests/fonts/colr/SixtyfourConvergence-Regular-VariableFont_BLED,SCAN,XELA,YELA.ttf' path is accessible.

```rust
use allsorts::binary::read::ReadScope;
use allsorts::tables::colr::DebugVisitor;
use allsorts::tables::OpenTypeFont;
use allsorts::Font;

let buffer = read_fixture(
    "tests/fonts/colr/SixtyfourConvergence-Regular-VariableFont_BLED,SCAN,XELA,YELA.ttf",
);
let otf = ReadScope::new(&buffer).read::<OpenTypeFont<'_>>().unwrap();
let table_provider = otf.table_provider(0).expect("error reading font file");
let mut font = Font::new(table_provider).unwrap();
let mut painter = DebugVisitor;
let glyph_id = 47; // 'S'
match font.visit_colr_glyph(glyph_id, 0, &mut painter) {
    Ok(()) => {}
    Err(err) => panic!("error visiting COLR glyph: {}", err),
}
```

--------------------------------

### TryFrom and TryInto Implementations

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/glyf/struct.BoundingBox.html

Documentation for `TryFrom` and `TryInto` trait implementations.

```APIDOC
## impl<T, U> TryFrom<U> for T where U: Into<T>

### Description
Provides a fallible conversion from type `U` into type `T`.

### Type Aliases
- `Error` (Infallible): The type returned in the event of a conversion error.

### Methods
- `try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`: Performs the conversion.
```

```APIDOC
## impl<T, U> TryInto<U> for T where U: TryFrom<T>

### Description
Provides a fallible conversion from type `T` into type `U`.

### Type Aliases
- `Error` (<U as TryFrom<T>>::Error): The type returned in the event of a conversion error.

### Methods
- `try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`: Performs the conversion.
```

--------------------------------

### Arc::weak_count

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.LayoutCache.html

Gets the number of weak (`Weak`) pointers to this allocation.

```APIDOC
## Arc::weak_count

### Description
Gets the number of weak (`Weak`) pointers to this allocation.

### Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the weak count at any time, including potentially between calling this method and acting on the result.

### Signature
`pub fn weak_count(this: &Arc<T>) -> usize`

### Example
```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```
```

--------------------------------

### Dict Length

Source: https://docs.rs/allsorts/0.16.1/allsorts/cff/cff2/type.TopDict.html

Provides a method to get the number of items in the dictionary.

```APIDOC
### `pub fn len(&self) -> usize`
Returns the number of items in the dictionary.
```

--------------------------------

### Get Bit Depth of MatchingStrike

Source: https://docs.rs/allsorts/0.16.1/allsorts/bitmap/cbdt/struct.MatchingStrike.html

Returns the bit depth of this MatchingStrike.

```rust
pub fn bit_depth(&self) -> BitDepth
```

--------------------------------

### From and Into Implementations

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/struct.ValueFormat.html

These snippets illustrate the blanket implementations of `From<T>` for `T` and `Into<U>` for `T` where `U` implements `From<T>`. The `from` method returns the argument unchanged, and `into` performs a conversion.

```rust
fn from(t: T) -> T
```

```rust
fn into(self) -> U
```

--------------------------------

### CloneToUninit Implementation for T

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/cmap/struct.SubHeader.html

Shows the nightly-only experimental API for `clone_to_uninit`, which performs copy-assignment from `self` to an uninitialized destination.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)>
```

--------------------------------

### iter

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/variable_fonts/fvar/struct.Tuple.html

Returns an iterator over the slice, yielding all items from start to end.

```APIDOC
## iter(&self) -> Iter<'_, T>

### Description
Returns an iterator over the slice. The iterator yields all items from start to end.

### Parameters
None

### Response Example
```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```
```

--------------------------------

### HmtxTableFlag Bit Manipulation

Source: https://docs.rs/allsorts/0.16.1/allsorts/woff2/struct.HmtxTableFlag.html

Methods for getting and manipulating the underlying bits of the HmtxTableFlag.

```rust
pub const fn bits(&self) -> u8
```

```rust
pub fn from_name(name: &str) -> Option<Self>
```

```rust
pub const fn is_empty(&self) -> bool
```

```rust
pub const fn is_all(&self) -> bool
```

```rust
pub const fn intersects(&self, other: Self) -> bool
```

```rust
pub const fn contains(&self, other: Self) -> bool
```

```rust
pub fn insert(&mut self, other: Self)
```

```rust
pub fn remove(&mut self, other: Self)
```

```rust
pub fn toggle(&mut self, other: Self)
```

```rust
pub fn set(&mut self, other: Self, value: bool)
```

--------------------------------

### Example Usage of DebugVisitor

Source: https://docs.rs/allsorts/0.16.1/allsorts/cff/charstring/struct.DebugVisitor.html

Demonstrates how to use DebugVisitor to process a CFF font's CharString. This involves reading an OpenType font, extracting CFF table data, and then visiting the glyphs using DebugVisitor.

```rust
use allsorts::binary::read::ReadScope;
use allsorts::cff::charstring::{ArgumentsStack, CharStringVisitorContext, DebugVisitor};
use allsorts::cff::CFFError;
use allsorts::cff::{self, CFFFont, CFFVariant, CFF};
use allsorts::font::MatchingPresentation;
use allsorts::font_data::FontData;
use allsorts::tables::{OpenTypeData, OpenTypeFont};
use allsorts::{tag, Font};

fn main() -> Result<(), CFFError> {
    // Read the font
    let buffer = std::fs::read("tests/fonts/opentype/Klei.otf").unwrap();
    let otf = ReadScope::new(&buffer).read::<OpenTypeFont<'_>>()?;
    let offset_table = match otf.data {
        OpenTypeData::Single(ttf) => ttf,
        OpenTypeData::Collection(_) => unreachable!(),
    };

    let cff_table_data = offset_table
        .read_table(&otf.scope, tag::CFF)?
        .expect("missing CFF table");
    let cff = cff_table_data.read::<CFF<'_>>()?;

    // Glyph to visit
    let glyph_id = 741; // U+2116 NUMERO SIGN

    // Set up CharString visitor
    let font = &cff.fonts[0];
    let local_subrs = match &font.data {
        CFFVariant::CID(_) => None, // Will be resolved on request.
        CFFVariant::Type1(type1) => type1.local_subr_index.as_ref(),
    };

    let mut visitor = DebugVisitor;
    let variable = None;
    let mut ctx = CharStringVisitorContext::new(
        glyph_id,
        &font.char_strings_index,
        local_subrs,
        &cff.global_subr_index,
        variable,
    );
    let mut stack = ArgumentsStack {
        data: &mut [0.0; cff::MAX_OPERANDS],
        len: 0,
        max_len: cff::MAX_OPERANDS,
    };
    ctx.visit(CFFFont::CFF(font), &mut stack, &mut visitor)?;
    Ok(())
}
```

--------------------------------

### get

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/variable_fonts/fvar/struct.Tuple.html

Retrieves the normalized value for a specific variation axis identified by its index.

```APIDOC
### `pub fn get(&self, index: u16) -> Option<F2Dot14>`

Retrieve the instance value for the axis at `index`.
```

--------------------------------

### PrivateDict Creation and Access

Source: https://docs.rs/allsorts/0.16.1/allsorts/cff/type.PrivateDict.html

Demonstrates how to create a new PrivateDict and access its values using various getter methods.

```APIDOC
## PrivateDict

### Description
Represents a dictionary for private configurations, aliased from `Dict<PrivateDictDefault>`.

### Methods

#### `new()`
- **Description**: Creates a new, empty `PrivateDict`.
- **Signature**: `pub fn new() -> Self`

#### `get_with_default(key: Operator) -> Option<&[Operand]>`
- **Description**: Retrieves a slice of operands associated with the given operator, returning `None` if the key is not found.
- **Signature**: `pub fn get_with_default(&self, key: Operator) -> Option<&[Operand]>`

#### `get(key: Operator) -> Option<&[Operand]>`
- **Description**: Retrieves a slice of operands associated with the given operator, returning `None` if the key is not found.
- **Signature**: `pub fn get(&self, key: Operator) -> Option<&[Operand]>`

#### `get_i32(key: Operator) -> Option<Result<i32, ParseError>>`
- **Description**: Retrieves the `i32` value for the given operator if the operands hold a single integer. Returns `None` if the key is not found or if the value cannot be parsed as `i32`.
- **Signature**: `pub fn get_i32(&self, key: Operator) -> Option<Result<i32, ParseError>>`
```

--------------------------------

### DisplayTag Usage Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/tag/struct.DisplayTag.html

Demonstrates how to use DisplayTag to print ASCII tags as strings and non-ASCII tags as hexadecimal values. This is useful for human-readable output of font tags.

```rust
use allsorts::tag::{self, DisplayTag};

// ASCII tag comes out as a string
assert_eq!(&DisplayTag(tag::NAME).to_string(), "name");
// Non-ASCII tag comes out as hex
assert_eq!(&DisplayTag(0x12345678).to_string(), "0x12345678");

println!(
    "DisplayTag is handy for printing a tag: '{}'",
    DisplayTag(tag::CFF)
);
```

--------------------------------

### Get the entry table

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/morx/struct.RearrangementEntry.html

Retrieves a reference to the vector table of RearrangementEntry items.

```rust
fn entry_table(&self) -> &VecTable<RearrangementEntry>
```

--------------------------------

### SimpleGlyphFlag Initialization Methods

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/glyf/struct.SimpleGlyphFlag.html

Provides methods for creating SimpleGlyphFlag instances, including an empty flag, a flag with all known bits set, and conversion from raw bit values.

```rust
pub const fn empty() -> Self
```

```rust
pub const fn all() -> Self
```

```rust
pub const fn from_bits(bits: u8) -> Option<Self>
```

```rust
pub const fn from_bits_truncate(bits: u8) -> Self
```

```rust
pub const fn from_bits_retain(bits: u8) -> Self
```

--------------------------------

### Get the rearrangement verb type

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/morx/struct.RearrangementEntry.html

Retrieves the type of rearrangement specified by this entry.

```rust
pub fn verb(&self) -> RearrangementVerb
```

--------------------------------

### Get the last item

Source: https://docs.rs/allsorts/0.16.1/allsorts/tables/colr/struct.ColorStopIter.html

Consumes the iterator and returns the last element yielded.

```rust
fn last(self) -> Option<Self::Item>
```

--------------------------------

### Option::or_else Example

Source: https://docs.rs/allsorts/0.16.1/allsorts/layout/type.ValueRecord.html

Illustrates `or_else`, which returns the first option if it is `Some`, otherwise calls a closure that returns an `Option`. This is lazily evaluated.

```rust
fn nobody() -> Option<&'static str> { None }
fn vikings() -> Option<&'static str> { Some("vikings") }

assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians"));
assert_eq!(None.or_else(vikings), Some("vikings"));
assert_eq!(None.or_else(nobody), None);
```
Tokens:
Raw