Crate quickphf_codegen

quickphf_codegen is a Rust crate that allows you to generate static hash maps and hash sets at compile-time using PTHash perfect hash functions.

For the runtime code necessary to use these data structures check out the quickphf crate instead.

The minimum supported Rust version is 1.56. This crate uses #![forbid(unsafe_code)].

WARNING: quickphf and quickphf_codegen currently use the standard library Hash trait which is not portable between platforms with different endianness.

Example

Currently, the only way to generate data structures for use with quickphf is by running one of build_raw_map, build_map, or build_set, displaying the result as a string, and then importing the resulting Rust code at the desired location.

For example, you can write a build.rs script such as:

use std::env;
use std::fs::File;
use std::io::{BufWriter, Write};
use std::path::Path;

fn main() {
    let path = Path::new(&env::var("OUT_DIR").unwrap()).join("codegen.rs");
    let mut file = BufWriter::new(fs::File::create(&path).unwrap());

    let keys = ["jpg", "png", "svg"];
    let values = ["image/jpeg", "image/png", "image/svg+xml"];
    let code = quickphf_codegen::build_map(&keys, &values);

    write!(&mut file, code).unwrap();
}

and then import the result in your lib.rs by:

static MIME_TYPES: quickphf::PhfMap<&'static str, &'static str> =
    include!(concat!(env!("OUT_DIR"), "/codegen.rs"));

Advanced Usage

Using QuickPHF with custom types

To be usable as a key in a PhfMap or PhfSet, or as value in a RawPhfMap or a PhfMap, a type must implement the trait ConstInstantiable, which provides a way to generate code which instantiates any value of that type in a const context. This trait is already implemented for many built-in types, but users can also implement it for their own custom types, by one of two ways:

1. If the code required to instantiate a value of a type is identical to its Debug representation, for example, like the following enum:

#[derive(Debug, Hash, PartialEq, Eq)]
enum PositionType {
    Contract { pub hours_per_week: u32 },
    Salaried,
    Managerial,
}

then it suffices to write

impl quickphf_codegen::DebugInstantiable for PositionType {}

2. Otherwise, the user has to provide a custom implementation. For example, the following struct has private fields and thus its values cannot be instantiated using the {} syntax, but provides a new constructor that is a const fn. Thus, given

#[derive(Debug, Hash, PartialEq, Eq)]
struct EmploymentRules {
    overtime_eligible: bool,
    bonus_eligible: bool,
}

impl EmploymentRules {
    pub const fn new(overtime_eligible: bool, bonus_eligible: bool) -> EmploymentRules {
        EmploymentRules {
            overtime_eligible,
            bonus_eligible,
        }
    }
}

we can provide a custom ConstInstantiable implementation by

use core::fmt;
use quickphf_codegen::*;

impl ConstInstantiable for EmploymentRules {
    fn fmt_const_new(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "EmploymentRules::new({}, {})",
            self.overtime_eligible, self.bonus_eligible
        )
    }
}

Modules

phf

Code for generating a PTHash-based perfect hash function.

Structs

CodeWriter

Code generator for a PTHash perfect hash function hash table structure.

Traits

ConstInstantiable

Provides a way to generate code which instantiates values of the implementing type in a const context.

DebugInstantiable

Provides blanket implementation of ConstInstantiable which defers to Debug representation of type.

Functions

build_map

Generate code for a static quickphf::PhfMap.

build_raw_map

Generate code for a static quickphf::RawPhfMap.

build_set

Generate code for a static quickphf::PhfSet.