Rollup of 11 pull requests
Successful merges:
- #56348 (Add todo!() macro)
- #57729 (extra testing of how NLL handles wildcard type `_`)
- #57847 (dbg!() without parameters)
- #58778 (Implement ExactSizeIterator for ToLowercase and ToUppercase)
- #58812 (Clarify distinction between floor() and trunc())
- #58939 (Fix a tiny error in documentation of std::pin.)
- #59116 (Be more discerning on when to attempt suggesting a comma in a macro invocation)
- #59252 (add self to mailmap)
- #59275 (Replaced self-reflective explicit types with clearer `Self` or `Self::…` in stdlib docs)
- #59280 (Stabilize refcell_map_split feature)
- #59290 (Run branch cleanup after copy prop)
Failed merges:
r? @ghost
Replaced self-reflective explicit types with clearer `Self` or `Self::…` in stdlib docs
Many docs examples use explicit types instead of the semantically more clear `Self`/`Self::…` aliases.
By using the latter it's clear that the value's type depends on either `Self`, or an associated type of `Self`, instead of some constant type. It's also more consistent (and I'd argue correct), as the current docs aren't really consistent in this, as can be seen from the diff.
This is a best effort PR, as I was basically going through the docs manually, looking for offending examples. I'm sure I missed a few. Gotta start somewhere.
extra testing of how NLL handles wildcard type `_`
test that wildcard type `_` is not duplicated by `type Foo<X> = (X, X);` and potentially instantiated at different types when used in type ascriptions in let bindings.
(NLL's handling of this for the type ascription *expression form* is currently broken, or at least differs from what AST-borrowck does. I'll file a separate bug about that. Its not something critical to address since that expression is guarded by `#![feature(type_ascription)]`.)
cc #55748
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>
