Include_bytes

Sometimes it is useful to include byte data directly inside an executable. The Rust program could read in this data from a file at startup, but this is not always necessary.

Instead, with the include_bytes macro, we can access a file's data directly in the Rust program at compile-time. We can run const functions on it to test and process it.

Example

We use the include_bytes macro in this Rust program. At compile-time the file is included, and we create a modified copy and test the data with const functions.

// Part 1: include this text file directly inside executable.
const DATA: &[u8] = include_bytes!("../../example.txt");

// Part 2: use constant functions to process the constant data at compile-time.
const DATA_UPPERCASE: &[u8] = &uppercase(DATA);
const HAS_LETTER_X: bool = has_letter_x(DATA);

const fn uppercase(data: &[u8]) -> [u8; DATA.len()] {
    let mut result = [0; DATA.len()];
    let mut i = 0;
    while i < data.len() {
        result[i] = data[i].to_ascii_uppercase();
        i += 1;
    }
    result
}

const fn has_letter_x(data: &[u8]) -> bool {
    let mut i = 0;
    while i < data.len() {
        if data[i] == b'x' {
            return true;
        }
        i += 1;
    }
    false
}

fn main() {
    // Part 3: display the constant data.
    let value = String::from_utf8_lossy(DATA).to_string();
    println!("String: [{}]", value);

    let value = String::from_utf8_lossy(DATA_UPPERCASE).to_string();
    println!("String uppercase: [{}]", value);

    println!("Has letter x: [{}]", HAS_LETTER_X);
}
String: [Some example text]
String uppercase: [SOME EXAMPLE TEXT]
Has letter x: [true]

Summary

For small files, include_bytes is useful. For larger files, the Rust compiler will cause errors and warnings about constant functions that run too long.

Because of this, it is best to only use include_bytes on smaller files. Code being evaluated in const functions can sometimes be slower than expected as well.