lazy_static_include/
lib.rs

1/*!
2# Lazy Static Include
3
4This crate provides `lazy_static_include_bytes` and `lazy_static_include_str` macros to replace `include_bytes` and `include_str` macros.
5
6Why should we do that?
7Because the original `include_bytes` and `include_str` macros bring extra data from files into the compiled executable binary file, the time for compiling surges.
8
9High compilation time is detrimental to software development. `lazy_static_include_bytes` and `lazy_static_include_str` macros can help you **lazy load** data from files
10when you are not using the **release** profile. In other words, if you are using `include_bytes` and `include_str` macros, and you think your compilation time is too high to wait,
11you can choose to use `lazy_static_include_bytes` and `lazy_static_include_str` macros.
12
13`lazy_static_include_bytes` and `lazy_static_include_str` macros include data from files into the compiled executable binary file **only** when you are using the **release** profile.
14Be careful when you distribute your program.
15
16The paths used for `lazy_static_include_bytes` and `lazy_static_include_str` are relative to **CARGO_MANIFEST_DIR**.
17
18## Examples
19
20```rust
21use lazy_static_include::*;
22
23lazy_static_include_str! {
24    /// doc
25    TEST => "data/test.txt",
26}
27
28lazy_static_include_str! {
29    /// doc
30    pub TEST2 => ("data", "test-2.txt"),
31}
32
33assert_eq!("This is just a test text.", TEST);
34assert_eq!("Some text...", TEST2);
35```
36
37```rust
38use lazy_static_include::*;
39
40lazy_static_include_bytes! {
41    /// doc
42    TEST => "data/test.txt",
43}
44
45lazy_static_include_bytes! {
46    /// doc
47    pub TEST2 => ("data", "test-2.txt"),
48}
49
50assert_eq!("This is just a test text.".as_bytes(), TEST);
51assert_eq!("Some text...".as_bytes(), TEST2);
52```
53
54You should notice that the value created from `lazy_static_include_bytes` and `lazy_static_include_str` macros isn't equal to `&'static [u8]` or `&'static str`. If you want to get an exact `&'static [u8]` or `&'static str` reference, you can **dereference** the value.
55
56```rust
57use lazy_static_include::*;
58
59lazy_static_include_bytes! {
60    /// doc
61    TEST => "data/test.txt",
62}
63
64let data: &'static [u8] = *TEST;
65```
66
67Also, private items (without `pub`) and public items (with `pub*`) cannot be put together.
68
69## Include Array
70
71There is a special macro `lazy_static_include_array` which can include arrays from files.
72The array is fixed sized and can be one of these following types: `bool`, `char`, `usize`, `u8`, `u16`, `u32`, `u64`, `u128`, `isize`, `i8`, `i16`, `i32`, `i64`, `i128`, `f32`, `f64`, `&'static str`.
73
74Also, the `lazy_static_include_array` macro includes data from files into the compiled executable binary file **only** when you are using the **release** profile.
75Be careful when you distribute your program.
76
77The paths used for `lazy_static_include_array` are relative to **CARGO_MANIFEST_DIR**.
78
79```rust
80use lazy_static_include::*;
81
82lazy_static_include_array! {
83    /// doc
84    TEST: [u64; 5] => "data/u64_array.txt",
85}
86
87lazy_static_include_array! {
88    /// doc
89    pub TEST2: [&'static str; 3] => ("data", "string_array.txt")
90}
91
92assert_eq!(123, TEST[0]);
93assert_eq!(456, TEST[1]);
94assert_eq!(789, TEST[2]);
95assert_eq!(1000, TEST[3]);
96assert_eq!(500000000000u64, TEST[4]);
97
98assert_eq!("Hi", TEST2[0]);
99assert_eq!("Hello", TEST2[1]);
100assert_eq!("哈囉", TEST2[2]);
101```
102
103## Benchmark
104
105Using static mechanisms makes your program faster. See my benchmark result below (AMD Ryzen 9 3900X 12-Core Processor 12C/24T 3.90GHz, ran on 2020/07/02):
106
107```text
108test include_array_lazy_static   ... bench:          46 ns/iter (+/- 3)
109test include_array_native_static ... bench:          48 ns/iter (+/- 3)
110test include_array_no_static     ... bench:      22,414 ns/iter (+/- 297)
111test include_bytes_lazy_static   ... bench:         844 ns/iter (+/- 3)
112test include_bytes_native_static ... bench:         863 ns/iter (+/- 5)
113test include_bytes_no_static     ... bench:       4,764 ns/iter (+/- 189)
114test include_str_lazy_static     ... bench:         857 ns/iter (+/- 8)
115test include_str_native_static   ... bench:         842 ns/iter (+/- 10)
116test include_str_no_static       ... bench:       4,837 ns/iter (+/- 145)
117```
118
119When using the **release** profile, the performance of `lazy_static_include_*` is very close to `include_*`. That means you don't need to worry about the overhead, but just enjoy the faster compilation time.
120
121You can run the benchmark program by executing,
122
123```bash
124cargo bench
125```
126*/
127
128#[doc(hidden)]
129pub extern crate lazy_static;
130
131#[doc(hidden)]
132pub extern crate manifest_dir_macros;
133
134#[doc(hidden)]
135pub extern crate syn;
136
137mod macro_include_array;
138mod macro_include_bytes;
139mod macro_include_str;
lazy_static_include/lib.rs

lazy_static_include/
lib.rs
