]>
Commit | Line | Data |
---|---|---|
ea8adc8c | 1 | /// Creates a [`Vec`] containing the arguments. |
041b39d2 XL |
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 | /// | |
ea8adc8c | 6 | /// - Create a [`Vec`] containing a given list of elements: |
041b39d2 XL |
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 | /// | |
ea8adc8c | 15 | /// - Create a [`Vec`] from a given element and size: |
041b39d2 XL |
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 | |
ea8adc8c | 23 | /// which implement [`Clone`] and the number of elements doesn't have to be |
041b39d2 XL |
24 | /// a constant. |
25 | /// | |
ea8adc8c | 26 | /// This will use `clone` to duplicate an expression, so one should be careful |
041b39d2 XL |
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. | |
ea8adc8c XL |
31 | /// |
32 | /// [`Vec`]: ../std/vec/struct.Vec.html | |
33 | /// [`Clone`]: ../std/clone/trait.Clone.html | |
041b39d2 XL |
34 | #[cfg(not(test))] |
35 | #[macro_export] | |
36 | #[stable(feature = "rust1", since = "1.0.0")] | |
532ac7d7 | 37 | #[allow_internal_unstable(box_syntax)] |
041b39d2 XL |
38 | macro_rules! vec { |
39 | ($elem:expr; $n:expr) => ( | |
40 | $crate::vec::from_elem($elem, $n) | |
41 | ); | |
42 | ($($x:expr),*) => ( | |
43 | <[_]>::into_vec(box [$($x),*]) | |
44 | ); | |
45 | ($($x:expr,)*) => (vec![$($x),*]) | |
46 | } | |
47 | ||
48 | // HACK(japaric): with cfg(test) the inherent `[T]::into_vec` method, which is | |
49 | // required for this macro definition, is not available. Instead use the | |
50 | // `slice::into_vec` function which is only available with cfg(test) | |
51 | // NB see the slice::hack module in slice.rs for more information | |
52 | #[cfg(test)] | |
53 | macro_rules! vec { | |
54 | ($elem:expr; $n:expr) => ( | |
55 | $crate::vec::from_elem($elem, $n) | |
56 | ); | |
57 | ($($x:expr),*) => ( | |
58 | $crate::slice::into_vec(box [$($x),*]) | |
59 | ); | |
60 | ($($x:expr,)*) => (vec![$($x),*]) | |
61 | } | |
62 | ||
ea8adc8c XL |
63 | /// Creates a `String` using interpolation of runtime expressions. |
64 | /// | |
9fa01778 XL |
65 | /// The first argument `format!` receives is a format string. This must be a string |
66 | /// literal. The power of the formatting string is in the `{}`s contained. | |
ea8adc8c XL |
67 | /// |
68 | /// Additional parameters passed to `format!` replace the `{}`s within the | |
69 | /// formatting string in the order given unless named or positional parameters | |
9fa01778 | 70 | /// are used; see [`std::fmt`][fmt] for more information. |
ea8adc8c XL |
71 | /// |
72 | /// A common use for `format!` is concatenation and interpolation of strings. | |
73 | /// The same convention is used with [`print!`] and [`write!`] macros, | |
74 | /// depending on the intended destination of the string. | |
041b39d2 | 75 | /// |
9fa01778 | 76 | /// To convert a single value to a string, use the [`to_string`] method. This |
0731742a XL |
77 | /// will use the [`Display`] formatting trait. |
78 | /// | |
041b39d2 | 79 | /// [fmt]: ../std/fmt/index.html |
ea8adc8c XL |
80 | /// [`print!`]: ../std/macro.print.html |
81 | /// [`write!`]: ../std/macro.write.html | |
0731742a XL |
82 | /// [`to_string`]: ../std/string/trait.ToString.html |
83 | /// [`Display`]: ../std/fmt/trait.Display.html | |
041b39d2 XL |
84 | /// |
85 | /// # Panics | |
86 | /// | |
87 | /// `format!` panics if a formatting trait implementation returns an error. | |
88 | /// This indicates an incorrect implementation | |
89 | /// since `fmt::Write for String` never returns an error itself. | |
90 | /// | |
91 | /// # Examples | |
92 | /// | |
93 | /// ``` | |
94 | /// format!("test"); | |
95 | /// format!("hello {}", "world!"); | |
96 | /// format!("x = {}, y = {y}", 10, y = 30); | |
97 | /// ``` | |
98 | #[macro_export] | |
99 | #[stable(feature = "rust1", since = "1.0.0")] | |
100 | macro_rules! format { | |
101 | ($($arg:tt)*) => ($crate::fmt::format(format_args!($($arg)*))) | |
102 | } |