The iterator is implemented using const generics. It implements the
traits `Iterator`, `DoubleEndedIterator`, `ExactSizeIterator`,
`FusedIterator` and `TrustedLen`. It also contains a public method
`new` to create it from an array.
`IntoIterator` was not implemented for arrays yet, as there are still
some open questions regarding backwards compatibility. This commit
only adds the iterator impl and does not yet offer a convenient way
to obtain that iterator.
Add the `matches!( $expr, $pat ) -> bool` macro
# Motivation
This macro is:
* General-purpose (not domain-specific)
* Simple (the implementation is short)
* Very popular [on crates.io](https://crates.io/crates/matches) (currently 37th in all-time downloads)
* The two previous points combined make it number one in [left-pad index](https://twitter.com/bascule/status/1184523027888988160) score
As such, I feel it is a good candidate for inclusion in the standard library.
In fact I already felt that way five years ago: https://github.com/rust-lang/rust/pull/14685 (Although the proof of popularity was not as strong at the time.)
# API
<details>
<del>
Back then, the main concern was that this macro may not be quite universally-enough useful to belong in the prelude.
Therefore, this PR adds the macro such that using it requires one of:
```rust
use core::macros::matches;
use std::macros::matches;
```
</del>
</details>
Like arms of a `match` expression, the macro supports multiple patterns separated by `|` and optionally followed by `if` and a guard expression:
```rust
let foo = 'f';
assert!(matches!(foo, 'A'..='Z' | 'a'..='z'));
let bar = Some(4);
assert!(matches!(bar, Some(x) if x > 2));
```
<details>
<del>
# Implementation constraints
A combination of reasons make it tricky for a standard library macro not to be in the prelude.
Currently, all public `macro_rules` macros in the standard library macros end up “in the prelude” of every crate not through `use std::prelude::v1::*;` like for other kinds of items, but through `#[macro_use]` on `extern crate std;`. (Both are injected by `src/libsyntax_ext/standard_library_imports.rs`.)
`#[macro_use]` seems to import every macro that is available at the top-level of a crate, even if through a `pub use` re-export.
Therefore, for `matches!` not to be in the prelude, we need it to be inside of a module rather than at the root of `core` or `std`.
However, the only way to make a `macro_rules` macro public outside of the crate where it is defined appears to be `#[macro_export]`. This exports the macro at the root of the crate regardless of which module defines it. See [macro scoping](https://doc.rust-lang.org/reference/macros-by-example.html#scoping-exporting-and-importing) in the reference.
Therefore, the macro needs to be defined in a crate that is not `core` or `std`.
# Implementation
This PR adds a new `matches_macro` crate as a private implementation detail of the standard library. This crate is `#![no_core]` so that libcore can depend on it. It contains a `macro_rules` definition with `#[macro_export]`.
libcore and libstd each have a new public `macros` module that contains a `pub use` re-export of the macro. Both the module and the macro are unstable, for now.
The existing private `macros` modules are renamed `prelude_macros`, though their respective source remains in `macros.rs` files.
</del>
</details>
# Motivation
This macro is:
* General-purpose (not domain-specific)
* Simple (the implementation is short)
* Very popular [on crates.io](https://crates.io/crates/matches)
(currently 37th in all-time downloads)
* The two previous points combined make it number one in
[left-pad index](https://twitter.com/bascule/status/1184523027888988160)
score
As such, I feel it is a good candidate for inclusion in the standard library.
In fact I already felt that way five years ago:
https://github.com/rust-lang/rust/pull/14685
(Although the proof of popularity was not as strong at the time.)
Back then, the main concern was that this macro may not be quite
universally-enough useful to belong in the prelude.
# API
Therefore, this PR adds the macro such that using it requires one of:
```
use core::macros::matches;
use std::macros::matches;
```
Like arms of a `match` expression,
the macro supports multiple patterns separated by `|`
and optionally followed by `if` and a guard expression:
```
let foo = 'f';
assert!(matches!(foo, 'A'..='Z' | 'a'..='z'));
let bar = Some(4);
assert!(matches!(bar, Some(x) if x > 2));
```
# Implementation constraints
A combination of reasons make it tricky
for a standard library macro not to be in the prelude.
Currently, all public `macro_rules` macros in the standard library macros
end up “in the prelude” of every crate not through `use std::prelude::v1::*;`
like for other kinds of items,
but through `#[macro_use]` on `extern crate std;`.
(Both are injected by `src/libsyntax_ext/standard_library_imports.rs`.)
`#[macro_use]` seems to import every macro that is available
at the top-level of a crate, even if through a `pub use` re-export.
Therefore, for `matches!` not to be in the prelude, we need it to be
inside of a module rather than at the root of `core` or `std`.
However, the only way to make a `macro_rules` macro public
outside of the crate where it is defined
appears to be `#[macro_export]`.
This exports the macro at the root of the crate
regardless of which module defines it.
See [macro scoping](
https://doc.rust-lang.org/reference/macros-by-example.html#scoping-exporting-and-importing)
in the reference.
Therefore, the macro needs to be defined in a crate
that is not `core` or `std`.
# Implementation
This PR adds a new `matches_macro` crate as a private implementation detail
of the standard library.
This crate is `#![no_core]` so that libcore can depend on it.
It contains a `macro_rules` definition with `#[macro_export]`.
libcore and libstd each have a new public `macros` module
that contains a `pub use` re-export of the macro.
Both the module and the macro are unstable, for now.
The existing private `macros` modules are renamed `prelude_macros`,
though their respective source remains in `macros.rs` files.
make is_power_of_two a const function
This makes `is_power_of_two` a const function by using `&` instead of short-circuiting `&&`; Rust supports bitwise `&` for `bool` and short-circuiting is not required in the existing expression.
I don't think this needs a const-hack label as I don't find the changed code less readable, if anything I prefer that it is clearer that short circuiting is not used.
@oli-obk
Remove leading :: from paths in doc examples
Noted some pre-2018 path syntax in the doc examples, for example:
https://doc.rust-lang.org/std/process/fn.exit.html
```rust
fn main() {
::std::process::exit(match run_app() {
Ok(_) => 0,
...
```
Couldn't find an existing issue on this (then again, "::" makes for an annoying thing to search for) so if there is already something fixing this and/or there's a reason to not fix it, just close this PR.
(Also fixed indentation in the `process::exit()` docs)
Remove unneeded `ref` from docs
Will reduce confusion like in https://users.rust-lang.org/t/help-understanding-the-ref-t-syntax/33779 since match ergonomics means you (almost) never have to say `ref` anymore!
There might be more like this, but I don't have a checkout on my computer right this second and I'm on slow wifi and GitHub search isn't powerful enough and that's my story.
Inline `ptr::null(_mut)` even in debug builds
I think we should treat `ptr::null(_mut)` as a constant. As It may help reduce code size
in debug build.
See godbolt link: https://godbolt.org/z/b9YMtD
properly document panics in div_euclid and rem_euclid
For signed numbers, document that `div_euclid` and `rem_euclid` panic not just when `rhs` is 0, but also when the division overflows.
For unsigned numbers, document that `div_euclid` and `rem_euclid` panic when `rhs` is 0.
Always inline `mem::{size_of,align_of}` in debug builds
Those two are const fn and do not have any arguments. Inlining
helps reducing generated code size in debug builds.
See also #64996.
Move debug_map assertions after check for err
Fixes#65231
We have some assertions in `DebugMap` to catch broken implementations of `Debug` that produce malformed entries. These checks don't make sense if formatting fails partway through. This PR moves those assertions to within the `and_then` closures along with the other formatting logic, so they're only checked if the map hasn't failed to format an entry already.
- Compatible with Emscripten 1.38.46-upstream or later upstream.
- Refactors the Emscripten target spec to share code with other wasm
targets.
- Replaces the old incorrect wasm32 C call ABI with the correct one,
preserving the old one as wasm32_bindgen_compat for wasm-bindgen
compatibility.
- Updates the varargs ABI used by Emscripten and deletes the old one.
- Removes the obsolete wasm32-experimental-emscripten target.
- Uses EMCC_CFLAGS on CI to avoid the timeout problems with #63649.
Add `dyn` to `Any` documentation
I noticed that in documentation to `Any` trait the old trait object syntax is used, which could be confusing for newcomers, since we generally recommend using `dyn Trait` instead of just `Trait`. This PR changes the documentation comment, so that it uses `&dyn Any`, `&mut dyn Any` and `Box<dyn Any>`, correspondingly.
Split non-CAS atomic support off into target_has_atomic_load_store
This PR implements my proposed changes in https://github.com/rust-lang/rust/issues/32976#issuecomment-518542029 by removing `target_has_atomic = "cas"` and splitting `target_has_atomic` into two separate `cfg`s:
* `target_has_atomic = 8/16/32/64/128`: This indicates the largest width that the target can atomically CAS (which implies support for all atomic operations).
* ` target_has_atomic_load_store = 8/16/32/64/128`: This indicates the largest width that the target can support loading or storing atomically (but may not support CAS).
cc #32976
r? @alexcrichton
I noticed that in documentation to `Any` trait the old trait object syntax is used, which could be confusing for newcomers, since we generally recommend using `dyn Trait` instead of just `Trait`. This PR changes the documentation comment, so that it uses `&dyn Any`, `&mut dyn Any` and `Box<dyn Any>`, correspondingly.
Improve docs on some char boolean methods
simple revival of #61794
(also rustfmt on rest of file :)
Documentation for `is_xid_start()` and `is_xid_continue()` couldn't be improved since both methods got remove from this repository
r? @dtolnay
cc @JohnCSimon
Make `Cell::new` method come first in documentation
Methods to create a thing usually comes first in `std` documentation, and `Cell` has been an exception. Also, `T: Copy` specialized methods should not be on top of the page. (This had led me to miss that most of its methods are not bounded by `Copy`...)
rewrite documentation for unimplemented! to clarify use
The current docs for `unimplemented!` seem to miss the point of this macro.
> This can be useful if you are prototyping and are just looking to have your code type-check, or if you're implementing a trait that requires multiple methods, and you're only planning on using one of them.
You could also return a `()` if you just want your code to type-check.
I think `unimplemented!` is useful for when you want your program to exit when it reaches an unimplemented area.
I rewrote the explanation and gave examples of both forms of this macro that I think clarify its use a little better.
