Rollup of 11 pull requests by Centril · Pull Request #59293 · rust-lang/rust (original) (raw)

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

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.