1 /// Creates a [`Vec`] containing the arguments. 2 /// 3 /// `vec!` allows `Vec`s to be defined with the same syntax as array expressions. 4 /// There are two forms of this macro: 5 /// 6 /// - Create a [`Vec`] containing a given list of elements: 7 /// 8 /// ``` 9 /// let v = vec![1, 2, 3]; 10 /// assert_eq!(v[0], 1); 11 /// assert_eq!(v[1], 2); 12 /// assert_eq!(v[2], 3); 13 /// ``` 14 /// 15 /// - Create a [`Vec`] from a given element and size: 16 /// 17 /// ``` 18 /// let v = vec![1; 3]; 19 /// assert_eq!(v, [1, 1, 1]); 20 /// ``` 21 /// 22 /// Note that unlike array expressions this syntax supports all elements 23 /// which implement [`Clone`] and the number of elements doesn't have to be 24 /// a constant. 25 /// 26 /// This will use `clone` to duplicate an expression, so one should be careful 27 /// using this with types having a nonstandard `Clone` implementation. For 28 /// example, `vec![Rc::new(1); 5]` will create a vector of five references 29 /// to the same boxed integer value, not five references pointing to independently 30 /// boxed integers. 31 /// 32 /// Also, note that `vec![expr; 0]` is allowed, and produces an empty vector. 33 /// This will still evaluate `expr`, however, and immediately drop the resulting value, so 34 /// be mindful of side effects. 35 /// 36 /// [`Vec`]: crate::vec::Vec 37 #[cfg(all(not(no_global_oom_handling), not(test)))] 38 #[macro_export] 39 #[stable(feature = "rust1", since = "1.0.0")] 40 #[rustc_diagnostic_item = "vec_macro"] 41 #[allow_internal_unstable(rustc_attrs, liballoc_internals)] 42 macro_rules! vec { 43 () => ( 44 $crate::__rust_force_expr!($crate::vec::Vec::new()) 45 ); 46 ($elem:expr; $n:expr) => ( 47 $crate::__rust_force_expr!($crate::vec::from_elem($elem, $n)) 48 ); 49 ($($x:expr),+ $(,)?) => ( 50 $crate::__rust_force_expr!(<[_]>::into_vec( 51 // This rustc_box is not required, but it produces a dramatic improvement in compile 52 // time when constructing arrays with many elements. 53 #[rustc_box] 54 $crate::boxed::Box::new([$($x),+]) 55 )) 56 ); 57 } 58 59 // HACK(japaric): with cfg(test) the inherent `[T]::into_vec` method, which is 60 // required for this macro definition, is not available. Instead use the 61 // `slice::into_vec` function which is only available with cfg(test) 62 // NB see the slice::hack module in slice.rs for more information 63 #[cfg(all(not(no_global_oom_handling), test))] 64 #[allow(unused_macro_rules)] 65 macro_rules! vec { 66 () => ( 67 $crate::vec::Vec::new() 68 ); 69 ($elem:expr; $n:expr) => ( 70 $crate::vec::from_elem($elem, $n) 71 ); 72 ($($x:expr),*) => ( 73 $crate::slice::into_vec($crate::boxed::Box::new([$($x),*])) 74 ); 75 ($($x:expr,)*) => (vec![$($x),*]) 76 } 77 78 /// Creates a `String` using interpolation of runtime expressions. 79 /// 80 /// The first argument `format!` receives is a format string. This must be a string 81 /// literal. The power of the formatting string is in the `{}`s contained. 82 /// 83 /// Additional parameters passed to `format!` replace the `{}`s within the 84 /// formatting string in the order given unless named or positional parameters 85 /// are used; see [`std::fmt`] for more information. 86 /// 87 /// A common use for `format!` is concatenation and interpolation of strings. 88 /// The same convention is used with [`print!`] and [`write!`] macros, 89 /// depending on the intended destination of the string. 90 /// 91 /// To convert a single value to a string, use the [`to_string`] method. This 92 /// will use the [`Display`] formatting trait. 93 /// 94 /// [`std::fmt`]: ../std/fmt/index.html 95 /// [`print!`]: ../std/macro.print.html 96 /// [`write!`]: core::write 97 /// [`to_string`]: crate::string::ToString 98 /// [`Display`]: core::fmt::Display 99 /// 100 /// # Panics 101 /// 102 /// `format!` panics if a formatting trait implementation returns an error. 103 /// This indicates an incorrect implementation 104 /// since `fmt::Write for String` never returns an error itself. 105 /// 106 /// # Examples 107 /// 108 /// ``` 109 /// format!("test"); 110 /// format!("hello {}", "world!"); 111 /// format!("x = {}, y = {y}", 10, y = 30); 112 /// let (x, y) = (1, 2); 113 /// format!("{x} + {y} = 3"); 114 /// ``` 115 #[macro_export] 116 #[stable(feature = "rust1", since = "1.0.0")] 117 #[cfg_attr(not(test), rustc_diagnostic_item = "format_macro")] 118 macro_rules! format { 119 ($($arg:tt)*) => {{ 120 let res = $crate::fmt::format($crate::__export::format_args!($($arg)*)); 121 res 122 }} 123 } 124 125 /// Force AST node to an expression to improve diagnostics in pattern position. 126 #[doc(hidden)] 127 #[macro_export] 128 #[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] 129 macro_rules! __rust_force_expr { 130 ($e:expr) => { 131 $e 132 }; 133 } 134