/// This will invoke the [`panic!`] macro if the provided expression cannot be
/// evaluated to `true` at runtime.
///
+/// # Uses
+///
/// Assertions are always checked in both debug and release builds, and cannot
/// be disabled. See [`debug_assert!`] for assertions that are not enabled in
/// release builds by default.
/// Other use-cases of `assert!` include [testing] and enforcing run-time
/// invariants in safe code (whose violation cannot result in unsafety).
///
-/// This macro has a second version, where a custom panic message can
+/// # Custom Messages
+///
+/// This macro has a second form, where a custom panic message can
/// be provided with or without arguments for formatting.
///
/// [`panic!`]: macro.panic.html
);
}
-/// Asserts that two expressions are equal to each other.
+/// Asserts that two expressions are equal to each other (using [`PartialEq`]).
///
/// On panic, this macro will print the values of the expressions with their
/// debug representations.
///
-/// Like [`assert!`], this macro has a second version, where a custom
+/// Like [`assert!`], this macro has a second form, where a custom
/// panic message can be provided.
///
+/// [`PartialEq`]: cmp/trait.PartialEq.html
/// [`assert!`]: macro.assert.html
///
/// # Examples
match (&$left, &$right) {
(left_val, right_val) => {
if !(*left_val == *right_val) {
- panic!("assertion failed: `(left == right)` \
- (left: `{:?}`, right: `{:?}`)", left_val, right_val)
+ panic!(r#"assertion failed: `(left == right)`
+ left: `{:?}`
+ right: `{:?}`"#, left_val, right_val)
}
}
}
match (&($left), &($right)) {
(left_val, right_val) => {
if !(*left_val == *right_val) {
- panic!("assertion failed: `(left == right)` \
- (left: `{:?}`, right: `{:?}`): {}", left_val, right_val,
+ panic!(r#"assertion failed: `(left == right)`
+ left: `{:?}`
+ right: `{:?}`: {}"#, left_val, right_val,
format_args!($($arg)+))
}
}
});
}
-/// Asserts that two expressions are not equal to each other.
+/// Asserts that two expressions are not equal to each other (using [`PartialEq`]).
///
/// On panic, this macro will print the values of the expressions with their
/// debug representations.
///
-/// Like `assert!()`, this macro has a second version, where a custom
+/// Like [`assert!`], this macro has a second form, where a custom
/// panic message can be provided.
///
+/// [`PartialEq`]: cmp/trait.PartialEq.html
/// [`assert!`]: macro.assert.html
///
/// # Examples
/// assert_ne!(a, b, "we are testing that the values are not equal");
/// ```
#[macro_export]
-#[stable(feature = "assert_ne", since = "1.12.0")]
+#[stable(feature = "assert_ne", since = "1.13.0")]
macro_rules! assert_ne {
($left:expr, $right:expr) => ({
match (&$left, &$right) {
(left_val, right_val) => {
if *left_val == *right_val {
- panic!("assertion failed: `(left != right)` \
- (left: `{:?}`, right: `{:?}`)", left_val, right_val)
+ panic!(r#"assertion failed: `(left != right)`
+ left: `{:?}`
+ right: `{:?}`"#, left_val, right_val)
}
}
}
match (&($left), &($right)) {
(left_val, right_val) => {
if *left_val == *right_val {
- panic!("assertion failed: `(left != right)` \
- (left: `{:?}`, right: `{:?}`): {}", left_val, right_val,
+ panic!(r#"assertion failed: `(left != right)`
+ left: `{:?}`
+ right: `{:?}`: {}"#, left_val, right_val,
format_args!($($arg)+))
}
}
/// Like [`assert!`], this macro also has a second version, where a custom panic
/// message can be provided.
///
+/// # Uses
+///
/// Unlike [`assert!`], `debug_assert!` statements are only enabled in non
/// optimized builds by default. An optimized build will omit all
/// `debug_assert!` statements unless `-C debug-assertions` is passed to the
/// debug_assert_ne!(a, b);
/// ```
#[macro_export]
-#[stable(feature = "assert_ne", since = "1.12.0")]
+#[stable(feature = "assert_ne", since = "1.13.0")]
macro_rules! debug_assert_ne {
($($arg:tt)*) => (if cfg!(debug_assertions) { assert_ne!($($arg)*); })
}
/// Write formatted data into a buffer
///
-/// This macro accepts a 'writer' (any value with a `write_fmt` method), a format string, and a
-/// list of arguments to format.
+/// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be
+/// formatted according to the specified format string and the result will be passed to the writer.
+/// The writer may be any value with a `write_fmt` method; generally this comes from an
+/// implementation of either the [`std::fmt::Write`] or the [`std::io::Write`] trait. The macro
+/// returns whatever the 'write_fmt' method returns; commonly a [`std::fmt::Result`], or an
+/// [`io::Result`].
///
-/// The `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write]
-/// or [`std::io::Write`][io_write] traits. The term 'writer' refers to an implementation of one of
-/// these two traits.
+/// See [`std::fmt`] for more information on the format string syntax.
///
-/// Passed arguments will be formatted according to the specified format string and the resulting
-/// string will be passed to the writer.
-///
-/// See [`std::fmt`][fmt] for more information on format syntax.
-///
-/// `write!` returns whatever the 'write_fmt' method returns.
-///
-/// Common return values include: [`fmt::Result`][fmt_result], [`io::Result`][io_result]
-///
-/// [fmt]: ../std/fmt/index.html
-/// [fmt_write]: ../std/fmt/trait.Write.html
-/// [io_write]: ../std/io/trait.Write.html
-/// [fmt_result]: ../std/fmt/type.Result.html
-/// [io_result]: ../std/io/type.Result.html
+/// [`std::fmt`]: ../std/fmt/index.html
+/// [`std::fmt::Write`]: ../std/fmt/trait.Write.html
+/// [`std::io::Write`]: ../std/io/trait.Write.html
+/// [`std::fmt::Result`]: ../std/fmt/type.Result.html
+/// [`io::Result`]: ../std/io/type.Result.html
///
/// # Examples
///
/// assert_eq!(v, b"s = \"abc 123\"");
/// ```
#[macro_export]
-#[stable(feature = "core", since = "1.6.0")]
+#[stable(feature = "rust1", since = "1.0.0")]
macro_rules! write {
($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*)))
}
/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
/// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
///
-/// This macro accepts a 'writer' (any value with a `write_fmt` method), a format string, and a
-/// list of arguments to format.
-///
-/// The `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write]
-/// or [`std::io::Write`][io_write] traits. The term 'writer' refers to an implementation of one of
-/// these two traits.
-///
-/// Passed arguments will be formatted according to the specified format string and the resulting
-/// string will be passed to the writer, along with the appended newline.
-///
-/// See [`std::fmt`][fmt] for more information on format syntax.
-///
-/// `write!` returns whatever the 'write_fmt' method returns.
+/// For more information, see [`write!`]. For information on the format string syntax, see
+/// [`std::fmt`].
///
-/// Common return values include: [`fmt::Result`][fmt_result], [`io::Result`][io_result]
+/// [`write!`]: macro.write.html
+/// [`std::fmt`]: ../std/fmt/index.html
///
-/// [fmt]: ../std/fmt/index.html
-/// [fmt_write]: ../std/fmt/trait.Write.html
-/// [io_write]: ../std/io/trait.Write.html
-/// [fmt_result]: ../std/fmt/type.Result.html
-/// [io_result]: ../std/io/type.Result.html
///
/// # Examples
///
/// }
/// ```
#[macro_export]
-#[stable(feature = "core", since = "1.6.0")]
+#[stable(feature = "rust1", since = "1.0.0")]
macro_rules! unreachable {
() => ({
panic!("internal error: entered unreachable code")
/// }
/// ```
#[macro_export]
-#[stable(feature = "core", since = "1.6.0")]
+#[stable(feature = "rust1", since = "1.0.0")]
macro_rules! unimplemented {
() => (panic!("not yet implemented"))
}
projects / rust.git / blobdiff