byte-strings 0.3.1

Rust byte strings manipulation, for a better and safer C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

#![doc = include_str!("../README.md")]
#![no_std]

// Fix rendering of `<details><summary>` within bulleted lists:
// Credit for this marvelous hack go to: https://github.com/rust-lang/cargo/issues/331#issuecomment-479847157
#![doc(html_favicon_url = "\">
<style>
summary {
    display: list-item;
}
</style>
<meta name=\"")]

pub use crate::concat_bytes as as_bytes;

/// Concatenates (byte) string literals into a single byte string literal.
///
/// This macro takes any number of comma-separated (byte) string literals,
/// and evaluates to (a static reference to) a byte array made of all the
/// bytes of the given byte string literals concatenated left-to-right.
///
/// Hence the macro evaluates to the type `&'static [u8; N]`
/// (where N is the total number of bytes), which can also "be seen as"
/// (coerce to) a static byte slice (_i.e.,_ `&'static [u8]`).
///
/// # Example
///
/// ```rust,edition2018
/// use ::byte_strings::concat_bytes;
///
/// let bytes = concat_bytes!(b"Hello, ", b"World!");
/// assert_eq!(bytes, b"Hello, World!");
/// ```
///
/// ### Macro expansion:
///
/// `concat_bytes!(b"Hello, ", b"World!")`
/// expands to
/// `b"Hello, World!"`
#[macro_export]
macro_rules! concat_bytes {(
    $($expr:expr),* $(,)?
) => (
    $crate::__::concat_bytes!(
        [$crate]
        $($expr),*
    )
)}

/// Converts into a valid [C string] at compile time (no runtime cost)
///
/// This macro takes any number of comma-separated byte string literals,
/// or string literals,
/// and evaluates to (a static reference to) a [C string]
/// made of all the bytes of the given literals concatenated left-to-right,
/// **with an appended null byte terminator**.
///
/// Hence the macro evaluates to the type `&'static ::core::ffi::CStr`.
///
/// # Example
///
/// ```rust,edition2018
/// use ::byte_strings::c_str;
///
/// assert_eq!(
///     c_str!("Hello, ", "World!"),
///     ::std::ffi::CStr::from_bytes_with_nul(b"Hello, World!\0").unwrap(),
/// )
/// ```
///
/// # Compilation error
///
/// For the [C string] to be what should be expected,
/// **the arguments cannot contain any null byte**.
/// Else the compilation will fail.
///
/// # Counter example
///
/// ```rust,compile_fail
/// # use ::byte_strings::c_str;
/// // error: input literals cannot contain null bytes
/// let hello_w = c_str!("Hello, ", "W\0rld!");
/// ```
///
/// ### Macro expansion:
///
/// ```rust
/// const _: &str = stringify! {
/// c_str!("Hello, ", "World!")
/// # };
/// ```
///
/// expands to
///
/// ```rust
/// unsafe {
///     ::std::ffi::CStr::from_bytes_with_nul_unchecked(b"Hello, World!\0")
/// }
/// # ;
/// ```
#[macro_export]
macro_rules! c_str {(
    $($literal:expr),* $(,)?
) => (
    $crate::__::c_str!(
        [$crate]
        $($literal),*
    )
)}

/// Shorthand alias.
pub use c_str as c;

// macro internals
#[doc(hidden)] /** Not part of the public API */ pub
mod __ {
    pub use {
        ::byte_strings_proc_macros::*,
        ::core,
    };
}

#[path = "const.rs"]
pub mod const_;

#[cfg_attr(feature = "ui-tests",
    cfg_attr(all(), doc = include_str!("compile_fail_tests.md")),
)]
mod _compile_fail_tests {}