Add functions to replace BufReader's reader

[Morganamilo]

This allows the buffer of the BufRead to be used between multiple readers.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[the8472]

This

• requires &mut
• discards the buffer
• then replaces the reader

At which point you can just do mem::replace(&mut existing_buf_reader, BufReader::new(new_reader))

[Morganamilo]

That allocates a new buffer on the heap instead of reusing the allocation.

[the8472]

Which likely isn't significant compared to the syscall overhead of opening the file.

And I also find discarding the buffer and the old reader dubious since it can lead to data being dropped. This can be important for streams (e.g. TCP) where the data can only be obtained once.

[Morganamilo]

My specific use case is I have a few tens of thousand files that are a line based format that I'm parsing in a loop.

I'd like my parser to not make the same allocation over and over when it could easily use the same buffer. I don't expect this to be useful on streams but it seemed useful here and was counter intuitive that I couldn't here.

[workingjubilee]

Do you have a benchmark suggesting this is a substantial win?

[Mark-Simulacrum]

We already allow replacing the underlying reader (*BufReader::get_mut() = new_reader), so the only new functionality here is (a) allowing replacing with a different type (map) and (b) discarding the current buffer before doing so.

Discarding the buffer does not seem particularly useful to me for the known use case. Presumably, you want to exhaust the reader anyway, not accidentally drop contents. I would probably assert!(buf_reader.buffer().is_empty()) rather than call discard on it.

I think (a) is also not yet well-motivated, it feels like an even more rare use case. Box<dyn Read> / &mut dyn Read as the stored type are probably also fine for 95% of BufReaders given the intentionally rare calls to the inner type.