[PATCH] RustEmbed::iter(): allow returning arbitrary iterator

[Johannes Altmanninger]

I sometimes want to embed a set of files only if some Cargo features
is turned on and do something like this:

cfg_if!(
if #[cfg(my_feature)] {
#[derive(RustEmbed)]
struct Files;
} else {
type Files = EmptyEmbed;
}
);

The "EmptyEmbed" trick allows call sites to use "Files" without
conditional compilation.

Implementing "EmptyEmbed" needlessly requires knowledge of
implementation details (the "Filenames" struct). Remove this concrete
type from the trait; an iterator is enough for all reasonable uses
I can think of.

Note that implementing "EmptyEmbed" still requires use of
"EmbeddedFile" whose "Metadata" field can't be constructed by the user;
so this is currently only useful for "EmptyEmbed".
---
changelog.md | 4 ++++
src/lib.rs | 2 +-
2 files changed, 5 insertions(+), 1 deletion(-)

FWIW I'm using this patch like this.

struct EmptyEmbed;
impl RustEmbed for EmptyEmbed {
fn get(_file_path: &str) -> Option<rust_embed::EmbeddedFile> {
None
}
fn iter() -> impl Iterator<Item = std::borrow::Cow<'static, str>> {
std::iter::empty()
}
}

diff --git a/changelog.md b/changelog.md
index f375776..c91ccd7 100644
--- a/changelog.md
+++ b/changelog.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

Thanks to [Mark Drobnak](https://github.com/AzureMarker) for the changelog.

+## Unrelased
+
+ - RustEmbed::iter(): replace concrete return type with generic iterator, to make it easier to implement an empty fake embed. Thanks to Johannes Altmanninger <acl...@gmail.com>.
+
## [8.9.0] - 2025-10-31

- Ignore paths that couldn't be canonicalized. Thanks to zvolin <mac.zw...@gmail.com>.
diff --git a/src/lib.rs b/src/lib.rs
index d3558fb..aa5582c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -45,7 +45,7 @@ pub trait RustEmbed {
/// is used.
///
/// Otherwise, the files are listed from the file system on each call.
- fn iter() -> Filenames;
+ fn iter() -> impl Iterator<Item = std::borrow::Cow<'static, str>>;
}

pub use RustEmbed as Embed;
--
2.51.0.167.g6ad8021821.dirty

[Peter John]

Hi Johannes,

I have applied your patch and tested everything. Will release the changes in 8.10.0. Thanks for updating the changelog.

Regards,
Peter

[Francis DB]

I fear this has broken things for other projects.

see https://github.com/kellpossible/cargo-i18n/issues/164

Cheers,

Francis

[The Comamba]

Hi there. It seems that these changes are leading to compilation errors for some users of the package:
https://github.com/kellpossible/cargo-i18n/issues/164
Should changing a trait signature be a breaking change and lead to a new major version? I'm not sure what the correct way forward here is. I primarily wanted to make you aware. :)
Thanks, and all the best,
Simon

[Peter John]

Hi all,

Yes I was contemplating whether it has to be a major version change but since the signature was functionally same and it was not breaking any of the tests I went with a minor version.
I guess this case was missed out. I've added a fix for it in 8.11.0 and released it. Let me know if it works. I can yank v8.10.0 then.

Regards,
Peter

[The Comamba]

Thank's a lot! This fixes it for me.

[Peter John]

I've updated the website with the changes. The trait was missing a + 'static lifetime and added a test case. I've yanked v8.10.0 now and it shouldn't be available anymore.

https://pyrossh.dev/repos/rust-embed/commits/6af8ee20c3a4040be8ea2b94c221a33f6c03c797

Regards,
Peter

[Johannes Altmanninger]

On Wed, Jan 14, 2026 at 07:23:23PM -0800, Peter John wrote:
> I've updated the website with the changes. The trait was missing a +
> 'static lifetime and added a test case.

right, thanks!