From 65bbd1aa2d0c9aca8347ba5b963e2f8658ab2d42 Mon Sep 17 00:00:00 2001 From: Jonathan Brouwer Date: Tue, 28 Jan 2025 08:38:17 +0100 Subject: [PATCH 1/2] Fix example of from_reader not applying buffering when it should --- src/de.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/de.rs b/src/de.rs index 5b64138d8..b1f4b84c3 100644 --- a/src/de.rs +++ b/src/de.rs @@ -2568,6 +2568,7 @@ where /// /// use std::error::Error; /// use std::net::{TcpListener, TcpStream}; +/// use std::io::BufReader; /// /// #[derive(Deserialize, Debug)] /// struct User { @@ -2576,7 +2577,8 @@ where /// } /// /// fn read_user_from_stream(tcp_stream: TcpStream) -> Result> { -/// let mut de = serde_json::Deserializer::from_reader(tcp_stream); +/// let buf_tcp_stream = BufReader::new(tcp_stream); +/// let mut de = serde_json::Deserializer::from_reader(buf_tcp_stream); /// let u = User::deserialize(&mut de)?; /// /// Ok(u) From 8c2d8004b2b873772dbeadd5ad3f96a185d329df Mon Sep 17 00:00:00 2001 From: Jonathan Brouwer Date: Tue, 28 Jan 2025 08:41:52 +0100 Subject: [PATCH 2/2] Add more warnings to apply buffering on docs of affected functions --- src/de.rs | 6 ++++++ src/read.rs | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/src/de.rs b/src/de.rs index b1f4b84c3..ec9c74664 100644 --- a/src/de.rs +++ b/src/de.rs @@ -45,11 +45,17 @@ where /// Create a JSON deserializer from one of the possible serde_json input /// sources. /// + /// When reading from a source against which short reads are not efficient, such + /// as a [`File`], you will want to apply your own buffering because serde_json + /// will not buffer the input. See [`std::io::BufReader`]. + /// /// Typically it is more convenient to use one of these methods instead: /// /// - Deserializer::from_str /// - Deserializer::from_slice /// - Deserializer::from_reader + /// + /// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html pub fn new(read: R) -> Self { Deserializer { read, diff --git a/src/read.rs b/src/read.rs index b4128467b..ef97493be 100644 --- a/src/read.rs +++ b/src/read.rs @@ -191,6 +191,12 @@ where R: io::Read, { /// Create a JSON input source to read from a std::io input stream. + /// + /// When reading from a source against which short reads are not efficient, such + /// as a [`File`], you will want to apply your own buffering because serde_json + /// will not buffer the input. See [`std::io::BufReader`]. + /// + /// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html pub fn new(reader: R) -> Self { IoRead { iter: LineColIterator::new(reader.bytes()),