]>
Commit | Line | Data |
---|---|---|
1a4d82fc | 1 | // Copyright 2014 The Rust Project Developers. See the COPYRIGHT |
970d7e83 LB |
2 | // file at the top-level directory of this distribution and at |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
10 | ||
1a4d82fc JJ |
11 | //! Standard library macros |
12 | //! | |
13 | //! This modules contains a set of macros which are exported from the standard | |
14 | //! library. Each macro is available for use when linking against the standard | |
15 | //! library. | |
970d7e83 | 16 | |
bd371182 | 17 | /// The entry point for panic of Rust threads. |
9346a6ac | 18 | /// |
bd371182 | 19 | /// This macro is used to inject panic into a Rust thread, causing the thread to |
a7813a04 XL |
20 | /// panic entirely. Each thread's panic can be reaped as the `Box<Any>` type, |
21 | /// and the single-argument form of the `panic!` macro will be the value which | |
22 | /// is transmitted. | |
9346a6ac AL |
23 | /// |
24 | /// The multi-argument form of this macro panics with a string and has the | |
25 | /// `format!` syntax for building a string. | |
26 | /// | |
27 | /// # Examples | |
28 | /// | |
29 | /// ```should_panic | |
30 | /// # #![allow(unreachable_code)] | |
31 | /// panic!(); | |
32 | /// panic!("this is a terrible mistake!"); | |
33 | /// panic!(4); // panic with the value of 4 to be collected elsewhere | |
34 | /// panic!("this is a {} {message}", "fancy", message = "message"); | |
35 | /// ``` | |
36 | #[macro_export] | |
37 | #[stable(feature = "rust1", since = "1.0.0")] | |
38 | #[allow_internal_unstable] | |
9346a6ac AL |
39 | macro_rules! panic { |
40 | () => ({ | |
41 | panic!("explicit panic") | |
42 | }); | |
43 | ($msg:expr) => ({ | |
a7813a04 | 44 | $crate::rt::begin_panic($msg, { |
9346a6ac AL |
45 | // static requires less code at runtime, more constant data |
46 | static _FILE_LINE: (&'static str, u32) = (file!(), line!()); | |
47 | &_FILE_LINE | |
48 | }) | |
49 | }); | |
50 | ($fmt:expr, $($arg:tt)+) => ({ | |
a7813a04 | 51 | $crate::rt::begin_panic_fmt(&format_args!($fmt, $($arg)+), { |
9346a6ac AL |
52 | // The leading _'s are to avoid dead code warnings if this is |
53 | // used inside a dead function. Just `#[allow(dead_code)]` is | |
54 | // insufficient, since the user may have | |
55 | // `#[forbid(dead_code)]` and which cannot be overridden. | |
56 | static _FILE_LINE: (&'static str, u32) = (file!(), line!()); | |
1a4d82fc JJ |
57 | &_FILE_LINE |
58 | }) | |
59 | }); | |
60 | } | |
61 | ||
c34b1796 AL |
62 | /// Macro for printing to the standard output. |
63 | /// | |
1a4d82fc JJ |
64 | /// Equivalent to the `println!` macro except that a newline is not printed at |
65 | /// the end of the message. | |
c34b1796 AL |
66 | /// |
67 | /// Note that stdout is frequently line-buffered by default so it may be | |
68 | /// necessary to use `io::stdout().flush()` to ensure the output is emitted | |
69 | /// immediately. | |
e9174d1e | 70 | /// |
b039eaaf SL |
71 | /// # Panics |
72 | /// | |
73 | /// Panics if writing to `io::stdout()` fails. | |
74 | /// | |
e9174d1e SL |
75 | /// # Examples |
76 | /// | |
77 | /// ``` | |
78 | /// use std::io::{self, Write}; | |
79 | /// | |
80 | /// print!("this "); | |
81 | /// print!("will "); | |
82 | /// print!("be "); | |
83 | /// print!("on "); | |
84 | /// print!("the "); | |
85 | /// print!("same "); | |
86 | /// print!("line "); | |
87 | /// | |
88 | /// io::stdout().flush().unwrap(); | |
89 | /// | |
90 | /// print!("this string has a newline, why not choose println! instead?\n"); | |
91 | /// | |
92 | /// io::stdout().flush().unwrap(); | |
93 | /// ``` | |
1a4d82fc | 94 | #[macro_export] |
85aaf69f | 95 | #[stable(feature = "rust1", since = "1.0.0")] |
c34b1796 | 96 | #[allow_internal_unstable] |
1a4d82fc | 97 | macro_rules! print { |
c34b1796 | 98 | ($($arg:tt)*) => ($crate::io::_print(format_args!($($arg)*))); |
1a4d82fc | 99 | } |
970d7e83 | 100 | |
5bcae85e SL |
101 | /// Macro for printing to the standard output, with a newline. On all |
102 | /// platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone | |
103 | /// (no additional CARRIAGE RETURN (`\r`/`U+000D`). | |
1a4d82fc | 104 | /// |
c34b1796 AL |
105 | /// Use the `format!` syntax to write data to the standard output. |
106 | /// See `std::fmt` for more information. | |
1a4d82fc | 107 | /// |
b039eaaf SL |
108 | /// # Panics |
109 | /// | |
110 | /// Panics if writing to `io::stdout()` fails. | |
111 | /// | |
c34b1796 | 112 | /// # Examples |
1a4d82fc JJ |
113 | /// |
114 | /// ``` | |
115 | /// println!("hello there!"); | |
116 | /// println!("format {} arguments", "some"); | |
117 | /// ``` | |
118 | #[macro_export] | |
85aaf69f | 119 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 120 | macro_rules! println { |
c34b1796 AL |
121 | ($fmt:expr) => (print!(concat!($fmt, "\n"))); |
122 | ($fmt:expr, $($arg:tt)*) => (print!(concat!($fmt, "\n"), $($arg)*)); | |
1a4d82fc JJ |
123 | } |
124 | ||
1a4d82fc JJ |
125 | /// A macro to select an event from a number of receivers. |
126 | /// | |
127 | /// This macro is used to wait for the first event to occur on a number of | |
128 | /// receivers. It places no restrictions on the types of receivers given to | |
129 | /// this macro, this can be viewed as a heterogeneous select. | |
130 | /// | |
85aaf69f | 131 | /// # Examples |
1a4d82fc JJ |
132 | /// |
133 | /// ``` | |
c1a9b12d SL |
134 | /// #![feature(mpsc_select)] |
135 | /// | |
85aaf69f SL |
136 | /// use std::thread; |
137 | /// use std::sync::mpsc; | |
1a4d82fc | 138 | /// |
85aaf69f | 139 | /// // two placeholder functions for now |
bd371182 | 140 | /// fn long_running_thread() {} |
85aaf69f | 141 | /// fn calculate_the_answer() -> u32 { 42 } |
1a4d82fc | 142 | /// |
85aaf69f SL |
143 | /// let (tx1, rx1) = mpsc::channel(); |
144 | /// let (tx2, rx2) = mpsc::channel(); | |
145 | /// | |
bd371182 | 146 | /// thread::spawn(move|| { long_running_thread(); tx1.send(()).unwrap(); }); |
85aaf69f | 147 | /// thread::spawn(move|| { tx2.send(calculate_the_answer()).unwrap(); }); |
1a4d82fc | 148 | /// |
d9579d0f | 149 | /// select! { |
bd371182 | 150 | /// _ = rx1.recv() => println!("the long running thread finished first"), |
1a4d82fc JJ |
151 | /// answer = rx2.recv() => { |
152 | /// println!("the answer was: {}", answer.unwrap()); | |
153 | /// } | |
d9579d0f AL |
154 | /// } |
155 | /// # drop(rx1.recv()); | |
156 | /// # drop(rx2.recv()); | |
1a4d82fc JJ |
157 | /// ``` |
158 | /// | |
159 | /// For more information about select, see the `std::sync::mpsc::Select` structure. | |
160 | #[macro_export] | |
e9174d1e | 161 | #[unstable(feature = "mpsc_select", issue = "27800")] |
1a4d82fc JJ |
162 | macro_rules! select { |
163 | ( | |
164 | $($name:pat = $rx:ident.$meth:ident() => $code:expr),+ | |
165 | ) => ({ | |
166 | use $crate::sync::mpsc::Select; | |
167 | let sel = Select::new(); | |
168 | $( let mut $rx = sel.handle(&$rx); )+ | |
169 | unsafe { | |
170 | $( $rx.add(); )+ | |
970d7e83 | 171 | } |
1a4d82fc JJ |
172 | let ret = sel.wait(); |
173 | $( if ret == $rx.id() { let $name = $rx.$meth(); $code } else )+ | |
174 | { unreachable!() } | |
175 | }) | |
176 | } | |
177 | ||
e9174d1e SL |
178 | #[cfg(test)] |
179 | macro_rules! assert_approx_eq { | |
180 | ($a:expr, $b:expr) => ({ | |
181 | let (a, b) = (&$a, &$b); | |
182 | assert!((*a - *b).abs() < 1.0e-6, | |
183 | "{} is not approximately equal to {}", *a, *b); | |
184 | }) | |
185 | } | |
186 | ||
1a4d82fc JJ |
187 | /// Built-in macros to the compiler itself. |
188 | /// | |
189 | /// These macros do not have any corresponding definition with a `macro_rules!` | |
190 | /// macro, but are documented here. Their implementations can be found hardcoded | |
191 | /// into libsyntax itself. | |
192 | #[cfg(dox)] | |
193 | pub mod builtin { | |
194 | /// The core macro for formatted string creation & output. | |
195 | /// | |
196 | /// This macro produces a value of type `fmt::Arguments`. This value can be | |
197 | /// passed to the functions in `std::fmt` for performing useful functions. | |
198 | /// All other formatting macros (`format!`, `write!`, `println!`, etc) are | |
199 | /// proxied through this one. | |
200 | /// | |
201 | /// For more information, see the documentation in `std::fmt`. | |
202 | /// | |
c34b1796 | 203 | /// # Examples |
1a4d82fc | 204 | /// |
c34b1796 | 205 | /// ``` |
1a4d82fc JJ |
206 | /// use std::fmt; |
207 | /// | |
208 | /// let s = fmt::format(format_args!("hello {}", "world")); | |
209 | /// assert_eq!(s, format!("hello {}", "world")); | |
210 | /// | |
211 | /// ``` | |
92a42be0 | 212 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
213 | #[macro_export] |
214 | macro_rules! format_args { ($fmt:expr, $($args:tt)*) => ({ | |
215 | /* compiler built-in */ | |
216 | }) } | |
217 | ||
218 | /// Inspect an environment variable at compile time. | |
219 | /// | |
220 | /// This macro will expand to the value of the named environment variable at | |
221 | /// compile time, yielding an expression of type `&'static str`. | |
222 | /// | |
223 | /// If the environment variable is not defined, then a compilation error | |
224 | /// will be emitted. To not emit a compile error, use the `option_env!` | |
225 | /// macro instead. | |
226 | /// | |
c34b1796 | 227 | /// # Examples |
1a4d82fc | 228 | /// |
c34b1796 | 229 | /// ``` |
1a4d82fc JJ |
230 | /// let path: &'static str = env!("PATH"); |
231 | /// println!("the $PATH variable at the time of compiling was: {}", path); | |
232 | /// ``` | |
92a42be0 | 233 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
234 | #[macro_export] |
235 | macro_rules! env { ($name:expr) => ({ /* compiler built-in */ }) } | |
236 | ||
237 | /// Optionally inspect an environment variable at compile time. | |
238 | /// | |
239 | /// If the named environment variable is present at compile time, this will | |
240 | /// expand into an expression of type `Option<&'static str>` whose value is | |
241 | /// `Some` of the value of the environment variable. If the environment | |
242 | /// variable is not present, then this will expand to `None`. | |
243 | /// | |
244 | /// A compile time error is never emitted when using this macro regardless | |
245 | /// of whether the environment variable is present or not. | |
246 | /// | |
c34b1796 | 247 | /// # Examples |
1a4d82fc | 248 | /// |
c34b1796 | 249 | /// ``` |
1a4d82fc JJ |
250 | /// let key: Option<&'static str> = option_env!("SECRET_KEY"); |
251 | /// println!("the secret key might be: {:?}", key); | |
252 | /// ``` | |
92a42be0 | 253 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
254 | #[macro_export] |
255 | macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) } | |
256 | ||
257 | /// Concatenate identifiers into one identifier. | |
258 | /// | |
259 | /// This macro takes any number of comma-separated identifiers, and | |
260 | /// concatenates them all into one, yielding an expression which is a new | |
261 | /// identifier. Note that hygiene makes it such that this macro cannot | |
7453a54e SL |
262 | /// capture local variables. Also, as a general rule, macros are only |
263 | /// allowed in item, statement or expression position. That means while | |
264 | /// you may use this macro for referring to existing variables, functions or | |
265 | /// modules etc, you cannot define a new one with it. | |
1a4d82fc | 266 | /// |
85aaf69f | 267 | /// # Examples |
1a4d82fc JJ |
268 | /// |
269 | /// ``` | |
270 | /// #![feature(concat_idents)] | |
271 | /// | |
272 | /// # fn main() { | |
85aaf69f | 273 | /// fn foobar() -> u32 { 23 } |
1a4d82fc JJ |
274 | /// |
275 | /// let f = concat_idents!(foo, bar); | |
276 | /// println!("{}", f()); | |
7453a54e SL |
277 | /// |
278 | /// // fn concat_idents!(new, fun, name) { } // not usable in this way! | |
1a4d82fc JJ |
279 | /// # } |
280 | /// ``` | |
3157f602 | 281 | #[unstable(feature = "concat_idents", issue = "29599")] |
1a4d82fc JJ |
282 | #[macro_export] |
283 | macro_rules! concat_idents { | |
284 | ($($e:ident),*) => ({ /* compiler built-in */ }) | |
285 | } | |
286 | ||
287 | /// Concatenates literals into a static string slice. | |
288 | /// | |
289 | /// This macro takes any number of comma-separated literals, yielding an | |
290 | /// expression of type `&'static str` which represents all of the literals | |
291 | /// concatenated left-to-right. | |
292 | /// | |
293 | /// Integer and floating point literals are stringified in order to be | |
294 | /// concatenated. | |
295 | /// | |
c34b1796 | 296 | /// # Examples |
1a4d82fc JJ |
297 | /// |
298 | /// ``` | |
85aaf69f | 299 | /// let s = concat!("test", 10, 'b', true); |
1a4d82fc JJ |
300 | /// assert_eq!(s, "test10btrue"); |
301 | /// ``` | |
92a42be0 | 302 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
303 | #[macro_export] |
304 | macro_rules! concat { ($($e:expr),*) => ({ /* compiler built-in */ }) } | |
305 | ||
306 | /// A macro which expands to the line number on which it was invoked. | |
307 | /// | |
62682a34 | 308 | /// The expanded expression has type `u32`, and the returned line is not |
1a4d82fc JJ |
309 | /// the invocation of the `line!()` macro itself, but rather the first macro |
310 | /// invocation leading up to the invocation of the `line!()` macro. | |
311 | /// | |
c34b1796 | 312 | /// # Examples |
1a4d82fc JJ |
313 | /// |
314 | /// ``` | |
315 | /// let current_line = line!(); | |
316 | /// println!("defined on line: {}", current_line); | |
317 | /// ``` | |
92a42be0 | 318 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
319 | #[macro_export] |
320 | macro_rules! line { () => ({ /* compiler built-in */ }) } | |
321 | ||
322 | /// A macro which expands to the column number on which it was invoked. | |
323 | /// | |
62682a34 | 324 | /// The expanded expression has type `u32`, and the returned column is not |
1a4d82fc JJ |
325 | /// the invocation of the `column!()` macro itself, but rather the first macro |
326 | /// invocation leading up to the invocation of the `column!()` macro. | |
327 | /// | |
c34b1796 | 328 | /// # Examples |
1a4d82fc JJ |
329 | /// |
330 | /// ``` | |
331 | /// let current_col = column!(); | |
332 | /// println!("defined on column: {}", current_col); | |
333 | /// ``` | |
92a42be0 | 334 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
335 | #[macro_export] |
336 | macro_rules! column { () => ({ /* compiler built-in */ }) } | |
337 | ||
338 | /// A macro which expands to the file name from which it was invoked. | |
339 | /// | |
340 | /// The expanded expression has type `&'static str`, and the returned file | |
341 | /// is not the invocation of the `file!()` macro itself, but rather the | |
342 | /// first macro invocation leading up to the invocation of the `file!()` | |
343 | /// macro. | |
344 | /// | |
c34b1796 | 345 | /// # Examples |
1a4d82fc JJ |
346 | /// |
347 | /// ``` | |
348 | /// let this_file = file!(); | |
349 | /// println!("defined in file: {}", this_file); | |
350 | /// ``` | |
92a42be0 | 351 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
352 | #[macro_export] |
353 | macro_rules! file { () => ({ /* compiler built-in */ }) } | |
354 | ||
355 | /// A macro which stringifies its argument. | |
356 | /// | |
357 | /// This macro will yield an expression of type `&'static str` which is the | |
358 | /// stringification of all the tokens passed to the macro. No restrictions | |
359 | /// are placed on the syntax of the macro invocation itself. | |
360 | /// | |
7453a54e SL |
361 | /// Note that the expanded results of the input tokens may change in the |
362 | /// future. You should be careful if you rely on the output. | |
363 | /// | |
c34b1796 | 364 | /// # Examples |
1a4d82fc JJ |
365 | /// |
366 | /// ``` | |
367 | /// let one_plus_one = stringify!(1 + 1); | |
368 | /// assert_eq!(one_plus_one, "1 + 1"); | |
369 | /// ``` | |
92a42be0 | 370 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
371 | #[macro_export] |
372 | macro_rules! stringify { ($t:tt) => ({ /* compiler built-in */ }) } | |
373 | ||
374 | /// Includes a utf8-encoded file as a string. | |
375 | /// | |
376 | /// This macro will yield an expression of type `&'static str` which is the | |
377 | /// contents of the filename specified. The file is located relative to the | |
378 | /// current file (similarly to how modules are found), | |
379 | /// | |
c34b1796 | 380 | /// # Examples |
1a4d82fc JJ |
381 | /// |
382 | /// ```rust,ignore | |
383 | /// let secret_key = include_str!("secret-key.ascii"); | |
384 | /// ``` | |
92a42be0 | 385 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
386 | #[macro_export] |
387 | macro_rules! include_str { ($file:expr) => ({ /* compiler built-in */ }) } | |
388 | ||
e9174d1e | 389 | /// Includes a file as a reference to a byte array. |
1a4d82fc | 390 | /// |
e9174d1e | 391 | /// This macro will yield an expression of type `&'static [u8; N]` which is |
1a4d82fc JJ |
392 | /// the contents of the filename specified. The file is located relative to |
393 | /// the current file (similarly to how modules are found), | |
394 | /// | |
c34b1796 | 395 | /// # Examples |
1a4d82fc JJ |
396 | /// |
397 | /// ```rust,ignore | |
398 | /// let secret_key = include_bytes!("secret-key.bin"); | |
399 | /// ``` | |
92a42be0 | 400 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
401 | #[macro_export] |
402 | macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) } | |
403 | ||
404 | /// Expands to a string that represents the current module path. | |
405 | /// | |
406 | /// The current module path can be thought of as the hierarchy of modules | |
407 | /// leading back up to the crate root. The first component of the path | |
408 | /// returned is the name of the crate currently being compiled. | |
409 | /// | |
c34b1796 | 410 | /// # Examples |
1a4d82fc | 411 | /// |
c34b1796 | 412 | /// ``` |
1a4d82fc JJ |
413 | /// mod test { |
414 | /// pub fn foo() { | |
415 | /// assert!(module_path!().ends_with("test")); | |
416 | /// } | |
417 | /// } | |
418 | /// | |
419 | /// test::foo(); | |
420 | /// ``` | |
92a42be0 | 421 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
422 | #[macro_export] |
423 | macro_rules! module_path { () => ({ /* compiler built-in */ }) } | |
424 | ||
425 | /// Boolean evaluation of configuration flags. | |
426 | /// | |
427 | /// In addition to the `#[cfg]` attribute, this macro is provided to allow | |
428 | /// boolean expression evaluation of configuration flags. This frequently | |
429 | /// leads to less duplicated code. | |
430 | /// | |
92a42be0 SL |
431 | /// The syntax given to this macro is the same syntax as [the `cfg` |
432 | /// attribute](../reference.html#conditional-compilation). | |
1a4d82fc | 433 | /// |
c34b1796 | 434 | /// # Examples |
1a4d82fc | 435 | /// |
c34b1796 | 436 | /// ``` |
1a4d82fc JJ |
437 | /// let my_directory = if cfg!(windows) { |
438 | /// "windows-specific-directory" | |
439 | /// } else { | |
440 | /// "unix-directory" | |
441 | /// }; | |
442 | /// ``` | |
92a42be0 | 443 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 444 | #[macro_export] |
92a42be0 | 445 | macro_rules! cfg { ($($cfg:tt)*) => ({ /* compiler built-in */ }) } |
c34b1796 AL |
446 | |
447 | /// Parse the current given file as an expression. | |
448 | /// | |
d9579d0f | 449 | /// This is generally a bad idea, because it's going to behave unhygienically. |
c34b1796 AL |
450 | /// |
451 | /// # Examples | |
452 | /// | |
453 | /// ```ignore | |
454 | /// fn foo() { | |
455 | /// include!("/path/to/a/file") | |
456 | /// } | |
457 | /// ``` | |
92a42be0 | 458 | #[stable(feature = "rust1", since = "1.0.0")] |
c34b1796 | 459 | #[macro_export] |
92a42be0 | 460 | macro_rules! include { ($file:expr) => ({ /* compiler built-in */ }) } |
1a4d82fc | 461 | } |