* Factor out the nigh-identical bodies of `_print` and `_eprint` to a helper
function `print_to` (I was sorely tempted to call it `_doprnt`).
* Update the issue number for the unstable `eprint` feature.
* Add entries to the "unstable book" for `eprint` and `eprint_internal`.
* Style corrections to the documentation.
* Since the switch to pulldown-cmark reference links need a blank line
before the URLs.
* Reference link references are not case sensitive.
* Doc comments need to be indented uniformly otherwise rustdoc gets
confused.
Add helpful hint in io docs about how ? is not allowed in main()
This is my effort to help alleviate the confusion caused by the error message:
```rust
error[E0277]: the trait bound `(): std::ops::Carrier` is not satisfied
--> hello_world.rs:72:5
|
72 | io::stdin().read_line(&mut d_input)?;
| ------------------------------------
| |
| the trait `std::ops::Carrier` is not implemented for `()`
| in this macro invocation
|
= note: required by `std::ops::Carrier::from_error`
error: aborting due to previous error
```
This has been discussed at length in https://github.com/rust-lang/rust/issues/35946, but I figured it would be helpful to mention in the docs.
Reading user input is one of the first things beginners will look up in the docs, so my thinking was they'd see this warning here and not have to deal with the [tricky error message](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html).
If you think this isn't the right place to put this in the docs, that's understandable, I'm open to suggestions for putting it elsewhere or removing it entirely.
Document Cursor::new position is 0
... even if contained `Vec` is not empty. E. g. for
```
let v = vec![10u8, 20];
let mut c = io::Cursor::new(v);
c.write_all(b"aaaa").unwrap();
println!("{:?}", c.into_inner());
```
result is
```
[97, 97, 97, 97]
```
and not
```
[10, 20, 97, 97, 97, 97]
```
Prior to this commit, most of the `BufRead` examples used `StdinLock` to
demonstrate how certain `BufRead` methods worked. Using `StdinLock` is
not ideal since:
* Relying on run-time data means we can't show concrete examples of how
these methods work up-front. The user is required to run them in order
to see how they behave.
* If the user tries to run an example in the playpen, it won't work
because the playpen doesn't support user input to stdin.
... even if contained `Vec` is not empty. E. g. for
```
let v = vec![10u8, 20];
let mut c = io::Cursor::new(v);
c.write_all(b"aaaa").unwrap();
println!("{:?}", c.into_inner());
```
result is
```
[97, 97, 97, 97]
```
and not
```
[10, 20, 97, 97, 97, 97]
```
std: Fix partial writes in LineWriter
Previously the `LineWriter` could successfully write some bytes but then fail to
report that it has done so. Additionally, an erroneous flush after a successful
write was permanently ignored. This commit fixes these two issues by (a)
maintaining a `need_flush` flag to indicate whether a flush should be the first
operation in `LineWriter::write` and (b) avoiding returning an error once some
bytes have been successfully written.
Closes#37807
Based on the discussion in https://github.com/rust-lang/rust/pull/37573,
it is likely better to keep this limited to std::io, instead of
modifying a function which users expect to be a memcpy.
Ultimately copy_from_slice is being a bottleneck, not io::Cursor::read.
It might be worthwhile to move the check here, so more places can
benefit from it.
During benchmarking, I found that one of my programs spent between 5 and
10 percent of the time doing memmoves. Ultimately I tracked these down
to single-byte slices being copied with a memcopy in io::Cursor::read().
Doing a manual copy if only one byte is requested can speed things up
significantly. For my program, this reduced the running time by 20%.
Why special-case only a single byte, and not a "small" slice in general?
I tried doing this for slices of at most 64 bytes and of at most 8
bytes. In both cases my test program was significantly slower.
Previously the `LineWriter` could successfully write some bytes but then fail to
report that it has done so. Additionally, an erroneous flush after a successful
write was permanently ignored. This commit fixes these two issues by (a)
maintaining a `need_flush` flag to indicate whether a flush should be the first
operation in `LineWriter::write` and (b) avoiding returning an error once some
bytes have been successfully written.
Closes#37807
