rust_embed/
lib.rs

Help
1#![forbid(unsafe_code)]
2#[cfg(feature = "compression")]
3#[cfg_attr(feature = "compression", doc(hidden))]
4pub use include_flate::flate;
5
6#[allow(unused_imports)]
7#[macro_use]
8extern crate rust_embed_impl;
9pub use rust_embed_impl::*;
10
11pub use rust_embed_utils::{EmbeddedFile, Metadata};
12
13#[doc(hidden)]
14pub extern crate rust_embed_utils as utils;
15
16/// A directory of binary assets.
17///
18/// The files in the specified folder will be embedded into the executable in
19/// release builds. Debug builds will read the data from the file system at
20/// runtime.
21///
22/// This trait is meant to be derived like so:
23/// ```
24/// use rust_embed::RustEmbed;
25///
26/// #[derive(RustEmbed)]
27/// #[folder = "examples/public/"]
28/// struct Asset;
29///
30/// fn main() {}
31/// ```
32pub trait RustEmbed {
33  /// Get an embedded file and its metadata.
34  ///
35  /// If the feature `debug-embed` is enabled or the binary was compiled in
36  /// release mode, the file information is embedded in the binary and the file
37  /// data is returned as a `Cow::Borrowed(&'static [u8])`.
38  ///
39  /// Otherwise, the information is read from the file system on each call and
40  /// the file data is returned as a `Cow::Owned(Vec<u8>)`.
41  fn get(file_path: &str) -> Option<EmbeddedFile>;
42
43  /// Iterates over the file paths in the folder.
44  ///
45  /// If the feature `debug-embed` is enabled or the binary is compiled in
46  /// release mode, a static array containing the list of relative file paths
47  /// is used.
48  ///
49  /// Otherwise, the files are listed from the file system on each call.
50  fn iter() -> Filenames;
51}
52
53/// An iterator over filenames.
54///
55/// This enum exists for optimization purposes, to avoid boxing the iterator in
56/// some cases. Do not try and match on it, as different variants will exist
57/// depending on the compilation context.
58pub enum Filenames {
59  /// Release builds use a named iterator type, which can be stack-allocated.
60  #[cfg(any(not(debug_assertions), feature = "debug-embed"))]
61  Embedded(std::slice::Iter<'static, &'static str>),
62
63  /// The debug iterator type is currently unnameable and still needs to be
64  /// boxed.
65  #[cfg(all(debug_assertions, not(feature = "debug-embed")))]
66  Dynamic(Box<dyn Iterator<Item = std::borrow::Cow<'static, str>>>),
67}
68
69impl Iterator for Filenames {
70  type Item = std::borrow::Cow<'static, str>;
71  fn next(&mut self) -> Option<Self::Item> {
72    match self {
73      #[cfg(any(not(debug_assertions), feature = "debug-embed"))]
74      Filenames::Embedded(names) => names.next().map(|x| std::borrow::Cow::from(*x)),
75
76      #[cfg(all(debug_assertions, not(feature = "debug-embed")))]
77      Filenames::Dynamic(boxed) => boxed.next(),
78    }
79  }
80}
rust_embed/lib.rs

rust_embed/
lib.rs
