str_macro/
lib.rs

1/*
2 * lib.rs
3 *
4 * str-macro - A convenience macro for strings in Rust.
5 * Copyright (c) 2019-2021 Ammon Smith
6 *
7 * str-macro is available free of charge under the terms of the MIT
8 * License. You are free to redistribute and/or modify it under those
9 * terms. It is distributed in the hopes that it will be useful, but
10 * WITHOUT ANY WARRANTY. See the LICENSE file for more details.
11 *
12 */
13
14#![deny(missing_debug_implementations, missing_docs)]
15#![forbid(unsafe_code)]
16
17//! Creates a [`String`] with the given contents.
18//!
19//! `str!` allows you to conveniently create owned [`String`]s,
20//! similar to the [`vec!`] macro found in the Rust stdlib.
21//!
22//! - Create an empty [`String`]
23//! ```
24//! # #[macro_use] extern crate str_macro;
25//! // Vec equivalent
26//! let v = vec![];
27//! assert_eq!(v, Vec::new());
28//! assert!(v.is_empty());
29//!
30//! # let _: Vec<()> = v;
31//! // String
32//! let s = str!();
33//! assert_eq!(s, String::new());
34//! assert!(s.is_empty());
35//! ```
36//!
37//! - Create an owned [`String`] from a constant [`str`] reference.
38//! ```
39//! # #[macro_use] extern crate str_macro;
40//! // Vec equivalent
41//! let v = vec!["alpha", "beta", "gamma"];
42//! assert_eq!(&v, &["alpha", "beta", "gamma"]);
43//! assert_eq!(v.len(), 3);
44//!
45//! // String
46//! let s = str!("alpha beta gamma");
47//! assert_eq!(&s, "alpha beta gamma");
48//! let _: String = s;
49//! ```
50//!
51//! - Create an owned [`String`] from an object which implements [`ToString`].
52//!
53//! Note that this is automatically implemented for anything that implements [`Display`].
54//! ```
55//! # #[macro_use] extern crate str_macro;
56//! # use std::net::Ipv4Addr;
57//! let s = str!(2194);
58//! assert_eq!(&s, "2194");
59//!
60//! let s = str!(Ipv4Addr::new(127, 0, 0, 1));
61//! assert_eq!(&s, "127.0.0.1");
62//! ```
63//!
64//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
65//! [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
66//! [`ToString`]: https://doc.rust-lang.org/std/string/trait.ToString.html
67//! [`str`]: https://doc.rust-lang.org/std/primitive.str.html
68//! [`vec!`]: https://doc.rust-lang.org/std/macro.vec.html
69
70// Definition //
71
72/// Create an owned `String`.
73///
74/// See the [crate-level documentation] for usage examples.
75///
76/// [crate-level documentation]: index.html
77#[macro_export]
78macro_rules! str {
79    () => {
80        String::new()
81    };
82    ($x:expr $(,)?) => {
83        ToString::to_string(&$x)
84    };
85}
86
87// Tests //
88
89#[cfg(test)]
90mod test {
91    #[test]
92    fn test_simple() {
93        let s: String = str!();
94        assert_eq!(s, "");
95
96        let s: String = str!("test message");
97        assert_eq!(s, "test message");
98
99        let s: String = str!(String::from("second message"));
100        assert_eq!(s, "second message");
101    }
102
103    #[test]
104    fn test_comma() {
105        let s: String = str!();
106        assert_eq!(s, "");
107
108        let s: String = str!("test message",);
109        assert_eq!(s, "test message");
110
111        let s: String = str!(String::from("second message"),);
112        assert_eq!(s, "second message");
113    }
114
115    #[derive(Debug)]
116    struct S;
117
118    impl ToString for S {
119        fn to_string(&self) -> String {
120            String::from("from struct")
121        }
122    }
123
124    #[test]
125    fn test_impl() {
126        let s: String = str!(S);
127        assert_eq!(s, "from struct");
128    }
129}
str_macro/lib.rs

str_macro/
lib.rs
