Add include_bytes! macro

[joshlf]

The include_bytes! macro is like the macro from core of the same name, except that it transmutes the file's contents to an arbitrary type (which implements FromBytes).

TODO:

• Change the example usage in the doc comment to use something more complex like the fixed-length header of a file format?
  • As discussed here, better to have a focused example that doesn't distract with other details.
• Are there other variants we should introduce? Perhaps one for slice types? Can we design it in such a way that it would work with other (non-slice) DSTs in the future if we add support for those?
  • Per Idea for supporting experimentation and providing early access to features #524 (comment), we're not trying to plan this far out anymore.

[jswrenn]

Nice! When I blogged about this a few years ago, I opted to match the standard library's behavior of returning a reference. I.e., this:

#[macro_export]
macro_rules! include_bytes {
    ($file:expr $(,)?) => {
        &$crate::transmute!(*::core::include_bytes!($file))
    };
}

I think it's fine to deviate from the standard library, but we probably should have some principled idea of why we're doing so.

[joshlf]

Nice! When I blogged about this a few years ago, I opted to match the standard library's behavior of returning a reference. I.e., this:

#[macro_export]
macro_rules! include_bytes {
    ($file:expr $(,)?) => {
        &$crate::transmute!(*::core::include_bytes!($file))
    };
}

I think it's fine to deviate from the standard library, but we probably should have some principled idea of why we're doing so.

tbh I think the stdlib is wrong here, but I agree that we should mirror it unless we have a good reason to diverge. Done.

[joshlf]

Nice! When I blogged about this a few years ago, I opted to match the standard library's behavior of returning a reference. I.e., this:

#[macro_export]
macro_rules! include_bytes {
    ($file:expr $(,)?) => {
        &$crate::transmute!(*::core::include_bytes!($file))
    };
}

I think it's fine to deviate from the standard library, but we probably should have some principled idea of why we're doing so.

tbh I think the stdlib is wrong here, but I agree that we should mirror it unless we have a good reason to diverge. Done.

Actually wait: what about non-Copy types? In the stdlib's case, the type is always [u8; N], and thus always Copy. We don't have that luxury, and so returning a reference would presumably mean that users of non-Copy types could never dereference the return value.

[jswrenn]

Agreed — I think that's a good reason for us to not return a reference.

[joshlf]

Agreed — I think that's a good reason for us to not return a reference.

Done.