byte_strings/
lib.rs

1#![doc = include_str!("../README.md")]
2#![no_std]
3
4// Fix rendering of `<details><summary>` within bulleted lists:
5// Credit for this marvelous hack go to: https://github.com/rust-lang/cargo/issues/331#issuecomment-479847157
6#![doc(html_favicon_url = "\">
7<style>
8summary {
9    display: list-item;
10}
11</style>
12<meta name=\"")]
13
14pub use crate::concat_bytes as as_bytes;
15
16/// Concatenates (byte) string literals into a single byte string literal.
17///
18/// This macro takes any number of comma-separated (byte) string literals,
19/// and evaluates to (a static reference to) a byte array made of all the
20/// bytes of the given byte string literals concatenated left-to-right.
21///
22/// Hence the macro evaluates to the type `&'static [u8; N]`
23/// (where N is the total number of bytes), which can also "be seen as"
24/// (coerce to) a static byte slice (_i.e.,_ `&'static [u8]`).
25///
26/// # Example
27///
28/// ```rust,edition2018
29/// use ::byte_strings::concat_bytes;
30///
31/// let bytes = concat_bytes!(b"Hello, ", b"World!");
32/// assert_eq!(bytes, b"Hello, World!");
33/// ```
34///
35/// ### Macro expansion:
36///
37/// `concat_bytes!(b"Hello, ", b"World!")`
38/// expands to
39/// `b"Hello, World!"`
40#[macro_export]
41macro_rules! concat_bytes {(
42    $($expr:expr),* $(,)?
43) => (
44    $crate::__::concat_bytes!(
45        [$crate]
46        $($expr),*
47    )
48)}
49
50/// Converts into a valid [C string] at compile time (no runtime cost)
51///
52/// This macro takes any number of comma-separated byte string literals,
53/// or string literals,
54/// and evaluates to (a static reference to) a [C string]
55/// made of all the bytes of the given literals concatenated left-to-right,
56/// **with an appended null byte terminator**.
57///
58/// Hence the macro evaluates to the type `&'static ::core::ffi::CStr`.
59///
60/// # Example
61///
62/// ```rust,edition2018
63/// use ::byte_strings::c_str;
64///
65/// assert_eq!(
66///     c_str!("Hello, ", "World!"),
67///     ::std::ffi::CStr::from_bytes_with_nul(b"Hello, World!\0").unwrap(),
68/// )
69/// ```
70///
71/// # Compilation error
72///
73/// For the [C string] to be what should be expected,
74/// **the arguments cannot contain any null byte**.
75/// Else the compilation will fail.
76///
77/// # Counter example
78///
79/// ```rust,compile_fail
80/// # use ::byte_strings::c_str;
81/// // error: input literals cannot contain null bytes
82/// let hello_w = c_str!("Hello, ", "W\0rld!");
83/// ```
84///
85/// ### Macro expansion:
86///
87/// ```rust
88/// const _: &str = stringify! {
89/// c_str!("Hello, ", "World!")
90/// # };
91/// ```
92///
93/// expands to
94///
95/// ```rust
96/// unsafe {
97///     ::std::ffi::CStr::from_bytes_with_nul_unchecked(b"Hello, World!\0")
98/// }
99/// # ;
100/// ```
101#[macro_export]
102macro_rules! c_str {(
103    $($literal:expr),* $(,)?
104) => (
105    $crate::__::c_str!(
106        [$crate]
107        $($literal),*
108    )
109)}
110
111/// Shorthand alias.
112pub use c_str as c;
113
114// macro internals
115#[doc(hidden)] /** Not part of the public API */ pub
116mod __ {
117    pub use {
118        ::byte_strings_proc_macros::*,
119        ::core,
120    };
121}
122
123#[path = "const.rs"]
124pub mod const_;
125
126#[cfg_attr(feature = "ui-tests",
127    cfg_attr(all(), doc = include_str!("compile_fail_tests.md")),
128)]
129mod _compile_fail_tests {}
byte_strings/lib.rs

byte_strings/
lib.rs
