Struct Database

pub struct Database { /* private fields */ }

A font database.

Implementations

impl Database

pub fn new() -> Database

Create a new, empty Database.

Generic font families would be set to:

• serif - Times New Roman
• sans-serif - Arial
• cursive - Comic Sans MS
• fantasy - Impact (Papyrus on macOS)
• monospace - Courier New

pub fn load_font_data(&mut self, data: Vec<u8>)

Loads a font data into the Database.

Will load all font faces in case of a font collection.

pub fn load_font_source(&mut self, source: Source) -> TinyVec<[ID; 8]>

Loads a font from the given source into the Database and returns the ID of the loaded font.

Will load all font faces in case of a font collection.

pub fn load_font_file<P>(&mut self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

Loads a font file into the Database.

Will load all font faces in case of a font collection.

pub fn load_fonts_dir<P>(&mut self, dir: P)

where P: AsRef<Path>,

Loads font files from the selected directory into the Database.

This method will scan directories recursively.

Will load ttf, otf, ttc and otc fonts.

Unlike other load_* methods, this one doesn’t return an error. It will simply skip malformed fonts and will print a warning into the log for each of them.

pub fn load_system_fonts(&mut self)

Attempts to load system fonts.

Supports Windows, Linux and macOS.

System fonts loading is a surprisingly complicated task, mostly unsolvable without interacting with system libraries. And since fontdb tries to be small and portable, this method will simply scan some predefined directories. Which means that fonts that are not in those directories must be added manually.

pub fn push_face_info(&mut self, info: FaceInfo)

Pushes a user-provided FaceInfo to the database.

In some cases, a caller might want to ignore the font’s metadata and provide their own. This method doesn’t parse the source font.

The id field should be set to ID::dummy() and will be then overwritten by this method.

pub fn remove_face(&mut self, id: ID)

Removes a font face by id from the database.

Returns false while attempting to remove a non-existing font face.

Useful when you want to ignore some specific font face(s) after loading a large directory with fonts. Or a specific face from a font.

pub fn is_empty(&self) -> bool

Returns true if the Database contains no font faces.

pub fn len(&self) -> usize

Returns the number of font faces in the Database.

Note that Database stores font faces, not fonts. For example, if a caller will try to load a font collection (*.ttc) that contains 5 faces, then the Database will load 5 font faces and this method will return 5, not 1.

pub fn set_serif_family<S>(&mut self, family: S)

where S: Into<String>,

Sets the family that will be used by Family::Serif.

pub fn set_sans_serif_family<S>(&mut self, family: S)

where S: Into<String>,

Sets the family that will be used by Family::SansSerif.

pub fn set_cursive_family<S>(&mut self, family: S)

where S: Into<String>,

Sets the family that will be used by Family::Cursive.

pub fn set_fantasy_family<S>(&mut self, family: S)

where S: Into<String>,

Sets the family that will be used by Family::Fantasy.

pub fn set_monospace_family<S>(&mut self, family: S)

where S: Into<String>,

Sets the family that will be used by Family::Monospace.

pub fn family_name<'a>(&'a self, family: &'a Family<'_>) -> &'a str

Returns the generic family name or the Family::Name itself.

Generic family names should be set via Database::set_*_family methods.

pub fn query(&self, query: &Query<'_>) -> Option<ID>

Performs a CSS-like query and returns the best matched font face.

pub fn faces(&self) -> impl Iterator<Item = &FaceInfo>

Returns an iterator over the internal storage.

This can be used for manual font matching.

pub fn face(&self, id: ID) -> Option<&FaceInfo>

Selects a FaceInfo by id.

Returns None if a face with such ID was already removed, or this ID belong to the other Database.

pub fn face_source(&self, id: ID) -> Option<(Source, u32)>

Returns font face storage and the face index by ID.

pub fn with_face_data<P, T>(&self, id: ID, p: P) -> Option<T>

where P: FnOnce(&[u8], u32) -> T,

Executes a closure with a font’s data.

We can’t return a reference to a font binary data because of lifetimes. So instead, you can use this method to process font’s data.

The closure accepts raw font data and font face index.

In case of Source::File, the font file will be memory mapped.

Returns None when font file loading failed.

Example

let is_variable = db.with_face_data(id, |font_data, face_index| {
    let font = ttf_parser::Face::from_slice(font_data, face_index).unwrap();
    font.is_variable()
})?;

pub unsafe fn make_shared_face_data( &mut self, id: ID, ) -> Option<(Arc<dyn AsRef<[u8]> + Sync + Send>, u32)>

Makes the font data that backs the specified face id shared so that the application can hold a reference to it.

Safety

If the face originates from a file from disk, then the file is mapped from disk. This is unsafe as another process may make changes to the file on disk, which may become visible in this process’ mapping and possibly cause crashes.

If the underlying font provides multiple faces, then all faces are updated to participate in the data sharing. If the face was previously marked for data sharing, then this function will return a clone of the existing reference.

pub fn make_face_data_unshared(&mut self, id: ID)

Transfers ownership of shared font data back to the font database. This is the reverse operation of Self::make_shared_face_data. If the font data belonging to the specified face is mapped from a file on disk, then that mapping is closed and the data becomes private to the process again.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Database

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

Formats the value using the given formatter.

impl Default for Database

fn default() -> Database

Returns the “default value” for a type.