Add a method to query the capacity of a BufWriter and BufReader
Besides the obvious of retrieving the parameter used to construct the writer, this method allows consumers to control the number of `flush` calls during write operations. For `BufReader` it gives an upper bound on the returned buffer in `fill_buf` which might influence the allocation behaviour of a consumer.
Some types of Write instances have a semantic meaning associated with
writing an empty buffer, such as sending an empty packet. This works
when calling `write` directly, and supplying an empty buffer. However,
calling `write_all` on an empty buffer will simply never call `write`,
because `write_all` assumes it has no work to do.
Document this behavior, to help prospective users of
datagram-packet-style Write instances.
`description` has been documented as soft-deprecated since 1.27.0 (17
months ago). There is no longer any reason to call it or implement it.
This commit:
- adds #[rustc_deprecated(since = "1.41.0")] to Error::description;
- moves description (and cause, which is also deprecated) below the
source and backtrace methods in the Error trait;
- reduces documentation of description and cause to take up much less
vertical real estate in rustdocs, while preserving the example that
shows how to render errors without needing to call description;
- removes the description function of all *currently unstable* Error
impls in the standard library;
- marks #[allow(deprecated)] the description function of all *stable*
Error impls in the standard library;
- replaces miscellaneous uses of description in example code and the
compiler.
This commit implements the `write_vectored` method of the `LineWriter`
type. First discovered in bytecodealliance/wasmtime#629 the
`write_vectored` method of `Stdout` bottoms out here but only ends up
writing the first buffer due to the default implementation of
`write_vectored`.
Like `BufWriter`, however, `LineWriter` can have a non-default
implementation of `write_vectored` which tries to preserve the
vectored-ness as much as possible. Namely we can have a vectored write
for everything before the newline and everything after the newline if
all the stars align well.
Also like `BufWriter`, though, special care is taken to ensure that
whenever bytes are written we're sure to signal success since that
represents a "commit" of writing bytes.
This commit applies rustfmt with rust-lang/rust's default settings to
files in src/libstd *that are not involved in any currently open PR* to
minimize merge conflicts. THe list of files involved in open PRs was
determined by querying GitHub's GraphQL API with this script:
https://gist.github.com/dtolnay/aa9c34993dc051a4f344d1b10e4487e8
With the list of files from the script in outstanding_files, the
relevant commands were:
$ find src/libstd -name '*.rs' \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ rg libstd outstanding_files | xargs git checkout --
Repeating this process several months apart should get us coverage of
most of the rest of libstd.
To confirm no funny business:
$ git checkout $THIS_COMMIT^
$ git show --pretty= --name-only $THIS_COMMIT \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ git diff $THIS_COMMIT # there should be no difference
One of the links in the docs was being rendered as a literal
open-bracket followed by a single quote, instead of being transformed
into a link. Fix it to match the link earlier in the same paragraph.
Prevously the `read_to_end` implementation for `std::io::Take` used its
own `limit` as a cap on the `reservation_size`. However, that could
still result in an over-allocation like this:
1. Call `reader.take(5).read_to_end(&mut vec)`.
2. `read_to_end_with_reservation` reserves 5 bytes and calls `read`.
3. `read` writes 5 bytes.
4. `read_to_end_with_reservation` reserves 5 bytes and calls `read`.
5. `read` writes 0 bytes.
6. The read loop ends with `vec` having length 5 and capacity 10.
The reservation of 5 bytes was correct for the read at step 2 but
unnecessary for the read at step 4. By that second read, `Take::limit`
is 0, but the `read_to_end_with_reservation` loop is still using the
same `reservation_size` it started with.
Solve this by having `read_to_end_with_reservation` take a closure,
which lets it get a fresh `reservation_size` for each read. This is an
implementation detail which doesn't affect any public API.
simplify std::io::Write::write rustdoc
The std::io::Write::write method currensly suggests consumers guaranteed
that `0 <= n <= buf.len()`, for `Ok(n)`, however `n` is of type `usize`
causing the compiler to emit a warning:
```
warning: comparison is useless due to type limits
--> lib.rs:6:18
|
6 | Ok(n) => 0 <= n && n <= output.len(),
| ^^^^^^
|
= note: #[warn(unused_comparisons)] on by default
```
This PR removes the suggestion to check `0 <= n` since it is moot.
r? @steveklabnik
The std::io::Write::write method currensly suggests consumers guaranteed
that `0 <= n <= buf.len()`, for `Ok(n)`, however `n` is of type `usize`
causing the compiler to emit a warning:
```
warning: comparison is useless due to type limits
--> lib.rs:6:18
|
6 | Ok(n) => 0 <= n && n <= output.len(),
| ^^^^^^
|
= note: #[warn(unused_comparisons)] on by default
```
This PR removes the suggestion to check `0 <= n` since it is moot.
r? @steveklabnik
Fix intra-doc link resolution failure on re-exporting libstd
Currently, re-exporting libstd items as below will [occur a lot of failures](https://gist.github.com/taiki-e/e33e0e8631ef47f65a74a3b69f456366).
```rust
pub use std::*;
```
Until the underlying issue (#56922) fixed, we can fix that so they don't propagate to downstream crates.
Related: https://github.com/rust-lang/rust/pull/56941 (That PR fixed failures that occur when re-exporting from libcore to libstd.)
r? @QuietMisdreavus
