Rollup merge of #56348 - matklad:todo-macro, r=withoutboats

Add todo!() macro

The primary use-case of `todo!()` macro is to be a much easier to type
alternative to `unimplemented!()` macro.

EDIT: hide unpopular proposal about re-purposing unimplemented

<details>
However, instead of just replacing `unimplemented!()`, it gives it a
more nuanced meaning: a thing which is intentionally left
unimplemented and which should not be called at runtime. Usually,
you'd like to prevent such cases statically, but sometimes you, for
example, have to implement a trait only some methods of which are
applicable. There are examples in the wild of code doing this thing,
and in this case, the current message of `unimplemented`, "not *yet*
implemented" is slightly misleading.

With the addition of TODO, you have three nuanced choices for a
`!`-returning macro (in addition to a good-old panic we all love):

  * todo!()
  * unreachable!()
  * unimplemented!()

Here's a rough guideline what each one means:

- `todo`: use it during development, as a "hole" or placeholder. It
  might be a good idea to add a pre-commit hook which checks that
  `todo` is not accidentally committed.

- `unreachable!()`: use it when your code can statically guarantee
  that some situation can not happen. If you use a library and hit
  `unreachable!()` in the library's code, it's definitely a bug in the
  library. It's OK to have `unreachable!()` in the code base,
  although, if possible, it's better to replace it with
  compiler-verified exhaustive checks.

- `unimplemented!()`: use it when the type checker forces you to
  handle some situation, but there's a contract that a callee must not
  actually call the code. If you use a library and hit
  `unimplemented!()`, it's probably a bug in your code, though
  it *could* be a bug in the library (or library docs) as well. It is
  ok-ish to see an `unimplemented!()` in real code, but it usually
  signifies a clunky, eyebrow-rising API.
</details>

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index b052f59b0f5c2ae07f2f178764012852fae66ac5..d77936c7ddd913fe9cad93e213742ff693a6bb9f 100644 (file)
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -559,6 +559,65 @@ macro_rules! unimplemented {
     ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)*)));
 }
 
+/// A standardized placeholder for marking unfinished code.
+///
+/// This can be useful if you are prototyping and are just looking to have your
+/// code typecheck. `todo!` works exactly like `unimplemented!`, there only
+/// difference between the two macros is the name.
+///
+/// # Panics
+///
+/// This will always [panic!](macro.panic.html)
+///
+/// # Examples
+///
+/// Here's an example of some in-progress code. We have a trait `Foo`:
+///
+/// ```
+/// trait Foo {
+///     fn bar(&self);
+///     fn baz(&self);
+/// }
+/// ```
+///
+/// We want to implement `Foo` on one of our types, but we also want to work on
+/// just `bar()` first. In order for our code to compile, we need to implement
+/// `baz()`, so we can use `todo!`:
+///
+/// ```
+/// #![feature(todo_macro)]
+///
+/// # trait Foo {
+/// #     fn bar(&self);
+/// #     fn baz(&self);
+/// # }
+/// struct MyStruct;
+///
+/// impl Foo for MyStruct {
+///     fn bar(&self) {
+///         // implementation goes here
+///     }
+///
+///     fn baz(&self) {
+///         // let's not worry about implementing baz() for now
+///         todo!();
+///     }
+/// }
+///
+/// fn main() {
+///     let s = MyStruct;
+///     s.bar();
+///
+///     // we aren't even using baz() yet, so this is fine.
+/// }
+/// ```
+#[macro_export]
+#[unstable(feature = "todo_macro", issue = "59277")]
+macro_rules! todo {
+    () => (panic!("not yet implemented"));
+    ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)*)));
+}
+
 /// A macro to create an array of [`MaybeUninit`]
 ///
 /// This macro constructs an uninitialized array of the type `[MaybeUninit<K>; N]`.

diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index fc8ac9a0b3e00b57978501097236dbd9dda88f28..296c4c887274e61eb7b3f9d719c9915b322f69e7 100644 (file)
--- a/src/libstd/lib.rs
+++ b/src/libstd/lib.rs
@@ -301,6 +301,7 @@
 #![feature(stmt_expr_attributes)]
 #![feature(str_internals)]
 #![feature(thread_local)]
+#![feature(todo_macro)]
 #![feature(toowned_clone_into)]
 #![feature(try_reserve)]
 #![feature(unboxed_closures)]
@@ -323,7 +324,7 @@
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::{assert_eq, assert_ne, debug_assert, debug_assert_eq, debug_assert_ne};
 #[stable(feature = "rust1", since = "1.0.0")]
-pub use core::{unreachable, unimplemented, write, writeln, r#try};
+pub use core::{unreachable, unimplemented, write, writeln, r#try, todo};
 
 #[allow(unused_imports)] // macros from `alloc` are not used on all platforms
 #[macro_use]