devela/text/str/
macros.rs

Help
1// devela::text::str::macros
2//
3//! Defines the [`str!`] and [`strjoin!`] macros.
4//
5
6/// Joins multiple string slices in compile-time.
7///
8/// # Example
9/// ```
10/// # use devela::{strjoin, const_assert};
11/// const BASE: &str = "path/to";
12/// const PART1: &str = "/foo";
13/// const PART2: &str = "/bar";
14/// const PATH: &str = strjoin!(BASE, PART1, PART2);
15/// const_assert![eq_str PATH, "path/to/foo/bar"];
16/// ```
17/// # Features
18/// Makes use of the `unsafe_str` feature if available.
19//
20// - source: https://users.rust-lang.org/t/concatenate-const-strings/51712/7
21// - modifications:
22//   - make unsafe optional.
23//   - support the trivial cases.
24//   - suport more than 2 arguments.
25//   - simplify reassignments and loop.
26#[doc(hidden)]
27#[macro_export]
28#[rustfmt::skip]
29macro_rules! strjoin {
30    // trivial cases:
31    () => { "" };
32    ($A:expr) => { $A };
33    // variadic case: Reduce to two-argument case:
34    ($A:expr, $B:expr, $($rest:expr),+) => {
35        $crate::strjoin!($A, $crate::strjoin!($B, $($rest),+))
36    };
37    ($A:expr, $B:expr) => {{
38        const fn combined() -> [u8; LEN] {
39            let mut out = [0u8; LEN];
40            out = copy_slice(A.as_bytes(), out, 0);
41            copy_slice(B.as_bytes(), out, A.len())
42        }
43        const fn copy_slice(input: &[u8], mut output: [u8; LEN], offset: usize) -> [u8; LEN] {
44            let mut index = 0;
45            while index < input.len() {
46                output[offset + index] = input[index];
47                index += 1;
48            }
49            output
50        }
51        const A: &str = $A;
52        const B: &str = $B;
53        const LEN: usize = A.len() + B.len();
54        const RESULT: &[u8] = &combined();
55        #[cfg(any(feature = "safe_text", not(feature = "unsafe_str")))]
56        { $crate::unwrap!(ok::core::str::from_utf8(RESULT)) }
57        #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
58        unsafe { ::core::str::from_utf8_unchecked(RESULT) }
59    }};
60}
61#[doc(inline)]
62pub use strjoin;
63
64/// [`&str`] compile-time operations, namespaced from the [const-str][::const_str] crate.
65///
66/// - The name of each operation links to the official macro documentation.
67/// - Each operation is prefixed to document their const-compatibility:
68///   - ƒ&nbsp; means const-fn compatible (can use runtime-context arguments).
69///   - ≡ means const-context only compatible (restricted to const-context arguments).
70///
71/// # Operations
72// /// - ƒ &nbsp;[`chain`][::const_str::chain]
73// ///   Chains multiple macro calls together.
74/// - ƒ &nbsp;[`compare`][::const_str::compare]
75///   Compares two [`&str`] lexicographically.
76/// - ≡ [`concat`][::const_str::concat]
77///   Concatenates ([`&str`] | [`char`] | [`bool`] | `u*` | `i*`) into a [`&str`].
78/// - ≡ [`concat_bytes`][::const_str::concat_bytes] Concatenates ([`&str`] | [`u8`]
79///   | [`&[u8]`](slice) | [`[u8; N]`](array) | [`&[u8; N]`](array)) to [`&[u8; _]`](array).
80/// - ƒ &nbsp;[`contains`][::const_str::contains]
81///   Returns [`true`] if the given pattern ([`&str`] | [`char`]) matches a sub-[`&str`].
82/// - ≡ [`cstr`][::const_str::cstr]
83///   Converts a [`&str`] to [`&CStr`](core::ffi::CStr).
84/// - ≡ [`encode`][::const_str::encode]
85///   Encodes a [`&str`] with an encoding (`utf8` | `utf16`).
86/// - ≡ [`encode_z`][::const_str::encode_z]
87///   Encodes a [`&str`] with an encoding (`utf8` | `utf16`) and append a NUL char.
88/// - ƒ &nbsp;[`ends_with`][::const_str::ends_with]
89///   Returns `true` if the given pattern matches a suffix of this [`&str`].
90/// - ƒ &nbsp;[`equal`][::const_str::equal]
91///   Returns [`true`] if two [`&str`] are equal.
92/// - ≡ [`from_utf8`][::const_str::from_utf8]
93///   Returns a [`&str`] from a [`&[u8]`](slice). Panics if it's not valid utf8.
94/// - ≡ [`hex`][::const_str::hex]
95///   Converts a [`&str`] with hexadecimals (`0-9` | `A-F` | `a-f`) into a [`[u8; _]`](array).
96/// - ƒ &nbsp;[`ip_addr`][::const_str::ip_addr]
97///   Converts a [`&str`] to an IP address.
98/// - ≡ [`join`][::const_str::join]
99///   Concatenates multiple [`&str`] into a [&str] separated by the given separator.
100/// - ƒ &nbsp;[`parse`][::const_str::parse]
101///   Parses a [`&str`] into a value ([`&str`] | [`char`] | [`bool`] | `u*` | `i*`).
102/// - ≡ [`raw_cstr`][::const_str::raw_cstr]
103///   Converts a [`&str`] into a [`*const c_char`](core::ffi::c_char).
104/// - ≡ [`repeat`][::const_str::repeat]
105///   Creates a [`&str`] by repeating a [`&str`] n times.
106/// - ≡ [`replace`][::const_str::replace]
107///   Replaces all matches of a pattern ([`&str`] | [`char`]) with another [`&str`].
108/// - ≡ [`sorted`][::const_str::sorted]
109///   Sorts multiple ([`&[&str]`](slice) | [`[&str; N]`](array) |
110///   [`&[&str; N]`](array)) into a [`[&str; _]`](array).
111/// - ≡ [`split`][::const_str::split]
112///   Splits a [`&str`] by a separator pattern ([`&str`] | [`char`])
113///   returning [`[&str; _]`](array).
114/// - ƒ &nbsp;[`starts_with`][::const_str::starts_with]
115///   Returns [`true`] if the given pattern ([`&str`] | [`char`]) matches a prefix of [`&str`].
116/// - ƒ &nbsp;[`strip_prefix`][::const_str::strip_prefix]
117///   Returns a [`&str`] with the prefix removed.
118/// - ƒ &nbsp;[`strip_suffix`][::const_str::strip_suffix]
119///   Returns a [`&str`] with the suffix removed.
120/// - ≡ [`to_byte_array`][::const_str::to_byte_array]
121///   Converts a [`&str`] or [`&[u8]`](slice) into a [`[u8; _]`](array).
122/// - ≡ [`to_char_array`][::const_str::to_char_array]
123///   Converts a [`&str`] into a [`[char; _]`](array).
124/// - ≡ [`to_str`][::const_str::to_str]
125///   Returns a [`&str`] from a value ([`&str`] | [`char`] | [`bool`] | `u*` | `i*`).
126/// - ≡ [`unwrap`][::const_str::unwrap] Unwraps a container, returns the content
127///   (see also the [`unwrap!`][crate::unwrap] macro).
128///
129/// Ascii related:
130/// - ≡ [`convert_ascii_case`][::const_str::convert_ascii_case]
131///   Converts a [`&str`] to a specified case. Non-ASCII characters are not affected.
132/// - ƒ &nbsp;[`eq_ignore_ascii_case`][::const_str::eq_ignore_ascii_case]
133///   Returns [`true`] if two [`&str`] are an ASCII *case-insensitive* match.
134/// - ƒ &nbsp;[`is_ascii`][::const_str::is_ascii]
135///   Returns [`true`] if all codes in this
136///   ([`&str`] | [`&[u8]`](slice) | [`&[u8; N]`](array)) are ASCII.
137/// - ≡ [`squish`][::const_str::squish]
138///   Splits a [`&str`] by ASCII whitespaces, and joins the parts with a single space.
139#[macro_export]
140#[doc(hidden)]
141#[cfg(feature = "dep_const_str")]
142macro_rules! _str { // 29 arms
143    // (chain $($t:tt)*) => {$crate::_dep::const_str::chain!{$($t)*} }; // FIX
144    (compare $($t:tt)*) => {$crate::_dep::const_str::compare!{$($t)*} };
145    (concat $($t:tt)*) => {$crate::_dep::const_str::concat!{$($t)*} };
146    (concat_bytes $($t:tt)*) => {$crate::_dep::const_str::concat_bytes!{$($t)*} };
147    (contains $($t:tt)*) => { $crate::_dep::const_str::contains!{$($t)*} };
148    (cstr $($t:tt)*) => {$crate::_dep::const_str::cstr!{$($t)*} };
149    (encode $($t:tt)*) => {$crate::_dep::const_str::encode!{$($t)*} };
150    (encode_z $($t:tt)*) => {$crate::_dep::const_str::encode_z!{$($t)*} };
151    (ends_with $($t:tt)*) => {$crate::_dep::const_str::ends_with!{$($t)*} };
152    (equal $($t:tt)*) => {$crate::_dep::const_str::equal!{$($t)*} };
153    (from_utf8 $($t:tt)*) => {$crate::_dep::const_str::from_utf8!{$($t)*} };
154    (hex $($t:tt)*) => {$crate::_dep::const_str::hex!{$($t)*} };
155    (ip_addr $($t:tt)*) => {$crate::_dep::const_str::ip_addr!{$($t)*} };
156    (join $($t:tt)*) => {$crate::_dep::const_str::join!{$($t)*} };
157    (parse $($t:tt)*) => {$crate::_dep::const_str::parse!{$($t)*} };
158    (raw_cstr $($t:tt)*) => {$crate::_dep::const_str::raw_cstr!{$($t)*} };
159    (repeat $($t:tt)*) => {$crate::_dep::const_str::repeat!{$($t)*} };
160    (replace $($t:tt)*) => {$crate::_dep::const_str::replace!{$($t)*} };
161    (sorted $($t:tt)*) => {$crate::_dep::const_str::sorted!{$($t)*} };
162    (split $($t:tt)*) => {$crate::_dep::const_str::split!{$($t)*} };
163    (starts_with $($t:tt)*) => {$crate::_dep::const_str::starts_with!{$($t)*} };
164    (strip_prefix $($t:tt)*) => {$crate::_dep::const_str::strip_prefix!{$($t)*} };
165    (strip_suffix $($t:tt)*) => {$crate::_dep::const_str::strip_suffix!{$($t)*} };
166    (to_byte_array $($t:tt)*) => {$crate::_dep::const_str::to_byte_array!{$($t)*} };
167    (to_char_array $($t:tt)*) => {$crate::_dep::const_str::to_char_array!{$($t)*} };
168    (to_str $($t:tt)*) => {$crate::_dep::const_str::to_str!{$($t)*} };
169    (
170     is_ascii $($t:tt)*) => {$crate::_dep::const_str::is_ascii!{$($t)*} };
171    (convert_ascii_case $($t:tt)*) => {$crate::_dep::const_str::convert_ascii_case!{$($t)*} };
172    (eq_ignore_ascii_case $($t:tt)*) => {$crate::_dep::const_str::eq_ignore_ascii_case!{$($t)*} };
173    (squish $($t:tt)*) => {$crate::_dep::const_str::squish!{$($t)*} };
174    (unwrap $($t:tt)*) => {$crate::_dep::const_str::unwrap!{$($t)*} };
175}
176#[doc(inline)]
177#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "dep_const_str")))]
178#[cfg(feature = "dep_const_str")]
179pub use _str as str;
180
181#[cfg(test)]
182#[cfg(feature = "dep_const_str")]
183mod tests_str {
184    #![allow(unused)]
185
186    use crate::{const_assert, str, unwrap, CStr, Slice};
187
188    const ONE: &str = "1";
189    const TWO: &str = "2";
190    const TEN: &str = "10";
191    const LANGS: &str = "hello你好";
192
193    // #[test]
194    // const fn chain() {
195    //     const PARTS: &[&str] = &str!{ chain
196    //        stringify!(core::cmp::Ordering::Less),
197    //        str!(replace _, { concat!(TOP, "::") }, ""), // FIXME: no rules expected _
198    //        str!(split _, "::"),
199    //     };
200    // }
201    #[test]
202    const fn compare() {
203        const_assert!(str!(compare <, ONE, TEN));
204        const_assert!(str!(compare >=, TWO, ONE));
205        const_assert!(!str!(compare <, TWO, ONE));
206    }
207    #[test]
208    fn f_compare() {
209        let one = "1";
210        assert!(str!(compare <, one, TEN));
211    }
212    #[test]
213    const fn concat() {
214        const MESSAGE: &str = str!(concat TWO, " > ", ONE);
215        const_assert!(str!(compare ==, MESSAGE, "2 > 1"));
216    }
217    #[test]
218    const fn concat_bytes() {
219        const S1: &[u8; 7] = str!(concat_bytes b'A', b"BC", [68, b'E', 70], "G");
220        const S2: &[u8; 12] = str!(concat_bytes S1, "/123", 0u8);
221        const_assert!(str!(compare ==, S1, b"ABCDEFG"));
222        const_assert!(str!(compare ==, S2, b"ABCDEFG/123\x00"));
223    }
224    #[test]
225    const fn contains() {
226        const_assert!(str!(contains TEN, "1"));
227        const_assert!(!str!(contains TEN, "2"));
228    }
229    #[test]
230    fn f_contains() {
231        let ten = "10";
232        assert!(str!(contains ten, "1"));
233    }
234    #[test]
235    const fn cstr() {
236        const CSTR: &CStr = str!(cstr "%d\n");
237        const BYTES: &[u8; 4] = unwrap!(some CSTR.to_bytes_with_nul().first_chunk::<4>());
238        const_assert!(str!(compare ==, BYTES, b"%d\n\0"));
239    }
240    #[test]
241    const fn encode() {
242        const LANGS_UTF8: &[u8] = str!(encode utf8, LANGS);
243        const LANGS_UTF16: &[u16] = str!(encode utf16, LANGS);
244        const_assert!(eq_buf LANGS_UTF8, &[104, 101, 108, 108, 111, 228, 189, 160, 229, 165, 189]);
245        const_assert!(Slice::<u16>::eq(LANGS_UTF16, &[104, 101, 108, 108, 111, 20320, 22909]));
246    }
247    #[test]
248    const fn encode_z() {
249        const LANGS_UTF8: &[u8] = str!(encode_z utf8, LANGS);
250        const LANGS_UTF16: &[u16] = str!(encode_z utf16, LANGS);
251        const_assert!(eq_buf LANGS_UTF8,
252            &[104, 101, 108, 108, 111, 228, 189, 160, 229, 165, 189, 0]
253        );
254        const_assert!(Slice::<u16>::eq(LANGS_UTF16, &[104, 101, 108, 108, 111, 20320, 22909, 0]));
255    }
256    #[test]
257    const fn ends_with() {
258        const_assert!(str!(ends_with TEN, "0"));
259        const_assert!(!str!(ends_with TEN, "1"));
260        const_assert!(str!(ends_with LANGS, "好"));
261    }
262    #[test]
263    fn f_ends_with() {
264        let ten = "10";
265        assert!(str!(ends_with ten, "0"));
266    }
267    #[test]
268    const fn equal() {
269        const_assert!(str!(equal TEN, "10"));
270        const_assert!(!str!(ends_with TEN, "1"));
271    }
272    #[test]
273    fn f_equal() {
274        let ten = "10";
275        assert!(str!(equal ten, "10"));
276    }
277    #[test]
278    const fn from_utf8() {
279        const BYTE_PATH: &[u8] = b"/tmp/file";
280        const PATH: &str = str!(from_utf8 BYTE_PATH);
281        const_assert!(eq_str PATH, "/tmp/file");
282    }
283    #[test]
284    const fn ip_addr() {
285        use core::net::{IpAddr, Ipv4Addr, Ipv6Addr};
286        const LOCALHOST_V4: Ipv4Addr = str!(ip_addr v4, "127.0.0.1");
287        const LOCALHOST_V6: Ipv6Addr = str!(ip_addr v6, "::1");
288        const LOCALHOSTS: [IpAddr; 2] = [str!(ip_addr "127.0.0.1"), str!(ip_addr "::1")];
289        const_assert!(
290            eq_buf & str!(ip_addr v4, "127.0.0.1").octets(),
291            &Ipv4Addr::new(127, 0, 0, 1).octets()
292        );
293        const_assert!(eq_buf & str!(ip_addr v6, "::1").octets(), &Ipv6Addr::LOCALHOST.octets());
294        const_assert!(LOCALHOSTS[0].is_ipv4() && LOCALHOSTS[1].is_ipv6());
295    }
296    #[test]
297    fn f_ip_address() {
298        let localhost_v4 = core::net::Ipv4Addr::LOCALHOST;
299        assert_eq!(str!(ip_addr v4, "127.0.0.1"), localhost_v4);
300    }
301    #[test]
302    const fn hex() {
303        const HEX: [u8; 4] = str!(hex "01020304");
304        const_assert!(eq_buf & str!(hex "01020304"), &[1, 2, 3, 4]);
305        const_assert!(eq_buf & str!(hex "a1 b2 C3 D4"), &[0xA1, 0xB2, 0xc3, 0xd4]);
306        const_assert!(eq_buf & str!(hex ["0a0B", "0C0d"]), &[10, 11, 12, 13]);
307    }
308    #[test]
309    const fn join() {
310        const_assert!(eq_str str!(join &[ONE, TWO, TEN], ","), "1,2,10");
311        const_assert!(eq_str str!(join &[ONE, TWO, TEN], ""), "1210");
312    }
313    #[test]
314    const fn parse() {
315        const_assert!(eq str!(parse "true", bool), true);
316        const_assert!(eq str!(parse "false", bool), false);
317        const_assert!(eq str!(parse "16723", usize), 16723);
318        const_assert!(eq str!(parse "-100", i8), -100);
319        const_assert!(eq str!(parse "€", char), '€');
320    }
321    #[test]
322    fn f_parse() {
323        let t = "true";
324        assert_eq!(str!(parse t, bool), true);
325    }
326    #[test]
327    const fn raw_cstr() {
328        const CCHAR: *const crate::c_char = str!(raw_cstr "%d\n");
329    }
330    #[test]
331    const fn repeat() {
332        const_assert!(eq_str str!(repeat TEN, 3), "101010");
333    }
334    #[test]
335    const fn replace() {
336        const_assert!(eq_str str!(replace "original", "gin", "tonic"), "oritonical");
337        const_assert!(eq_str str!(replace "original", 'g', "G"), "oriGinal");
338    }
339    #[test]
340    const fn sorted() {
341        const SORTED: &[&str] = &str!(sorted ["one", "two", "three"]);
342        const_assert!(Slice::<&[&str]>::eq(SORTED, &["one", "three", "two"]));
343        const_assert!(Slice::<&[&str]>::eq(&str!(sorted ["1", "2", "10"]), &["1", "10", "2"]));
344    }
345    #[test]
346    const fn split() {
347        const TEXT: &str = "apple, kiwi, banana";
348        const_assert!(Slice::<&[&str]>::eq(&str!(split TEXT, ", "), &["apple", "kiwi", "banana"]));
349    }
350    #[test]
351    const fn starts_with() {
352        const_assert!(str!(starts_with "banana", 'b'));
353        const_assert!(str!(starts_with "banana", "ban"));
354        const_assert!(!str!(starts_with "banana", "a"));
355    }
356    #[test]
357    fn f_starts_with() {
358        let banana = "banana";
359        assert!(str!(starts_with banana, 'b'));
360    }
361    #[test]
362    const fn strip_prefix() {
363        const_assert!(eq_str unwrap![some str!(strip_prefix "banana", "ban")], "ana");
364        const_assert!(str!(strip_prefix "banana", "a").is_none());
365    }
366    #[test]
367    fn f_strip_prefix() {
368        let banana = "banana";
369        assert_eq!(unwrap![some str!(strip_prefix banana, "ban")], "ana");
370    }
371    #[test]
372    const fn strip_suffix() {
373        const_assert!(eq_str unwrap![some str!(strip_suffix "banana", "ana")], "ban");
374        const_assert!(str!(strip_suffix "banana", "b").is_none());
375    }
376    #[test]
377    fn f_strip_suffix() {
378        let banana = "banana";
379        assert_eq!(unwrap![some str!(strip_suffix banana, "ana")], "ban");
380    }
381    #[test]
382    const fn to_byte_array() {
383        const ARRAY: [u8; 5] = str![to_byte_array "hello"];
384        const_assert!(eq_buf & ARRAY, &[b'h', b'e', b'l', b'l', b'o']);
385    }
386    #[test]
387    const fn to_char_array() {
388        const ARRAY: [char; 5] = str![to_char_array "hello"];
389        const_assert!(Slice::<char>::eq(&ARRAY, &['h', 'e', 'l', 'l', 'o']));
390    }
391    #[test]
392    const fn to_str() {
393        const_assert!(eq_str str!(to_str "string"), "string");
394        const_assert!(eq_str str!(to_str '€'), "€");
395        const_assert!(eq_str str!(to_str false), "false");
396        const_assert!(eq_str str!(to_str 50u32 - 3), "47");
397        const_assert!(eq_str str!(to_str 5i8 - 9), "-4");
398    }
399    #[test]
400    const fn convert_ascii_case() {
401        const_assert!(eq_str str!(convert_ascii_case lower, "Lower Case"), "lower case");
402        const_assert!(eq_str str!(convert_ascii_case upper, "Upper Case"), "UPPER CASE");
403        const_assert!(eq_str str!(convert_ascii_case lower_camel, "lower camel"), "lowerCamel");
404        const_assert!(eq_str str!(convert_ascii_case upper_camel, "upper camel"), "UpperCamel");
405        const_assert!(eq_str str!(convert_ascii_case upper_camel, "upper camel"), "UpperCamel");
406        const_assert!(eq_str str!(convert_ascii_case snake, "snake case"), "snake_case");
407        const_assert!(eq_str str!(convert_ascii_case kebab, "kebab case"), "kebab-case");
408        const_assert!(eq_str str!(convert_ascii_case shouty_snake, "shouty snake"), "SHOUTY_SNAKE");
409        const_assert!(eq_str str!(convert_ascii_case shouty_kebab, "shouty kebab"), "SHOUTY-KEBAB");
410    }
411    #[test]
412    const fn eq_ignore_ascii_case() {
413        const_assert!(str!(eq_ignore_ascii_case "Ferris", "FERRIS"));
414        const_assert!(str!(eq_ignore_ascii_case "Ferrös", "FERRöS"));
415        const_assert!(!str!(eq_ignore_ascii_case "Ferrös", "FERRÖS"));
416    }
417    #[test]
418    fn f_eq_ignore_ascii_case() {
419        let ferris = "Ferris";
420        assert!(str!(eq_ignore_ascii_case ferris, "FERRIS"));
421    }
422    #[test]
423    const fn is_ascii() {
424        const_assert!(str!(is_ascii "hello\n"));
425        const_assert!(!str!(is_ascii LANGS));
426    }
427    #[test]
428    fn f_is_ascii() {
429        let ascii = "hello\n";
430        assert!(str!(is_ascii ascii));
431    }
432    #[test]
433    const fn squish() {
434        const_assert!(eq_str str!(squish "   SQUISH  \t THAT  \t CAT!    "), "SQUISH THAT CAT!");
435    }
436    #[test]
437    const fn unwrap() {
438        struct NonCopy;
439        let a: u8 = str!(unwrap Some(23));
440        // let b: NonCopy = str!(unwrap Some(NonCopy)); // FAIL: only works with Copy types
441        let a: NonCopy = unwrap!(some Some(NonCopy)); // but our unwrap macro can do :)
442    }
443}
devela/text/str/macros.rs

devela/text/str/
macros.rs
