]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | // Copyright 2014 The Rust Project Developers. See the COPYRIGHT |
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 | ||
bd371182 | 11 | /// Entry point of thread panic, for details, see std::macros |
1a4d82fc | 12 | #[macro_export] |
62682a34 | 13 | #[allow_internal_unstable] |
92a42be0 | 14 | #[stable(feature = "core", since = "1.6.0")] |
1a4d82fc JJ |
15 | macro_rules! panic { |
16 | () => ( | |
17 | panic!("explicit panic") | |
18 | ); | |
19 | ($msg:expr) => ({ | |
ea8adc8c | 20 | $crate::panicking::panic(&($msg, file!(), line!(), __rust_unstable_column!())) |
1a4d82fc | 21 | }); |
0531ce1d XL |
22 | ($msg:expr,) => ( |
23 | panic!($msg) | |
24 | ); | |
25 | ($fmt:expr, $($arg:tt)+) => ({ | |
ea8adc8c XL |
26 | $crate::panicking::panic_fmt(format_args!($fmt, $($arg)*), |
27 | &(file!(), line!(), __rust_unstable_column!())) | |
1a4d82fc JJ |
28 | }); |
29 | } | |
30 | ||
041b39d2 | 31 | /// Asserts that two expressions are equal to each other (using [`PartialEq`]). |
1a4d82fc | 32 | /// |
c34b1796 AL |
33 | /// On panic, this macro will print the values of the expressions with their |
34 | /// debug representations. | |
1a4d82fc | 35 | /// |
041b39d2 | 36 | /// Like [`assert!`], this macro has a second form, where a custom |
32a655c1 SL |
37 | /// panic message can be provided. |
38 | /// | |
041b39d2 | 39 | /// [`PartialEq`]: cmp/trait.PartialEq.html |
cc61c64b | 40 | /// [`assert!`]: macro.assert.html |
8bb4bdeb | 41 | /// |
c34b1796 | 42 | /// # Examples |
1a4d82fc JJ |
43 | /// |
44 | /// ``` | |
85aaf69f SL |
45 | /// let a = 3; |
46 | /// let b = 1 + 2; | |
1a4d82fc | 47 | /// assert_eq!(a, b); |
32a655c1 SL |
48 | /// |
49 | /// assert_eq!(a, b, "we are testing addition with {} and {}", a, b); | |
1a4d82fc JJ |
50 | /// ``` |
51 | #[macro_export] | |
85aaf69f | 52 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 53 | macro_rules! assert_eq { |
8bb4bdeb | 54 | ($left:expr, $right:expr) => ({ |
a7813a04 | 55 | match (&$left, &$right) { |
1a4d82fc | 56 | (left_val, right_val) => { |
c34b1796 | 57 | if !(*left_val == *right_val) { |
041b39d2 XL |
58 | panic!(r#"assertion failed: `(left == right)` |
59 | left: `{:?}`, | |
60 | right: `{:?}`"#, left_val, right_val) | |
1a4d82fc JJ |
61 | } |
62 | } | |
63 | } | |
3157f602 | 64 | }); |
abe05a73 XL |
65 | ($left:expr, $right:expr,) => ({ |
66 | assert_eq!($left, $right) | |
67 | }); | |
8bb4bdeb | 68 | ($left:expr, $right:expr, $($arg:tt)+) => ({ |
3157f602 XL |
69 | match (&($left), &($right)) { |
70 | (left_val, right_val) => { | |
71 | if !(*left_val == *right_val) { | |
041b39d2 XL |
72 | panic!(r#"assertion failed: `(left == right)` |
73 | left: `{:?}`, | |
74 | right: `{:?}`: {}"#, left_val, right_val, | |
8bb4bdeb | 75 | format_args!($($arg)+)) |
3157f602 XL |
76 | } |
77 | } | |
78 | } | |
79 | }); | |
1a4d82fc JJ |
80 | } |
81 | ||
041b39d2 | 82 | /// Asserts that two expressions are not equal to each other (using [`PartialEq`]). |
9e0c209e SL |
83 | /// |
84 | /// On panic, this macro will print the values of the expressions with their | |
85 | /// debug representations. | |
86 | /// | |
041b39d2 | 87 | /// Like [`assert!`], this macro has a second form, where a custom |
32a655c1 SL |
88 | /// panic message can be provided. |
89 | /// | |
041b39d2 | 90 | /// [`PartialEq`]: cmp/trait.PartialEq.html |
8bb4bdeb XL |
91 | /// [`assert!`]: macro.assert.html |
92 | /// | |
9e0c209e SL |
93 | /// # Examples |
94 | /// | |
95 | /// ``` | |
96 | /// let a = 3; | |
97 | /// let b = 2; | |
98 | /// assert_ne!(a, b); | |
32a655c1 SL |
99 | /// |
100 | /// assert_ne!(a, b, "we are testing that the values are not equal"); | |
9e0c209e SL |
101 | /// ``` |
102 | #[macro_export] | |
cc61c64b | 103 | #[stable(feature = "assert_ne", since = "1.13.0")] |
9e0c209e | 104 | macro_rules! assert_ne { |
8bb4bdeb | 105 | ($left:expr, $right:expr) => ({ |
9e0c209e SL |
106 | match (&$left, &$right) { |
107 | (left_val, right_val) => { | |
108 | if *left_val == *right_val { | |
041b39d2 XL |
109 | panic!(r#"assertion failed: `(left != right)` |
110 | left: `{:?}`, | |
111 | right: `{:?}`"#, left_val, right_val) | |
9e0c209e SL |
112 | } |
113 | } | |
114 | } | |
115 | }); | |
abe05a73 XL |
116 | ($left:expr, $right:expr,) => { |
117 | assert_ne!($left, $right) | |
118 | }; | |
8bb4bdeb | 119 | ($left:expr, $right:expr, $($arg:tt)+) => ({ |
9e0c209e SL |
120 | match (&($left), &($right)) { |
121 | (left_val, right_val) => { | |
122 | if *left_val == *right_val { | |
041b39d2 XL |
123 | panic!(r#"assertion failed: `(left != right)` |
124 | left: `{:?}`, | |
125 | right: `{:?}`: {}"#, left_val, right_val, | |
8bb4bdeb | 126 | format_args!($($arg)+)) |
9e0c209e SL |
127 | } |
128 | } | |
129 | } | |
130 | }); | |
131 | } | |
132 | ||
1a4d82fc JJ |
133 | /// Ensure that a boolean expression is `true` at runtime. |
134 | /// | |
8bb4bdeb | 135 | /// This will invoke the [`panic!`] macro if the provided expression cannot be |
1a4d82fc JJ |
136 | /// evaluated to `true` at runtime. |
137 | /// | |
8bb4bdeb | 138 | /// Like [`assert!`], this macro also has a second version, where a custom panic |
92a42be0 SL |
139 | /// message can be provided. |
140 | /// | |
041b39d2 XL |
141 | /// # Uses |
142 | /// | |
8bb4bdeb | 143 | /// Unlike [`assert!`], `debug_assert!` statements are only enabled in non |
c34b1796 AL |
144 | /// optimized builds by default. An optimized build will omit all |
145 | /// `debug_assert!` statements unless `-C debug-assertions` is passed to the | |
146 | /// compiler. This makes `debug_assert!` useful for checks that are too | |
147 | /// expensive to be present in a release build but may be helpful during | |
148 | /// development. | |
1a4d82fc | 149 | /// |
5bcae85e SL |
150 | /// An unchecked assertion allows a program in an inconsistent state to keep |
151 | /// running, which might have unexpected consequences but does not introduce | |
152 | /// unsafety as long as this only happens in safe code. The performance cost | |
8bb4bdeb | 153 | /// of assertions, is however, not measurable in general. Replacing [`assert!`] |
5bcae85e SL |
154 | /// with `debug_assert!` is thus only encouraged after thorough profiling, and |
155 | /// more importantly, only in safe code! | |
156 | /// | |
8bb4bdeb XL |
157 | /// [`panic!`]: macro.panic.html |
158 | /// [`assert!`]: macro.assert.html | |
159 | /// | |
c34b1796 | 160 | /// # Examples |
1a4d82fc JJ |
161 | /// |
162 | /// ``` | |
163 | /// // the panic message for these assertions is the stringified value of the | |
164 | /// // expression given. | |
165 | /// debug_assert!(true); | |
85aaf69f SL |
166 | /// |
167 | /// fn some_expensive_computation() -> bool { true } // a very simple function | |
1a4d82fc JJ |
168 | /// debug_assert!(some_expensive_computation()); |
169 | /// | |
170 | /// // assert with a custom message | |
85aaf69f | 171 | /// let x = true; |
1a4d82fc | 172 | /// debug_assert!(x, "x wasn't true!"); |
85aaf69f SL |
173 | /// |
174 | /// let a = 3; let b = 27; | |
1a4d82fc JJ |
175 | /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b); |
176 | /// ``` | |
177 | #[macro_export] | |
85aaf69f | 178 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 179 | macro_rules! debug_assert { |
c34b1796 | 180 | ($($arg:tt)*) => (if cfg!(debug_assertions) { assert!($($arg)*); }) |
1a4d82fc JJ |
181 | } |
182 | ||
9cc50fc6 | 183 | /// Asserts that two expressions are equal to each other. |
1a4d82fc | 184 | /// |
9cc50fc6 SL |
185 | /// On panic, this macro will print the values of the expressions with their |
186 | /// debug representations. | |
1a4d82fc | 187 | /// |
ea8adc8c | 188 | /// Unlike [`assert_eq!`], `debug_assert_eq!` statements are only enabled in non |
c34b1796 AL |
189 | /// optimized builds by default. An optimized build will omit all |
190 | /// `debug_assert_eq!` statements unless `-C debug-assertions` is passed to the | |
191 | /// compiler. This makes `debug_assert_eq!` useful for checks that are too | |
192 | /// expensive to be present in a release build but may be helpful during | |
193 | /// development. | |
1a4d82fc | 194 | /// |
ea8adc8c XL |
195 | /// [`assert_eq!`]: ../std/macro.assert_eq.html |
196 | /// | |
c34b1796 | 197 | /// # Examples |
1a4d82fc JJ |
198 | /// |
199 | /// ``` | |
85aaf69f SL |
200 | /// let a = 3; |
201 | /// let b = 1 + 2; | |
1a4d82fc JJ |
202 | /// debug_assert_eq!(a, b); |
203 | /// ``` | |
204 | #[macro_export] | |
92a42be0 | 205 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 206 | macro_rules! debug_assert_eq { |
c34b1796 | 207 | ($($arg:tt)*) => (if cfg!(debug_assertions) { assert_eq!($($arg)*); }) |
1a4d82fc JJ |
208 | } |
209 | ||
9e0c209e SL |
210 | /// Asserts that two expressions are not equal to each other. |
211 | /// | |
212 | /// On panic, this macro will print the values of the expressions with their | |
213 | /// debug representations. | |
214 | /// | |
ea8adc8c | 215 | /// Unlike [`assert_ne!`], `debug_assert_ne!` statements are only enabled in non |
9e0c209e SL |
216 | /// optimized builds by default. An optimized build will omit all |
217 | /// `debug_assert_ne!` statements unless `-C debug-assertions` is passed to the | |
218 | /// compiler. This makes `debug_assert_ne!` useful for checks that are too | |
219 | /// expensive to be present in a release build but may be helpful during | |
220 | /// development. | |
221 | /// | |
ea8adc8c XL |
222 | /// [`assert_ne!`]: ../std/macro.assert_ne.html |
223 | /// | |
9e0c209e SL |
224 | /// # Examples |
225 | /// | |
226 | /// ``` | |
227 | /// let a = 3; | |
228 | /// let b = 2; | |
229 | /// debug_assert_ne!(a, b); | |
230 | /// ``` | |
231 | #[macro_export] | |
cc61c64b | 232 | #[stable(feature = "assert_ne", since = "1.13.0")] |
9e0c209e SL |
233 | macro_rules! debug_assert_ne { |
234 | ($($arg:tt)*) => (if cfg!(debug_assertions) { assert_ne!($($arg)*); }) | |
235 | } | |
236 | ||
237 | /// Helper macro for reducing boilerplate code for matching `Result` together | |
238 | /// with converting downstream errors. | |
239 | /// | |
ea8adc8c | 240 | /// The `?` operator was added to replace `try!` and should be used instead. |
9e0c209e | 241 | /// |
ea8adc8c | 242 | /// `try!` matches the given [`Result`]. In case of the `Ok` variant, the |
9e0c209e SL |
243 | /// expression has the value of the wrapped value. |
244 | /// | |
245 | /// In case of the `Err` variant, it retrieves the inner error. `try!` then | |
246 | /// performs conversion using `From`. This provides automatic conversion | |
247 | /// between specialized errors and more general ones. The resulting | |
248 | /// error is then immediately returned. | |
249 | /// | |
250 | /// Because of the early return, `try!` can only be used in functions that | |
ea8adc8c XL |
251 | /// return [`Result`]. |
252 | /// | |
253 | /// [`Result`]: ../std/result/enum.Result.html | |
1a4d82fc | 254 | /// |
92a42be0 SL |
255 | /// # Examples |
256 | /// | |
257 | /// ``` | |
258 | /// use std::io; | |
259 | /// use std::fs::File; | |
260 | /// use std::io::prelude::*; | |
261 | /// | |
9e0c209e SL |
262 | /// enum MyError { |
263 | /// FileWriteError | |
264 | /// } | |
265 | /// | |
266 | /// impl From<io::Error> for MyError { | |
267 | /// fn from(e: io::Error) -> MyError { | |
268 | /// MyError::FileWriteError | |
269 | /// } | |
270 | /// } | |
271 | /// | |
2c00a5a8 | 272 | /// // The preferred method of quick returning Errors |
ea8adc8c XL |
273 | /// fn write_to_file_question() -> Result<(), MyError> { |
274 | /// let mut file = File::create("my_best_friends.txt")?; | |
2c00a5a8 | 275 | /// file.write_all(b"This is a list of my best friends.")?; |
ea8adc8c XL |
276 | /// Ok(()) |
277 | /// } | |
278 | /// | |
279 | /// // The previous method of quick returning Errors | |
9e0c209e | 280 | /// fn write_to_file_using_try() -> Result<(), MyError> { |
92a42be0 SL |
281 | /// let mut file = try!(File::create("my_best_friends.txt")); |
282 | /// try!(file.write_all(b"This is a list of my best friends.")); | |
92a42be0 SL |
283 | /// Ok(()) |
284 | /// } | |
ea8adc8c | 285 | /// |
92a42be0 | 286 | /// // This is equivalent to: |
9e0c209e | 287 | /// fn write_to_file_using_match() -> Result<(), MyError> { |
92a42be0 SL |
288 | /// let mut file = try!(File::create("my_best_friends.txt")); |
289 | /// match file.write_all(b"This is a list of my best friends.") { | |
a7813a04 | 290 | /// Ok(v) => v, |
9e0c209e | 291 | /// Err(e) => return Err(From::from(e)), |
92a42be0 | 292 | /// } |
92a42be0 SL |
293 | /// Ok(()) |
294 | /// } | |
295 | /// ``` | |
1a4d82fc | 296 | #[macro_export] |
92a42be0 | 297 | #[stable(feature = "rust1", since = "1.0.0")] |
83c7162d | 298 | #[doc(alias = "?")] |
1a4d82fc | 299 | macro_rules! try { |
92a42be0 SL |
300 | ($expr:expr) => (match $expr { |
301 | $crate::result::Result::Ok(val) => val, | |
302 | $crate::result::Result::Err(err) => { | |
303 | return $crate::result::Result::Err($crate::convert::From::from(err)) | |
1a4d82fc | 304 | } |
0531ce1d XL |
305 | }); |
306 | ($expr:expr,) => (try!($expr)); | |
1a4d82fc JJ |
307 | } |
308 | ||
ff7c6d11 | 309 | /// Write formatted data into a buffer. |
b039eaaf | 310 | /// |
cc61c64b XL |
311 | /// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be |
312 | /// formatted according to the specified format string and the result will be passed to the writer. | |
313 | /// The writer may be any value with a `write_fmt` method; generally this comes from an | |
314 | /// implementation of either the [`std::fmt::Write`] or the [`std::io::Write`] trait. The macro | |
ea8adc8c | 315 | /// returns whatever the `write_fmt` method returns; commonly a [`std::fmt::Result`], or an |
cc61c64b | 316 | /// [`io::Result`]. |
b039eaaf | 317 | /// |
cc61c64b | 318 | /// See [`std::fmt`] for more information on the format string syntax. |
5bcae85e | 319 | /// |
cc61c64b XL |
320 | /// [`std::fmt`]: ../std/fmt/index.html |
321 | /// [`std::fmt::Write`]: ../std/fmt/trait.Write.html | |
322 | /// [`std::io::Write`]: ../std/io/trait.Write.html | |
323 | /// [`std::fmt::Result`]: ../std/fmt/type.Result.html | |
324 | /// [`io::Result`]: ../std/io/type.Result.html | |
1a4d82fc | 325 | /// |
c34b1796 | 326 | /// # Examples |
1a4d82fc JJ |
327 | /// |
328 | /// ``` | |
c34b1796 | 329 | /// use std::io::Write; |
1a4d82fc JJ |
330 | /// |
331 | /// let mut w = Vec::new(); | |
62682a34 SL |
332 | /// write!(&mut w, "test").unwrap(); |
333 | /// write!(&mut w, "formatted {}", "arguments").unwrap(); | |
b039eaaf SL |
334 | /// |
335 | /// assert_eq!(w, b"testformatted arguments"); | |
1a4d82fc | 336 | /// ``` |
476ff2be SL |
337 | /// |
338 | /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects | |
339 | /// implementing either, as objects do not typically implement both. However, the module must | |
340 | /// import the traits qualified so their names do not conflict: | |
341 | /// | |
342 | /// ``` | |
343 | /// use std::fmt::Write as FmtWrite; | |
344 | /// use std::io::Write as IoWrite; | |
345 | /// | |
346 | /// let mut s = String::new(); | |
347 | /// let mut v = Vec::new(); | |
348 | /// write!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt | |
349 | /// write!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt | |
350 | /// assert_eq!(v, b"s = \"abc 123\""); | |
351 | /// ``` | |
1a4d82fc | 352 | #[macro_export] |
cc61c64b | 353 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 354 | macro_rules! write { |
9346a6ac | 355 | ($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*))) |
1a4d82fc JJ |
356 | } |
357 | ||
c30ab7b3 | 358 | /// Write formatted data into a buffer, with a newline appended. |
5bcae85e SL |
359 | /// |
360 | /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone | |
361 | /// (no additional CARRIAGE RETURN (`\r`/`U+000D`). | |
362 | /// | |
cc61c64b XL |
363 | /// For more information, see [`write!`]. For information on the format string syntax, see |
364 | /// [`std::fmt`]. | |
5bcae85e | 365 | /// |
cc61c64b XL |
366 | /// [`write!`]: macro.write.html |
367 | /// [`std::fmt`]: ../std/fmt/index.html | |
b039eaaf | 368 | /// |
b039eaaf SL |
369 | /// |
370 | /// # Examples | |
371 | /// | |
372 | /// ``` | |
373 | /// use std::io::Write; | |
374 | /// | |
375 | /// let mut w = Vec::new(); | |
32a655c1 | 376 | /// writeln!(&mut w).unwrap(); |
b039eaaf SL |
377 | /// writeln!(&mut w, "test").unwrap(); |
378 | /// writeln!(&mut w, "formatted {}", "arguments").unwrap(); | |
379 | /// | |
32a655c1 | 380 | /// assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes()); |
b039eaaf | 381 | /// ``` |
476ff2be SL |
382 | /// |
383 | /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects | |
384 | /// implementing either, as objects do not typically implement both. However, the module must | |
385 | /// import the traits qualified so their names do not conflict: | |
386 | /// | |
387 | /// ``` | |
388 | /// use std::fmt::Write as FmtWrite; | |
389 | /// use std::io::Write as IoWrite; | |
390 | /// | |
391 | /// let mut s = String::new(); | |
392 | /// let mut v = Vec::new(); | |
393 | /// writeln!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt | |
394 | /// writeln!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt | |
395 | /// assert_eq!(v, b"s = \"abc 123\\n\"\n"); | |
396 | /// ``` | |
1a4d82fc | 397 | #[macro_export] |
85aaf69f | 398 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 399 | macro_rules! writeln { |
32a655c1 SL |
400 | ($dst:expr) => ( |
401 | write!($dst, "\n") | |
402 | ); | |
0531ce1d XL |
403 | ($dst:expr,) => ( |
404 | writeln!($dst) | |
405 | ); | |
1a4d82fc JJ |
406 | ($dst:expr, $fmt:expr) => ( |
407 | write!($dst, concat!($fmt, "\n")) | |
408 | ); | |
409 | ($dst:expr, $fmt:expr, $($arg:tt)*) => ( | |
410 | write!($dst, concat!($fmt, "\n"), $($arg)*) | |
411 | ); | |
412 | } | |
413 | ||
414 | /// A utility macro for indicating unreachable code. | |
415 | /// | |
416 | /// This is useful any time that the compiler can't determine that some code is unreachable. For | |
417 | /// example: | |
418 | /// | |
419 | /// * Match arms with guard conditions. | |
420 | /// * Loops that dynamically terminate. | |
421 | /// * Iterators that dynamically terminate. | |
422 | /// | |
ea8adc8c | 423 | /// If the determination that the code is unreachable proves incorrect, the |
83c7162d XL |
424 | /// program immediately terminates with a [`panic!`]. The function [`unreachable_unchecked`], |
425 | /// which belongs to the [`std::hint`] module, informs the compilier to | |
ea8adc8c XL |
426 | /// optimize the code out of the release version entirely. |
427 | /// | |
428 | /// [`panic!`]: ../std/macro.panic.html | |
83c7162d XL |
429 | /// [`unreachable_unchecked`]: ../std/hint/fn.unreachable_unchecked.html |
430 | /// [`std::hint`]: ../std/hint/index.html | |
ea8adc8c | 431 | /// |
1a4d82fc JJ |
432 | /// # Panics |
433 | /// | |
ea8adc8c | 434 | /// This will always [`panic!`] |
1a4d82fc | 435 | /// |
ea8adc8c | 436 | /// [`panic!`]: ../std/macro.panic.html |
1a4d82fc JJ |
437 | /// # Examples |
438 | /// | |
439 | /// Match arms: | |
440 | /// | |
c34b1796 | 441 | /// ``` |
92a42be0 | 442 | /// # #[allow(dead_code)] |
c34b1796 | 443 | /// fn foo(x: Option<i32>) { |
1a4d82fc JJ |
444 | /// match x { |
445 | /// Some(n) if n >= 0 => println!("Some(Non-negative)"), | |
446 | /// Some(n) if n < 0 => println!("Some(Negative)"), | |
447 | /// Some(_) => unreachable!(), // compile error if commented out | |
448 | /// None => println!("None") | |
449 | /// } | |
450 | /// } | |
451 | /// ``` | |
452 | /// | |
453 | /// Iterators: | |
454 | /// | |
c34b1796 | 455 | /// ``` |
92a42be0 | 456 | /// # #[allow(dead_code)] |
1a4d82fc | 457 | /// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3 |
c34b1796 | 458 | /// for i in 0.. { |
1a4d82fc JJ |
459 | /// if 3*i < i { panic!("u32 overflow"); } |
460 | /// if x < 3*i { return i-1; } | |
461 | /// } | |
462 | /// unreachable!(); | |
463 | /// } | |
464 | /// ``` | |
465 | #[macro_export] | |
cc61c64b | 466 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
467 | macro_rules! unreachable { |
468 | () => ({ | |
469 | panic!("internal error: entered unreachable code") | |
470 | }); | |
471 | ($msg:expr) => ({ | |
472 | unreachable!("{}", $msg) | |
473 | }); | |
0531ce1d XL |
474 | ($msg:expr,) => ({ |
475 | unreachable!($msg) | |
476 | }); | |
1a4d82fc JJ |
477 | ($fmt:expr, $($arg:tt)*) => ({ |
478 | panic!(concat!("internal error: entered unreachable code: ", $fmt), $($arg)*) | |
479 | }); | |
480 | } | |
481 | ||
ea8adc8c | 482 | /// A standardized placeholder for marking unfinished code. |
e9174d1e SL |
483 | /// |
484 | /// This can be useful if you are prototyping and are just looking to have your | |
485 | /// code typecheck, or if you're implementing a trait that requires multiple | |
486 | /// methods, and you're only planning on using one of them. | |
487 | /// | |
ea8adc8c XL |
488 | /// # Panics |
489 | /// | |
490 | /// This will always [panic!](macro.panic.html) | |
491 | /// | |
e9174d1e SL |
492 | /// # Examples |
493 | /// | |
494 | /// Here's an example of some in-progress code. We have a trait `Foo`: | |
495 | /// | |
496 | /// ``` | |
497 | /// trait Foo { | |
498 | /// fn bar(&self); | |
499 | /// fn baz(&self); | |
500 | /// } | |
501 | /// ``` | |
502 | /// | |
503 | /// We want to implement `Foo` on one of our types, but we also want to work on | |
504 | /// just `bar()` first. In order for our code to compile, we need to implement | |
505 | /// `baz()`, so we can use `unimplemented!`: | |
506 | /// | |
507 | /// ``` | |
508 | /// # trait Foo { | |
e9174d1e | 509 | /// # fn bar(&self); |
92a42be0 | 510 | /// # fn baz(&self); |
e9174d1e SL |
511 | /// # } |
512 | /// struct MyStruct; | |
513 | /// | |
514 | /// impl Foo for MyStruct { | |
92a42be0 | 515 | /// fn bar(&self) { |
e9174d1e SL |
516 | /// // implementation goes here |
517 | /// } | |
518 | /// | |
92a42be0 SL |
519 | /// fn baz(&self) { |
520 | /// // let's not worry about implementing baz() for now | |
e9174d1e SL |
521 | /// unimplemented!(); |
522 | /// } | |
523 | /// } | |
524 | /// | |
525 | /// fn main() { | |
526 | /// let s = MyStruct; | |
92a42be0 | 527 | /// s.bar(); |
e9174d1e | 528 | /// |
92a42be0 | 529 | /// // we aren't even using baz() yet, so this is fine. |
e9174d1e SL |
530 | /// } |
531 | /// ``` | |
1a4d82fc | 532 | #[macro_export] |
cc61c64b | 533 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 534 | macro_rules! unimplemented { |
041b39d2 XL |
535 | () => (panic!("not yet implemented")); |
536 | ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)*))); | |
1a4d82fc | 537 | } |
c30ab7b3 SL |
538 | |
539 | /// Built-in macros to the compiler itself. | |
540 | /// | |
541 | /// These macros do not have any corresponding definition with a `macro_rules!` | |
542 | /// macro, but are documented here. Their implementations can be found hardcoded | |
543 | /// into libsyntax itself. | |
544 | /// | |
545 | /// For more information, see documentation for `std`'s macros. | |
546 | mod builtin { | |
041b39d2 XL |
547 | |
548 | /// Unconditionally causes compilation to fail with the given error message when encountered. | |
549 | /// | |
ff7c6d11 | 550 | /// For more information, see the documentation for [`std::compile_error!`]. |
041b39d2 | 551 | /// |
ff7c6d11 | 552 | /// [`std::compile_error!`]: ../std/macro.compile_error.html |
041b39d2 XL |
553 | #[stable(feature = "compile_error_macro", since = "1.20.0")] |
554 | #[macro_export] | |
555 | #[cfg(dox)] | |
0531ce1d XL |
556 | macro_rules! compile_error { |
557 | ($msg:expr) => ({ /* compiler built-in */ }); | |
558 | ($msg:expr,) => ({ /* compiler built-in */ }); | |
559 | } | |
041b39d2 | 560 | |
c30ab7b3 SL |
561 | /// The core macro for formatted string creation & output. |
562 | /// | |
563 | /// For more information, see the documentation for [`std::format_args!`]. | |
564 | /// | |
565 | /// [`std::format_args!`]: ../std/macro.format_args.html | |
566 | #[stable(feature = "rust1", since = "1.0.0")] | |
567 | #[macro_export] | |
568 | #[cfg(dox)] | |
ff7c6d11 XL |
569 | macro_rules! format_args { |
570 | ($fmt:expr) => ({ /* compiler built-in */ }); | |
571 | ($fmt:expr, $($args:tt)*) => ({ /* compiler built-in */ }); | |
572 | } | |
c30ab7b3 SL |
573 | |
574 | /// Inspect an environment variable at compile time. | |
575 | /// | |
576 | /// For more information, see the documentation for [`std::env!`]. | |
577 | /// | |
578 | /// [`std::env!`]: ../std/macro.env.html | |
579 | #[stable(feature = "rust1", since = "1.0.0")] | |
580 | #[macro_export] | |
581 | #[cfg(dox)] | |
ff7c6d11 XL |
582 | macro_rules! env { |
583 | ($name:expr) => ({ /* compiler built-in */ }); | |
584 | ($name:expr,) => ({ /* compiler built-in */ }); | |
585 | } | |
c30ab7b3 SL |
586 | |
587 | /// Optionally inspect an environment variable at compile time. | |
588 | /// | |
589 | /// For more information, see the documentation for [`std::option_env!`]. | |
590 | /// | |
591 | /// [`std::option_env!`]: ../std/macro.option_env.html | |
592 | #[stable(feature = "rust1", since = "1.0.0")] | |
593 | #[macro_export] | |
594 | #[cfg(dox)] | |
0531ce1d XL |
595 | macro_rules! option_env { |
596 | ($name:expr) => ({ /* compiler built-in */ }); | |
597 | ($name:expr,) => ({ /* compiler built-in */ }); | |
598 | } | |
c30ab7b3 SL |
599 | |
600 | /// Concatenate identifiers into one identifier. | |
601 | /// | |
602 | /// For more information, see the documentation for [`std::concat_idents!`]. | |
603 | /// | |
604 | /// [`std::concat_idents!`]: ../std/macro.concat_idents.html | |
605 | #[unstable(feature = "concat_idents_macro", issue = "29599")] | |
606 | #[macro_export] | |
607 | #[cfg(dox)] | |
608 | macro_rules! concat_idents { | |
83c7162d XL |
609 | ($($e:ident),+) => ({ /* compiler built-in */ }); |
610 | ($($e:ident,)+) => ({ /* compiler built-in */ }); | |
c30ab7b3 SL |
611 | } |
612 | ||
613 | /// Concatenates literals into a static string slice. | |
614 | /// | |
615 | /// For more information, see the documentation for [`std::concat!`]. | |
616 | /// | |
617 | /// [`std::concat!`]: ../std/macro.concat.html | |
618 | #[stable(feature = "rust1", since = "1.0.0")] | |
619 | #[macro_export] | |
620 | #[cfg(dox)] | |
ff7c6d11 XL |
621 | macro_rules! concat { |
622 | ($($e:expr),*) => ({ /* compiler built-in */ }); | |
623 | ($($e:expr,)*) => ({ /* compiler built-in */ }); | |
624 | } | |
c30ab7b3 SL |
625 | |
626 | /// A macro which expands to the line number on which it was invoked. | |
627 | /// | |
628 | /// For more information, see the documentation for [`std::line!`]. | |
629 | /// | |
630 | /// [`std::line!`]: ../std/macro.line.html | |
631 | #[stable(feature = "rust1", since = "1.0.0")] | |
632 | #[macro_export] | |
633 | #[cfg(dox)] | |
634 | macro_rules! line { () => ({ /* compiler built-in */ }) } | |
635 | ||
636 | /// A macro which expands to the column number on which it was invoked. | |
637 | /// | |
638 | /// For more information, see the documentation for [`std::column!`]. | |
639 | /// | |
640 | /// [`std::column!`]: ../std/macro.column.html | |
641 | #[stable(feature = "rust1", since = "1.0.0")] | |
642 | #[macro_export] | |
643 | #[cfg(dox)] | |
644 | macro_rules! column { () => ({ /* compiler built-in */ }) } | |
645 | ||
646 | /// A macro which expands to the file name from which it was invoked. | |
647 | /// | |
648 | /// For more information, see the documentation for [`std::file!`]. | |
649 | /// | |
650 | /// [`std::file!`]: ../std/macro.file.html | |
651 | #[stable(feature = "rust1", since = "1.0.0")] | |
652 | #[macro_export] | |
653 | #[cfg(dox)] | |
654 | macro_rules! file { () => ({ /* compiler built-in */ }) } | |
655 | ||
abe05a73 | 656 | /// A macro which stringifies its arguments. |
c30ab7b3 SL |
657 | /// |
658 | /// For more information, see the documentation for [`std::stringify!`]. | |
659 | /// | |
660 | /// [`std::stringify!`]: ../std/macro.stringify.html | |
661 | #[stable(feature = "rust1", since = "1.0.0")] | |
662 | #[macro_export] | |
663 | #[cfg(dox)] | |
abe05a73 | 664 | macro_rules! stringify { ($($t:tt)*) => ({ /* compiler built-in */ }) } |
c30ab7b3 SL |
665 | |
666 | /// Includes a utf8-encoded file as a string. | |
667 | /// | |
668 | /// For more information, see the documentation for [`std::include_str!`]. | |
669 | /// | |
670 | /// [`std::include_str!`]: ../std/macro.include_str.html | |
671 | #[stable(feature = "rust1", since = "1.0.0")] | |
672 | #[macro_export] | |
673 | #[cfg(dox)] | |
0531ce1d XL |
674 | macro_rules! include_str { |
675 | ($file:expr) => ({ /* compiler built-in */ }); | |
676 | ($file:expr,) => ({ /* compiler built-in */ }); | |
677 | } | |
c30ab7b3 SL |
678 | |
679 | /// Includes a file as a reference to a byte array. | |
680 | /// | |
681 | /// For more information, see the documentation for [`std::include_bytes!`]. | |
682 | /// | |
683 | /// [`std::include_bytes!`]: ../std/macro.include_bytes.html | |
684 | #[stable(feature = "rust1", since = "1.0.0")] | |
685 | #[macro_export] | |
686 | #[cfg(dox)] | |
0531ce1d XL |
687 | macro_rules! include_bytes { |
688 | ($file:expr) => ({ /* compiler built-in */ }); | |
689 | ($file:expr,) => ({ /* compiler built-in */ }); | |
690 | } | |
c30ab7b3 SL |
691 | |
692 | /// Expands to a string that represents the current module path. | |
693 | /// | |
694 | /// For more information, see the documentation for [`std::module_path!`]. | |
695 | /// | |
696 | /// [`std::module_path!`]: ../std/macro.module_path.html | |
697 | #[stable(feature = "rust1", since = "1.0.0")] | |
698 | #[macro_export] | |
699 | #[cfg(dox)] | |
700 | macro_rules! module_path { () => ({ /* compiler built-in */ }) } | |
701 | ||
ff7c6d11 | 702 | /// Boolean evaluation of configuration flags, at compile-time. |
c30ab7b3 SL |
703 | /// |
704 | /// For more information, see the documentation for [`std::cfg!`]. | |
705 | /// | |
706 | /// [`std::cfg!`]: ../std/macro.cfg.html | |
707 | #[stable(feature = "rust1", since = "1.0.0")] | |
708 | #[macro_export] | |
709 | #[cfg(dox)] | |
710 | macro_rules! cfg { ($($cfg:tt)*) => ({ /* compiler built-in */ }) } | |
711 | ||
712 | /// Parse a file as an expression or an item according to the context. | |
713 | /// | |
714 | /// For more information, see the documentation for [`std::include!`]. | |
715 | /// | |
716 | /// [`std::include!`]: ../std/macro.include.html | |
717 | #[stable(feature = "rust1", since = "1.0.0")] | |
718 | #[macro_export] | |
719 | #[cfg(dox)] | |
0531ce1d XL |
720 | macro_rules! include { |
721 | ($file:expr) => ({ /* compiler built-in */ }); | |
722 | ($file:expr,) => ({ /* compiler built-in */ }); | |
723 | } | |
724 | ||
725 | /// Ensure that a boolean expression is `true` at runtime. | |
726 | /// | |
727 | /// For more information, see the documentation for [`std::assert!`]. | |
728 | /// | |
729 | /// [`std::assert!`]: ../std/macro.assert.html | |
730 | #[macro_export] | |
731 | #[stable(feature = "rust1", since = "1.0.0")] | |
732 | #[cfg(dox)] | |
733 | macro_rules! assert { | |
734 | ($cond:expr) => ({ /* compiler built-in */ }); | |
735 | ($cond:expr,) => ({ /* compiler built-in */ }); | |
736 | ($cond:expr, $($arg:tt)+) => ({ /* compiler built-in */ }); | |
737 | } | |
c30ab7b3 | 738 | } |