Crate constuneval[][src]

Simple Cow focussed serializer for generating const Rust code using Debug trait.

Usage

In general, to embed some code(tables/struct) into crate, you have to use the build script and include! macro. Inside the build script, you'll generate some code with one of the to_file(), to_string() provided by constuneval, and then include the generated file, like this:

include!(concat!(env!(OUT_DIR), "/file_name.rs"));

Also this crate provides a fork of UnevalCow but with better serialization though Debug trait

How does it work?

To keep things simple all the formatting/serialization is done with help of Debug trait. For most types such as struct, enum, Vec, etc it works fine, but not for Deref like types like Cow as their Debug essentially deref before formatting. To address this crate also provides UnevalCow as a substitute to std::borrow::Cow.

Of course, we can't always directly construct the code for the desired value (more on this in the Limitations section below).

Example

use constuneval::{to_file, to_string, UnevalCow};
use std::fmt;

#[derive(Debug)]
pub struct FftDomain<F>
where
    [F]: 'static + ToOwned + fmt::Debug,
    <[F] as std::borrow::ToOwned>::Owned: fmt::Debug,
{
    pub some_table: UnevalCow<'static, [UnevalCow<'static, [F]>]>,
}
 
// some build time generated struct table
let fft_temp = FftDomain {
    some_table: UnevalCow::Owned(vec![
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
        UnevalCow::Owned(vec![1, 2, 3, 4, 5]),
    ]),
};
 
 
to_file(
    std::path::Path::new("const_fft_tables.rs"),
    "FFT_TABLE",
    &fft_temp,
    Some("FftDomain<'static, i32>"),
)
.expect("Write Failed");

content of const_fft_tables.rs (after running rustfmt on it)

const FFT_TABLE: FftDomain<'static, i32> = FftDomain {
    some_table: UnevalCow::Borrowed(&[
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
        UnevalCow::Borrowed(&[1, 2, 3, 4, 5]),
    ]),
};

Now this file/code can be embed into crate using include! macro.

Limitations

There are some cases when constuneval will be unable to generate valid code. Namely:

  1. This serializer is intended for use with types with well implemented Debug trait. It may not work if Debug trait is producing invalid outputs.

Re-exports

pub use uneval_cow::UnevalCow;

Modules

uneval_cow

Fork of std::borrow::UnevalCow with more proper Debug trait.

Functions

to_file

Generate the const Rust code and write it to temporary file

to_string

Obtain string with generated const Rust code.