core: allow messages in unimplemented!() macro
This makes `unimplemented!()` match `unreachable!()`, allowing a message and possible formatting to be provided to better explain what and/or why something is not implemented.
I've used this myself in hyper for a while, include the type and method name, to better help while prototyping new modules, like `unimplemented!("Conn::poll_complete")`, or `unimplemented!("Conn::poll; state={:?}", state)`.
By having the left and right strings above and below on the same line it helps spot the difference between the two. E.g.
thread 'tests::test_safe_filename' panicked at 'assertion failed: `(left == right)`
left: `"-aandb--S123.html"`
right: `"-aandb-S123.html"`',
When the strings are both on the same line it take a lot longer to spot the difference. It is a small change but the small time savings add up with repetition. This helps Rust be an excellent language to write tests in.
This change reduces duplication by linking the documentation for
`writeln!` to `write!`. It also restructures the `write!` documentation
to read in a more logical manner.
Updates #29329, #29381
Previously, `assert_eq!(left, right,)` (respectively, `assert_ne!(left,
right,)`; note the trailing comma) would result in a confusing "requires
at least a format string argument" error. In reality, a format string is
optional, but the trailing comma puts us into the "match a token tree of
zero or more tokens" branch of the macro (in order to support the
optional format string), and passing the empty token tree into
`format_args!` results in the confusing error. If instead we match a
token tree of one or more tokens, we get a much more sensible
"unexpected end of macro invocation" error.
While we're here, fix up a stray space before a comma in the match
guards.
Resolves#39369.
Document convention for using both fmt::Write and io::Write
Using a trait's methods (like `Write::write_fmt` as used in `writeln!` and other macros) requires importing that trait directly (not just the module containing it). Both `fmt::Write` and `io::Write` provide compatible `Write::write_fmt` methods, and code can use `writeln!` and other macros on both an object implementing `fmt::Write` (such as a `String`) and an object implementing `io::Write` (such as `Stderr`). However, importing both `Write` traits produces an error due to the name conflict.
The convention I've seen renames both of them on import, to `FmtWrite` and `IoWrite` respectively. Document that convention in the Rust documentation for `write!` and `writeln!`, with examples.
Copyediting on documentation for write! and writeln!
Fix various sentence fragments, missing articles, and other grammatical issues in the documentation for write! and writeln!.
Also fix the links (and link names) for common return types.
(Noticed when preparing https://github.com/rust-lang/rust/pull/37472 ; posted separately to avoid mixing the new documentation with copyedits to existing documentation.)
Fix various sentence fragments, missing articles, and other grammatical
issues in the documentation for write! and writeln!.
Also fix the links (and link names) for common return types.
Removes the `STATUSES` static which duplicates truth from the pattern
match in `collect_lang_features`.
Fixes existing duplicates by renaming:
- never_type{,_impls} on `impl`s on `!`
- concat_idents{,_macro} on `macro_rules! concat_idents`
Fixes#37013.
A few categories:
* Links into compiler docs were just all removed as we're not generating
compiler docs.
* Move up one more level to forcibly go to std docs to fix inlined documentation
across the facade crates.
This commit is the standard API stabilization commit for the 1.6 release cycle.
The list of issues and APIs below have all been through their cycle-long FCP and
the libs team decisions are listed below
Stabilized APIs
* `Read::read_exact`
* `ErrorKind::UnexpectedEof` (renamed from `UnexpectedEOF`)
* libcore -- this was a bit of a nuanced stabilization, the crate itself is now
marked as `#[stable]` and the methods appearing via traits for primitives like
`char` and `str` are now also marked as stable. Note that the extension traits
themeselves are marked as unstable as they're imported via the prelude. The
`try!` macro was also moved from the standard library into libcore to have the
same interface. Otherwise the functions all have copied stability from the
standard library now.
* The `#![no_std]` attribute
* `fs::DirBuilder`
* `fs::DirBuilder::new`
* `fs::DirBuilder::recursive`
* `fs::DirBuilder::create`
* `os::unix::fs::DirBuilderExt`
* `os::unix::fs::DirBuilderExt::mode`
* `vec::Drain`
* `vec::Vec::drain`
* `string::Drain`
* `string::String::drain`
* `vec_deque::Drain`
* `vec_deque::VecDeque::drain`
* `collections::hash_map::Drain`
* `collections::hash_map::HashMap::drain`
* `collections::hash_set::Drain`
* `collections::hash_set::HashSet::drain`
* `collections::binary_heap::Drain`
* `collections::binary_heap::BinaryHeap::drain`
* `Vec::extend_from_slice` (renamed from `push_all`)
* `Mutex::get_mut`
* `Mutex::into_inner`
* `RwLock::get_mut`
* `RwLock::into_inner`
* `Iterator::min_by_key` (renamed from `min_by`)
* `Iterator::max_by_key` (renamed from `max_by`)
Deprecated APIs
* `ErrorKind::UnexpectedEOF` (renamed to `UnexpectedEof`)
* `OsString::from_bytes`
* `OsStr::to_cstring`
* `OsStr::to_bytes`
* `fs::walk_dir` and `fs::WalkDir`
* `path::Components::peek`
* `slice::bytes::MutableByteVector`
* `slice::bytes::copy_memory`
* `Vec::push_all` (renamed to `extend_from_slice`)
* `Duration::span`
* `IpAddr`
* `SocketAddr::ip`
* `Read::tee`
* `io::Tee`
* `Write::broadcast`
* `io::Broadcast`
* `Iterator::min_by` (renamed to `min_by_key`)
* `Iterator::max_by` (renamed to `max_by_key`)
* `net::lookup_addr`
New APIs (still unstable)
* `<[T]>::sort_by_key` (added to mirror `min_by_key`)
Closes#27585Closes#27704Closes#27707Closes#27710Closes#27711Closes#27727Closes#27740Closes#27744Closes#27799Closes#27801
cc #27801 (doesn't close as `Chars` is still unstable)
Closes#28968
Did this alphabetically, so I didn't see [how `std` was doing things](https://dxr.mozilla.org/rust/source/src/libstd/lib.rs#215) till I was nearly finished. If you prefer to add crate-level-whitelists like std instead of test-level, I can rebase with that strategy.
A number of these commits can probably be dropped as the crates don't have much to test, and are deprecated. Let me know which if any to drop! (can also squash after review if desired)
r? @steveklabnik
`format_args!` doesn't support none Sized types so we should just pass it the references to `left_val` and `right_val`.
The following works:
```rust
assert!([1, 2, 3][..] == vec![1, 2, 3][..])
```
So I would expect this to as well:
```rust
assert_eq!([1, 2, 3][..], vec![1, 2, 3][..])
```
But it fails with "error: the trait `core::marker::Sized` is not implemented for the type `[_]` [E0277]"
I don't know if this change will have any nasty side effects I don't understand.
format_args! doesn't support none Sized types so we should just pass it the references to left_val and right_val.
This fixes `assert_eq!([1, 2, 3][..], vec![1, 2, 3][..])` for example.
After submitting #28031, I ran a [script](https://gist.github.com/durka/a5243440697c780f669b) on the rest of src/ and found some anomalies. In this PR are the fixes that I thought were obvious (but I might be wrong!). The others I've submitted in issue #28037.
This commit shards the broad `core` feature of the libcore library into finer
grained features. This split groups together similar APIs and enables tracking
each API separately, giving a better sense of where each feature is within the
stabilization process.
A few minor APIs were deprecated along the way:
* Iterator::reverse_in_place
* marker::NoCopy
An automated script was run against the `.rs` and `.md` files,
subsituting every occurrence of `task` with `thread`. In the `.rs`
files, only the texts in the comment blocks were affected.
This means passing in e.g. a `Vec<u8>` or `String` will work as
intended, rather than deref-ing to `&mut [u8]` or `&mut str`.
[breaking-change]
Closes#23768
This means passing in e.g. a `Vec<u8>` or `String` will work as
intended, rather than deref-ing to `&mut [u8]` or `&mut str`.
[breaking-change]
Closes#23768
This is a deprecated attribute that is slated for removal, and it also affects
all implementors of the trait. This commit removes the attribute and fixes up
implementors accordingly. The primary implementation which was lost was the
ability to compare `&[T]` and `Vec<T>` (in that order).
This change also modifies the `assert_eq!` macro to not consider both directions
of equality, only the one given in the left/right forms to the macro. This
modification is motivated due to the fact that `&[T] == Vec<T>` no longer
compiles, causing hundreds of errors in unit tests in the standard library (and
likely throughout the community as well).
Closes#19470
[breaking-change]
This commit cleans out a large amount of deprecated APIs from the standard
library and some of the facade crates as well, updating all users in the
compiler and in tests as it goes along.
This is a deprecated attribute that is slated for removal, and it also affects
all implementors of the trait. This commit removes the attribute and fixes up
implementors accordingly. The primary implementation which was lost was the
ability to compare `&[T]` and `Vec<T>` (in that order).
This change also modifies the `assert_eq!` macro to not consider both directions
of equality, only the one given in the left/right forms to the macro. This
modification is motivated due to the fact that `&[T] == Vec<T>` no longer
compiles, causing hundreds of errors in unit tests in the standard library (and
likely throughout the community as well).
cc #19470
[breaking-change]
This removes the FromError trait, since it can now be expressed using
the new convert::Into trait. All implementations of FromError<E> where
changed to From<E>, and `try!` was changed to use From::from instead.
Because this removes FromError, it is a breaking change, but fixing it
simply requires changing the words `FromError` to `From`, and
`from_error` to `from`.
[breaking-change]
This commit removes the reexports of `old_io` traits as well as `old_path` types
and traits from the prelude. This functionality is now all deprecated and needs
to be removed to make way for other functionality like `Seek` in the `std::io`
module (currently reexported as `NewSeek` in the io prelude).
Closes#23377Closes#23378
This commit is an implementation of [RFC 563][rfc] which adds a new
`cfg(debug_assertions)` directive which is specially recognized and calculated
by the compiler. The flag is turned off at any optimization level greater than 1
and may also be explicitly controlled through the `-C debug-assertions`
flag.
[rfc]: https://github.com/rust-lang/rfcs/pull/563
The `debug_assert!` and `debug_assert_eq!` macros now respect this instead of
the `ndebug` variable and `ndebug` no longer holds any meaning to the standard
library.
Code which was previously relying on `not(ndebug)` to gate expensive code should
be updated to rely on `debug_assertions` instead.
Closes#22492
[breaking-change]
This commit is an implementation of [RFC 563][rfc] which adds a new
`cfg(debug_assertions)` directive which is specially recognized and calculated
by the compiler. The flag is turned off at any optimization level greater than 1
and may also be explicitly controlled through the `-C debug-assertions`
flag.
[rfc]: https://github.com/rust-lang/rfcs/pull/563
The `debug_assert!` and `debug_assert_eq!` macros now respect this instead of
the `ndebug` variable and `ndebug` no longer holds any meaning to the standard
library.
Code which was previously relying on `not(ndebug)` to gate expensive code should
be updated to rely on `debug_assertions` instead.
Closes#22492
[breaking-change]
I searched for times when we were hiding functions with # in the documentation,
and fixed them to not use it unless neccesary.
I also made random improvements whenever I changed something. For example,
I changed Example to Examples, for consistency.
Fixes#13423
fmt::Show is for debugging, and can and should be implemented for
all public types. This trait is used with `{:?}` syntax. There still
exists #[derive(Show)].
fmt::String is for types that faithfully be represented as a String.
Because of this, there is no way to derive fmt::String, all
implementations must be purposeful. It is used by the default format
syntax, `{}`.
This will break most instances of `{}`, since that now requires the type
to impl fmt::String. In most cases, replacing `{}` with `{:?}` is the
correct fix. Types that were being printed specifically for users should
receive a fmt::String implementation to fix this.
Part of #20013
[breaking-change]
Many of libstd's macros are now re-exported from libcore and libcollections.
Their libstd definitions have moved to a macros_stage0 module and can disappear
after the next snapshot.
Where the two crates had already diverged, I took the libstd versions as
they're generally newer and better-tested. See e.g. d3c831b, which was a fix to
libstd's assert_eq!() that didn't make it into libcore's.
Fixes#16806.
Yes, really. That definition wouldn't work anyway.
This also fixes repeated entries for `debug_assert!` from libcore docs. Maybe we should warn such macro definitions in the first place?
followed by a semicolon.
This allows code like `vec![1i, 2, 3].len();` to work.
This breaks code that uses macros as statements without putting
semicolons after them, such as:
fn main() {
...
assert!(a == b)
assert!(c == d)
println(...);
}
It also breaks code that uses macros as items without semicolons:
local_data_key!(foo)
fn main() {
println("hello world")
}
Add semicolons to fix this code. Those two examples can be fixed as
follows:
fn main() {
...
assert!(a == b);
assert!(c == d);
println(...);
}
local_data_key!(foo);
fn main() {
println("hello world")
}
RFC #378.
Closes#18635.
[breaking-change]
This commit applies the stabilization of std::fmt as outlined in [RFC 380][rfc].
There are a number of breaking changes as a part of this commit which will need
to be handled to migrated old code:
* A number of formatting traits have been removed: String, Bool, Char, Unsigned,
Signed, and Float. It is recommended to instead use Show wherever possible or
to use adaptor structs to implement other methods of formatting.
* The format specifier for Boolean has changed from `t` to `b`.
* The enum `FormatError` has been renamed to `Error` as well as becoming a unit
struct instead of an enum. The `WriteError` variant no longer exists.
* The `format_args_method!` macro has been removed with no replacement. Alter
code to use the `format_args!` macro instead.
* The public fields of a `Formatter` have become read-only with no replacement.
Use a new formatting string to alter the formatting flags in combination with
the `write!` macro. The fields can be accessed through accessor methods on the
`Formatter` structure.
Other than these breaking changes, the contents of std::fmt should now also all
contain stability markers. Most of them are still #[unstable] or #[experimental]
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0380-stabilize-std-fmt.md
[breaking-change]
Closes#18904
https://github.com/rust-lang/rfcs/pull/221
The current terminology of "task failure" often causes problems when
writing or speaking about code. You often want to talk about the
possibility of an operation that returns a Result "failing", but cannot
because of the ambiguity with task failure. Instead, you have to speak
of "the failing case" or "when the operation does not succeed" or other
circumlocutions.
Likewise, we use a "Failure" header in rustdoc to describe when
operations may fail the task, but it would often be helpful to separate
out a section describing the "Err-producing" case.
We have been steadily moving away from task failure and toward Result as
an error-handling mechanism, so we should optimize our terminology
accordingly: Result-producing functions should be easy to describe.
To update your code, rename any call to `fail!` to `panic!` instead.
Assuming you have not created your own macro named `panic!`, this
will work on UNIX based systems:
grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g'
You can of course also do this by hand.
[breaking-change]
