123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140 |
- // Copyright (c) 2016-2019, The Tor Project, Inc. */
- // See LICENSE for licensing information */
- //! Utilities for working with static strings.
- /// Create a `CStr` from a literal byte slice, appending a NUL byte to it first.
- ///
- /// # Warning
- ///
- /// The literal byte slice which is taken as an argument *MUST NOT* have any NUL
- /// bytes (`b"\0"`) in it, anywhere, or else an empty string will be returned
- /// (`CStr::from_bytes_with_nul_unchecked(b"\0")`) so as to avoid `panic!()`ing.
- ///
- /// # Examples
- ///
- /// ```
- /// #[macro_use]
- /// extern crate tor_util;
- ///
- /// use std::ffi::CStr;
- ///
- /// # fn do_test() -> Result<&'static CStr, &'static str> {
- /// let message: &'static str = "This is a test of the tsunami warning system.";
- /// let tuesday: &'static CStr;
- /// let original: &str;
- ///
- /// tuesday = cstr!("This is a test of the tsunami warning system.");
- /// original = tuesday.to_str().or(Err("Couldn't unwrap CStr!"))?;
- ///
- /// assert!(original == message);
- /// #
- /// # Ok(tuesday)
- /// # }
- /// # fn main() {
- /// # do_test(); // so that we can use the ? operator in the test
- /// # }
- /// ```
- /// It is also possible to pass several string literals to this macro. They
- /// will be concatenated together in the order of the arguments, unmodified,
- /// before finally being suffixed with a NUL byte:
- ///
- /// ```
- /// #[macro_use]
- /// extern crate tor_util;
- /// #
- /// # use std::ffi::CStr;
- /// #
- /// # fn do_test() -> Result<&'static CStr, &'static str> {
- ///
- /// let quux: &'static CStr = cstr!("foo", "bar", "baz");
- /// let orig: &'static str = quux.to_str().or(Err("Couldn't unwrap CStr!"))?;
- ///
- /// assert!(orig == "foobarbaz");
- /// # Ok(quux)
- /// # }
- /// # fn main() {
- /// # do_test(); // so that we can use the ? operator in the test
- /// # }
- /// ```
- /// This is useful for passing static strings to C from Rust FFI code. To do so
- /// so, use the `.as_ptr()` method on the resulting `&'static CStr` to convert
- /// it to the Rust equivalent of a C `const char*`:
- ///
- /// ```
- /// #[macro_use]
- /// extern crate tor_util;
- ///
- /// use std::ffi::CStr;
- /// use std::os::raw::c_char;
- ///
- /// pub extern "C" fn give_static_borrowed_string_to_c() -> *const c_char {
- /// let hello: &'static CStr = cstr!("Hello, language my parents wrote.");
- ///
- /// hello.as_ptr()
- /// }
- /// # fn main() {
- /// # let greetings = give_static_borrowed_string_to_c();
- /// # }
- /// ```
- /// Note that the C code this static borrowed string is passed to *MUST NOT*
- /// attempt to free the memory for the string.
- ///
- /// # Note
- ///
- /// An unfortunate limitation of the rustc compiler (as of 1.25.0-nightly), is
- /// that the first example above compiles, but if we were to change the
- /// assignment of `tuesday` as follows, it will fail to compile, because Rust
- /// macros are expanded at parse time, and at parse time there is no symbol
- /// table available.
- ///
- /// ```ignore
- /// tuesday = cstr!(message);
- /// ```
- /// with the error message `error: expected a literal`.
- ///
- /// # Returns
- ///
- /// If the string literals passed as arguments contain no NUL bytes anywhere,
- /// then an `&'static CStr` containing the (concatenated) bytes of the string
- /// literal(s) passed as arguments, with a NUL byte appended, is returned.
- /// Otherwise, an `&'static CStr` containing a single NUL byte is returned (an
- /// "empty" string in C).
- #[macro_export]
- macro_rules! cstr {
- ($($bytes:expr),*) => (
- ::std::ffi::CStr::from_bytes_with_nul(
- concat!($($bytes),*, "\0").as_bytes()
- ).unwrap_or(
- unsafe{
- ::std::ffi::CStr::from_bytes_with_nul_unchecked(b"\0")
- }
- )
- )
- }
- #[cfg(test)]
- mod test {
- use std::ffi::CStr;
- #[test]
- fn cstr_macro() {
- let _: &'static CStr = cstr!("boo");
- }
- #[test]
- fn cstr_macro_multi_input() {
- let quux: &'static CStr = cstr!("foo", "bar", "baz");
- assert!(quux.to_str().unwrap() == "foobarbaz");
- }
- #[test]
- fn cstr_macro_bad_input() {
- let waving: &'static CStr = cstr!("waving not drowning o/");
- let drowning: &'static CStr = cstr!("\0 drowning not waving");
- assert!(waving.to_str().unwrap() == "waving not drowning o/");
- assert!(drowning.to_str().unwrap() == "")
- }
- }
|