| 1 |
use super::error::{Error, ErrorKind, Result}; |
| 2 |
use core::{cmp, fmt, slice}; |
| 3 |
|
| 4 |
#[cfg(feature = "alloc")] |
| 5 |
pub use alloc::vec::Vec; |
| 6 |
|
| 7 |
#[cfg(feature = "alloc")] |
| 8 |
struct Guard<'a> { |
| 9 |
buf: &'a mut Vec<u8>, |
| 10 |
len: usize, |
| 11 |
} |
| 12 |
|
| 13 |
#[cfg(feature = "alloc")] |
| 14 |
impl Drop for Guard<'_> { |
| 15 |
fn drop(&mut self) { |
| 16 |
unsafe { |
| 17 |
self.buf.set_len(self.len); |
| 18 |
} |
| 19 |
} |
| 20 |
} |
| 21 |
|
| 22 |
// This uses an adaptive system to extend the vector when it fills. We want to |
| 23 |
// avoid paying to allocate and zero a huge chunk of memory if the reader only |
| 24 |
// has 4 bytes while still making large reads if the reader does have a ton |
| 25 |
// of data to return. Simply tacking on an extra DEFAULT_BUF_SIZE space every |
| 26 |
// time is 4,500 times (!) slower than a default reservation size of 32 if the |
| 27 |
// reader has a very small amount of data to return. |
| 28 |
// |
| 29 |
// Because we're extending the buffer with uninitialized data for trusted |
| 30 |
// readers, we need to make sure to truncate that if any of this panics. |
| 31 |
#[cfg(feature = "alloc")] |
| 32 |
fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize> { |
| 33 |
read_to_end_with_reservation(r, buf, |_| 32) |
| 34 |
} |
| 35 |
|
| 36 |
#[cfg(feature = "alloc")] |
| 37 |
fn read_to_end_with_reservation<R, F>( |
| 38 |
r: &mut R, |
| 39 |
buf: &mut Vec<u8>, |
| 40 |
mut reservation_size: F, |
| 41 |
) -> Result<usize> |
| 42 |
where |
| 43 |
R: Read + ?Sized, |
| 44 |
F: FnMut(&R) -> usize, |
| 45 |
{ |
| 46 |
let start_len = buf.len(); |
| 47 |
let mut g = Guard { |
| 48 |
len: buf.len(), |
| 49 |
buf, |
| 50 |
}; |
| 51 |
loop { |
| 52 |
if g.len == g.buf.len() { |
| 53 |
unsafe { |
| 54 |
// FIXME(danielhenrymantilla): #42788 |
| 55 |
// |
| 56 |
// - This creates a (mut) reference to a slice of |
| 57 |
// _uninitialized_ integers, which is **undefined behavior** |
| 58 |
// |
| 59 |
// - Only the standard library gets to soundly "ignore" this, |
| 60 |
// based on its privileged knowledge of unstable rustc |
| 61 |
// internals; |
| 62 |
g.buf.reserve(reservation_size(r)); |
| 63 |
let capacity = g.buf.capacity(); |
| 64 |
g.buf.set_len(capacity); |
| 65 |
r.initializer().initialize(&mut g.buf[g.len..]); |
| 66 |
} |
| 67 |
} |
| 68 |
|
| 69 |
let buf = &mut g.buf[g.len..]; |
| 70 |
match r.read(buf) { |
| 71 |
Ok(0) => return Ok(g.len - start_len), |
| 72 |
Ok(n) => { |
| 73 |
// We can't allow bogus values from read. If it is too large, the returned vec could have its length |
| 74 |
// set past its capacity, or if it overflows the vec could be shortened which could create an invalid |
| 75 |
// string if this is called via read_to_string. |
| 76 |
assert!(n <= buf.len()); |
| 77 |
g.len += n; |
| 78 |
} |
| 79 |
Err(ref e) if e.kind() == ErrorKind::Interrupted => {} |
| 80 |
Err(e) => return Err(e), |
| 81 |
} |
| 82 |
} |
| 83 |
} |
| 84 |
|
| 85 |
/// The `Read` trait allows for reading bytes from a source. |
| 86 |
/// |
| 87 |
/// Implementors of the `Read` trait are called 'readers'. |
| 88 |
/// |
| 89 |
/// Readers are defined by one required method, [`read()`]. Each call to [`read()`] |
| 90 |
/// will attempt to pull bytes from this source into a provided buffer. A |
| 91 |
/// number of other methods are implemented in terms of [`read()`], giving |
| 92 |
/// implementors a number of ways to read bytes while only needing to implement |
| 93 |
/// a single method. |
| 94 |
/// |
| 95 |
/// Readers are intended to be composable with one another. Many implementors |
| 96 |
/// throughout [`std::io`] take and provide types which implement the `Read` |
| 97 |
/// trait. |
| 98 |
/// |
| 99 |
/// Please note that each call to [`read()`] may involve a system call, and |
| 100 |
/// therefore, using something that implements [`BufRead`], such as |
| 101 |
/// [`BufReader`], will be more efficient. |
| 102 |
/// |
| 103 |
/// # Examples |
| 104 |
/// |
| 105 |
/// [`File`]s implement `Read`: |
| 106 |
/// |
| 107 |
/// ```no_run |
| 108 |
/// use std::io; |
| 109 |
/// use std::io::prelude::*; |
| 110 |
/// use std::fs::File; |
| 111 |
/// |
| 112 |
/// fn main() -> io::Result<()> { |
| 113 |
/// let mut f = File::open("foo.txt")?; |
| 114 |
/// let mut buffer = [0; 10]; |
| 115 |
/// |
| 116 |
/// // read up to 10 bytes |
| 117 |
/// f.read(&mut buffer)?; |
| 118 |
/// |
| 119 |
/// let mut buffer = Vec::new(); |
| 120 |
/// // read the whole file |
| 121 |
/// f.read_to_end(&mut buffer)?; |
| 122 |
/// |
| 123 |
/// // read into a String, so that you don't need to do the conversion. |
| 124 |
/// let mut buffer = String::new(); |
| 125 |
/// f.read_to_string(&mut buffer)?; |
| 126 |
/// |
| 127 |
/// // and more! See the other methods for more details. |
| 128 |
/// Ok(()) |
| 129 |
/// } |
| 130 |
/// ``` |
| 131 |
/// |
| 132 |
/// Read from [`&str`] because [`&[u8]`][slice] implements `Read`: |
| 133 |
/// |
| 134 |
/// ```no_run |
| 135 |
/// # use std::io; |
| 136 |
/// use std::io::prelude::*; |
| 137 |
/// |
| 138 |
/// fn main() -> io::Result<()> { |
| 139 |
/// let mut b = "This string will be read".as_bytes(); |
| 140 |
/// let mut buffer = [0; 10]; |
| 141 |
/// |
| 142 |
/// // read up to 10 bytes |
| 143 |
/// b.read(&mut buffer)?; |
| 144 |
/// |
| 145 |
/// // etc... it works exactly as a File does! |
| 146 |
/// Ok(()) |
| 147 |
/// } |
| 148 |
/// ``` |
| 149 |
/// |
| 150 |
/// [`read()`]: Read::read |
| 151 |
/// [`&str`]: prim@str |
| 152 |
/// [`std::io`]: self |
| 153 |
/// [`File`]: crate::fs::File |
| 154 |
/// [slice]: ../../std/primitive.slice.html |
| 155 |
pub trait Read { |
| 156 |
/// Pull some bytes from this source into the specified buffer, returning |
| 157 |
/// how many bytes were read. |
| 158 |
/// |
| 159 |
/// This function does not provide any guarantees about whether it blocks |
| 160 |
/// waiting for data, but if an object needs to block for a read and cannot, |
| 161 |
/// it will typically signal this via an [`Err`] return value. |
| 162 |
/// |
| 163 |
/// If the return value of this method is [`Ok(n)`], then it must be |
| 164 |
/// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates |
| 165 |
/// that the buffer `buf` has been filled in with `n` bytes of data from this |
| 166 |
/// source. If `n` is `0`, then it can indicate one of two scenarios: |
| 167 |
/// |
| 168 |
/// 1. This reader has reached its "end of file" and will likely no longer |
| 169 |
/// be able to produce bytes. Note that this does not mean that the |
| 170 |
/// reader will *always* no longer be able to produce bytes. |
| 171 |
/// 2. The buffer specified was 0 bytes in length. |
| 172 |
/// |
| 173 |
/// It is not an error if the returned value `n` is smaller than the buffer size, |
| 174 |
/// even when the reader is not at the end of the stream yet. |
| 175 |
/// This may happen for example because fewer bytes are actually available right now |
| 176 |
/// (e. g. being close to end-of-file) or because read() was interrupted by a signal. |
| 177 |
/// |
| 178 |
/// No guarantees are provided about the contents of `buf` when this |
| 179 |
/// function is called, implementations cannot rely on any property of the |
| 180 |
/// contents of `buf` being true. It is recommended that *implementations* |
| 181 |
/// only write data to `buf` instead of reading its contents. |
| 182 |
/// |
| 183 |
/// Correspondingly, however, *callers* of this method may not assume any guarantees |
| 184 |
/// about how the implementation uses `buf`. The trait is safe to implement, |
| 185 |
/// so it is possible that the code that's supposed to write to the buffer might also read |
| 186 |
/// from it. It is your responsibility to make sure that `buf` is initialized |
| 187 |
/// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one |
| 188 |
/// obtains via [`MaybeUninit<T>`]) is not safe, and can lead to undefined behavior. |
| 189 |
/// |
| 190 |
/// [`MaybeUninit<T>`]: crate::mem::MaybeUninit |
| 191 |
/// |
| 192 |
/// # Errors |
| 193 |
/// |
| 194 |
/// If this function encounters any form of I/O or other error, an error |
| 195 |
/// variant will be returned. If an error is returned then it must be |
| 196 |
/// guaranteed that no bytes were read. |
| 197 |
/// |
| 198 |
/// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the read |
| 199 |
/// operation should be retried if there is nothing else to do. |
| 200 |
/// |
| 201 |
/// # Examples |
| 202 |
/// |
| 203 |
/// [`File`]s implement `Read`: |
| 204 |
/// |
| 205 |
/// [`Ok(n)`]: Ok |
| 206 |
/// [`File`]: crate::fs::File |
| 207 |
/// |
| 208 |
/// ```no_run |
| 209 |
/// use std::io; |
| 210 |
/// use std::io::prelude::*; |
| 211 |
/// use std::fs::File; |
| 212 |
/// |
| 213 |
/// fn main() -> io::Result<()> { |
| 214 |
/// let mut f = File::open("foo.txt")?; |
| 215 |
/// let mut buffer = [0; 10]; |
| 216 |
/// |
| 217 |
/// // read up to 10 bytes |
| 218 |
/// let n = f.read(&mut buffer[..])?; |
| 219 |
/// |
| 220 |
/// println!("The bytes: {:?}", &buffer[..n]); |
| 221 |
/// Ok(()) |
| 222 |
/// } |
| 223 |
/// ``` |
| 224 |
fn read(&mut self, buf: &mut [u8]) -> Result<usize>; |
| 225 |
|
| 226 |
/// Read all bytes until EOF in this source, placing them into `buf`. |
| 227 |
/// |
| 228 |
/// All bytes read from this source will be appended to the specified buffer |
| 229 |
/// `buf`. This function will continuously call [`read()`] to append more data to |
| 230 |
/// `buf` until [`read()`] returns either [`Ok(0)`] or an error of |
| 231 |
/// non-[`ErrorKind::Interrupted`] kind. |
| 232 |
/// |
| 233 |
/// If successful, this function will return the total number of bytes read. |
| 234 |
/// |
| 235 |
/// # Errors |
| 236 |
/// |
| 237 |
/// If this function encounters an error of the kind |
| 238 |
/// [`ErrorKind::Interrupted`] then the error is ignored and the operation |
| 239 |
/// will continue. |
| 240 |
/// |
| 241 |
/// If any other read error is encountered then this function immediately |
| 242 |
/// returns. Any bytes which have already been read will be appended to |
| 243 |
/// `buf`. |
| 244 |
/// |
| 245 |
/// # Examples |
| 246 |
/// |
| 247 |
/// [`File`]s implement `Read`: |
| 248 |
/// |
| 249 |
/// [`read()`]: Read::read |
| 250 |
/// [`Ok(0)`]: Ok |
| 251 |
/// [`File`]: crate::fs::File |
| 252 |
/// |
| 253 |
/// ```no_run |
| 254 |
/// use std::io; |
| 255 |
/// use std::io::prelude::*; |
| 256 |
/// use std::fs::File; |
| 257 |
/// |
| 258 |
/// fn main() -> io::Result<()> { |
| 259 |
/// let mut f = File::open("foo.txt")?; |
| 260 |
/// let mut buffer = Vec::new(); |
| 261 |
/// |
| 262 |
/// // read the whole file |
| 263 |
/// f.read_to_end(&mut buffer)?; |
| 264 |
/// Ok(()) |
| 265 |
/// } |
| 266 |
/// ``` |
| 267 |
/// |
| 268 |
/// (See also the [`std::fs::read`] convenience function for reading from a |
| 269 |
/// file.) |
| 270 |
/// |
| 271 |
/// [`std::fs::read`]: crate::fs::read |
| 272 |
#[cfg(feature = "alloc")] |
| 273 |
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> { |
| 274 |
read_to_end(self, buf) |
| 275 |
} |
| 276 |
|
| 277 |
/// Determines if this `Read`er can work with buffers of uninitialized |
| 278 |
/// memory. |
| 279 |
/// |
| 280 |
/// The default implementation returns an initializer which will zero |
| 281 |
/// buffers. |
| 282 |
/// |
| 283 |
/// If a `Read`er guarantees that it can work properly with uninitialized |
| 284 |
/// memory, it should call [`Initializer::nop()`]. See the documentation for |
| 285 |
/// [`Initializer`] for details. |
| 286 |
/// |
| 287 |
/// The behavior of this method must be independent of the state of the |
| 288 |
/// `Read`er - the method only takes `&self` so that it can be used through |
| 289 |
/// trait objects. |
| 290 |
/// |
| 291 |
/// # Safety |
| 292 |
/// |
| 293 |
/// This method is unsafe because a `Read`er could otherwise return a |
| 294 |
/// non-zeroing `Initializer` from another `Read` type without an `unsafe` |
| 295 |
/// block. |
| 296 |
#[inline] |
| 297 |
unsafe fn initializer(&self) -> Initializer { |
| 298 |
Initializer::zeroing() |
| 299 |
} |
| 300 |
|
| 301 |
/// Read the exact number of bytes required to fill `buf`. |
| 302 |
/// |
| 303 |
/// This function reads as many bytes as necessary to completely fill the |
| 304 |
/// specified buffer `buf`. |
| 305 |
/// |
| 306 |
/// No guarantees are provided about the contents of `buf` when this |
| 307 |
/// function is called, implementations cannot rely on any property of the |
| 308 |
/// contents of `buf` being true. It is recommended that implementations |
| 309 |
/// only write data to `buf` instead of reading its contents. The |
| 310 |
/// documentation on [`read`] has a more detailed explanation on this |
| 311 |
/// subject. |
| 312 |
/// |
| 313 |
/// # Errors |
| 314 |
/// |
| 315 |
/// If this function encounters an error of the kind |
| 316 |
/// [`ErrorKind::Interrupted`] then the error is ignored and the operation |
| 317 |
/// will continue. |
| 318 |
/// |
| 319 |
/// If this function encounters an "end of file" before completely filling |
| 320 |
/// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`]. |
| 321 |
/// The contents of `buf` are unspecified in this case. |
| 322 |
/// |
| 323 |
/// If any other read error is encountered then this function immediately |
| 324 |
/// returns. The contents of `buf` are unspecified in this case. |
| 325 |
/// |
| 326 |
/// If this function returns an error, it is unspecified how many bytes it |
| 327 |
/// has read, but it will never read more than would be necessary to |
| 328 |
/// completely fill the buffer. |
| 329 |
/// |
| 330 |
/// # Examples |
| 331 |
/// |
| 332 |
/// [`File`]s implement `Read`: |
| 333 |
/// |
| 334 |
/// [`read`]: Read::read |
| 335 |
/// [`File`]: crate::fs::File |
| 336 |
/// |
| 337 |
/// ```no_run |
| 338 |
/// use std::io; |
| 339 |
/// use std::io::prelude::*; |
| 340 |
/// use std::fs::File; |
| 341 |
/// |
| 342 |
/// fn main() -> io::Result<()> { |
| 343 |
/// let mut f = File::open("foo.txt")?; |
| 344 |
/// let mut buffer = [0; 10]; |
| 345 |
/// |
| 346 |
/// // read exactly 10 bytes |
| 347 |
/// f.read_exact(&mut buffer)?; |
| 348 |
/// Ok(()) |
| 349 |
/// } |
| 350 |
/// ``` |
| 351 |
fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> { |
| 352 |
while !buf.is_empty() { |
| 353 |
match self.read(buf) { |
| 354 |
Ok(0) => break, |
| 355 |
Ok(n) => { |
| 356 |
let tmp = buf; |
| 357 |
buf = &mut tmp[n..]; |
| 358 |
} |
| 359 |
Err(ref e) if e.kind() == ErrorKind::Interrupted => {} |
| 360 |
Err(e) => return Err(e), |
| 361 |
} |
| 362 |
} |
| 363 |
if !buf.is_empty() { |
| 364 |
Err(Error::new( |
| 365 |
ErrorKind::UnexpectedEof, |
| 366 |
"failed to fill whole buffer", |
| 367 |
)) |
| 368 |
} else { |
| 369 |
Ok(()) |
| 370 |
} |
| 371 |
} |
| 372 |
|
| 373 |
/// Creates a "by reference" adaptor for this instance of `Read`. |
| 374 |
/// |
| 375 |
/// The returned adaptor also implements `Read` and will simply borrow this |
| 376 |
/// current reader. |
| 377 |
/// |
| 378 |
/// # Examples |
| 379 |
/// |
| 380 |
/// [`File`]s implement `Read`: |
| 381 |
/// |
| 382 |
/// [`File`]: crate::fs::File |
| 383 |
/// |
| 384 |
/// ```no_run |
| 385 |
/// use std::io; |
| 386 |
/// use std::io::Read; |
| 387 |
/// use std::fs::File; |
| 388 |
/// |
| 389 |
/// fn main() -> io::Result<()> { |
| 390 |
/// let mut f = File::open("foo.txt")?; |
| 391 |
/// let mut buffer = Vec::new(); |
| 392 |
/// let mut other_buffer = Vec::new(); |
| 393 |
/// |
| 394 |
/// { |
| 395 |
/// let reference = f.by_ref(); |
| 396 |
/// |
| 397 |
/// // read at most 5 bytes |
| 398 |
/// reference.take(5).read_to_end(&mut buffer)?; |
| 399 |
/// |
| 400 |
/// } // drop our &mut reference so we can use f again |
| 401 |
/// |
| 402 |
/// // original file still usable, read the rest |
| 403 |
/// f.read_to_end(&mut other_buffer)?; |
| 404 |
/// Ok(()) |
| 405 |
/// } |
| 406 |
/// ``` |
| 407 |
fn by_ref(&mut self) -> &mut Self |
| 408 |
where |
| 409 |
Self: Sized, |
| 410 |
{ |
| 411 |
self |
| 412 |
} |
| 413 |
|
| 414 |
/// Transforms this `Read` instance to an [`Iterator`] over its bytes. |
| 415 |
/// |
| 416 |
/// The returned type implements [`Iterator`] where the `Item` is |
| 417 |
/// [`Result`]`<`[`u8`]`, `[`io::Error`]`>`. |
| 418 |
/// The yielded item is [`Ok`] if a byte was successfully read and [`Err`] |
| 419 |
/// otherwise. EOF is mapped to returning [`None`] from this iterator. |
| 420 |
/// |
| 421 |
/// # Examples |
| 422 |
/// |
| 423 |
/// [`File`]s implement `Read`: |
| 424 |
/// |
| 425 |
/// [`File`]: crate::fs::File |
| 426 |
/// [`Result`]: crate::result::Result |
| 427 |
/// [`io::Error`]: self::Error |
| 428 |
/// |
| 429 |
/// ```no_run |
| 430 |
/// use std::io; |
| 431 |
/// use std::io::prelude::*; |
| 432 |
/// use std::fs::File; |
| 433 |
/// |
| 434 |
/// fn main() -> io::Result<()> { |
| 435 |
/// let mut f = File::open("foo.txt")?; |
| 436 |
/// |
| 437 |
/// for byte in f.bytes() { |
| 438 |
/// println!("{}", byte.unwrap()); |
| 439 |
/// } |
| 440 |
/// Ok(()) |
| 441 |
/// } |
| 442 |
/// ``` |
| 443 |
fn bytes(self) -> Bytes<Self> |
| 444 |
where |
| 445 |
Self: Sized, |
| 446 |
{ |
| 447 |
Bytes { inner: self } |
| 448 |
} |
| 449 |
|
| 450 |
/// Creates an adaptor which will chain this stream with another. |
| 451 |
/// |
| 452 |
/// The returned `Read` instance will first read all bytes from this object |
| 453 |
/// until EOF is encountered. Afterwards the output is equivalent to the |
| 454 |
/// output of `next`. |
| 455 |
/// |
| 456 |
/// # Examples |
| 457 |
/// |
| 458 |
/// [`File`]s implement `Read`: |
| 459 |
/// |
| 460 |
/// [`File`]: crate::fs::File |
| 461 |
/// |
| 462 |
/// ```no_run |
| 463 |
/// use std::io; |
| 464 |
/// use std::io::prelude::*; |
| 465 |
/// use std::fs::File; |
| 466 |
/// |
| 467 |
/// fn main() -> io::Result<()> { |
| 468 |
/// let mut f1 = File::open("foo.txt")?; |
| 469 |
/// let mut f2 = File::open("bar.txt")?; |
| 470 |
/// |
| 471 |
/// let mut handle = f1.chain(f2); |
| 472 |
/// let mut buffer = String::new(); |
| 473 |
/// |
| 474 |
/// // read the value into a String. We could use any Read method here, |
| 475 |
/// // this is just one example. |
| 476 |
/// handle.read_to_string(&mut buffer)?; |
| 477 |
/// Ok(()) |
| 478 |
/// } |
| 479 |
/// ``` |
| 480 |
fn chain<R: Read>(self, next: R) -> Chain<Self, R> |
| 481 |
where |
| 482 |
Self: Sized, |
| 483 |
{ |
| 484 |
Chain { |
| 485 |
first: self, |
| 486 |
second: next, |
| 487 |
done_first: false, |
| 488 |
} |
| 489 |
} |
| 490 |
|
| 491 |
/// Creates an adaptor which will read at most `limit` bytes from it. |
| 492 |
/// |
| 493 |
/// This function returns a new instance of `Read` which will read at most |
| 494 |
/// `limit` bytes, after which it will always return EOF ([`Ok(0)`]). Any |
| 495 |
/// read errors will not count towards the number of bytes read and future |
| 496 |
/// calls to [`read()`] may succeed. |
| 497 |
/// |
| 498 |
/// # Examples |
| 499 |
/// |
| 500 |
/// [`File`]s implement `Read`: |
| 501 |
/// |
| 502 |
/// [`File`]: crate::fs::File |
| 503 |
/// [`Ok(0)`]: Ok |
| 504 |
/// [`read()`]: Read::read |
| 505 |
/// |
| 506 |
/// ```no_run |
| 507 |
/// use std::io; |
| 508 |
/// use std::io::prelude::*; |
| 509 |
/// use std::fs::File; |
| 510 |
/// |
| 511 |
/// fn main() -> io::Result<()> { |
| 512 |
/// let mut f = File::open("foo.txt")?; |
| 513 |
/// let mut buffer = [0; 5]; |
| 514 |
/// |
| 515 |
/// // read at most five bytes |
| 516 |
/// let mut handle = f.take(5); |
| 517 |
/// |
| 518 |
/// handle.read(&mut buffer)?; |
| 519 |
/// Ok(()) |
| 520 |
/// } |
| 521 |
/// ``` |
| 522 |
fn take(self, limit: u64) -> Take<Self> |
| 523 |
where |
| 524 |
Self: Sized, |
| 525 |
{ |
| 526 |
Take { inner: self, limit } |
| 527 |
} |
| 528 |
} |
| 529 |
|
| 530 |
/// A type used to conditionally initialize buffers passed to `Read` methods. |
| 531 |
#[derive(Debug)] |
| 532 |
pub struct Initializer(bool); |
| 533 |
|
| 534 |
impl Initializer { |
| 535 |
/// Returns a new `Initializer` which will zero out buffers. |
| 536 |
#[inline] |
| 537 |
pub fn zeroing() -> Initializer { |
| 538 |
Initializer(true) |
| 539 |
} |
| 540 |
|
| 541 |
/// Returns a new `Initializer` which will not zero out buffers. |
| 542 |
/// |
| 543 |
/// # Safety |
| 544 |
/// |
| 545 |
/// This may only be called by `Read`ers which guarantee that they will not |
| 546 |
/// read from buffers passed to `Read` methods, and that the return value of |
| 547 |
/// the method accurately reflects the number of bytes that have been |
| 548 |
/// written to the head of the buffer. |
| 549 |
#[inline] |
| 550 |
pub unsafe fn nop() -> Initializer { |
| 551 |
Initializer(false) |
| 552 |
} |
| 553 |
|
| 554 |
/// Indicates if a buffer should be initialized. |
| 555 |
#[inline] |
| 556 |
pub fn should_initialize(&self) -> bool { |
| 557 |
self.0 |
| 558 |
} |
| 559 |
|
| 560 |
/// Initializes a buffer if necessary. |
| 561 |
#[inline] |
| 562 |
pub fn initialize(&self, buf: &mut [u8]) { |
| 563 |
if self.should_initialize() { |
| 564 |
unsafe { core::ptr::write_bytes(buf.as_mut_ptr(), 0, buf.len()) } |
| 565 |
} |
| 566 |
} |
| 567 |
} |
| 568 |
|
| 569 |
/// A trait for objects which are byte-oriented sinks. |
| 570 |
/// |
| 571 |
/// Implementors of the `Write` trait are sometimes called 'writers'. |
| 572 |
/// |
| 573 |
/// Writers are defined by two required methods, [`write`] and [`flush`]: |
| 574 |
/// |
| 575 |
/// * The [`write`] method will attempt to write some data into the object, |
| 576 |
/// returning how many bytes were successfully written. |
| 577 |
/// |
| 578 |
/// * The [`flush`] method is useful for adaptors and explicit buffers |
| 579 |
/// themselves for ensuring that all buffered data has been pushed out to the |
| 580 |
/// 'true sink'. |
| 581 |
/// |
| 582 |
/// Writers are intended to be composable with one another. Many implementors |
| 583 |
/// throughout [`std::io`] take and provide types which implement the `Write` |
| 584 |
/// trait. |
| 585 |
/// |
| 586 |
/// [`write`]: Write::write |
| 587 |
/// [`flush`]: Write::flush |
| 588 |
/// [`std::io`]: self |
| 589 |
/// |
| 590 |
/// # Examples |
| 591 |
/// |
| 592 |
/// ```no_run |
| 593 |
/// use std::io::prelude::*; |
| 594 |
/// use std::fs::File; |
| 595 |
/// |
| 596 |
/// fn main() -> std::io::Result<()> { |
| 597 |
/// let data = b"some bytes"; |
| 598 |
/// |
| 599 |
/// let mut pos = 0; |
| 600 |
/// let mut buffer = File::create("foo.txt")?; |
| 601 |
/// |
| 602 |
/// while pos < data.len() { |
| 603 |
/// let bytes_written = buffer.write(&data[pos..])?; |
| 604 |
/// pos += bytes_written; |
| 605 |
/// } |
| 606 |
/// Ok(()) |
| 607 |
/// } |
| 608 |
/// ``` |
| 609 |
/// |
| 610 |
/// The trait also provides convenience methods like [`write_all`], which calls |
| 611 |
/// `write` in a loop until its entire input has been written. |
| 612 |
/// |
| 613 |
/// [`write_all`]: Write::write_all |
| 614 |
pub trait Write { |
| 615 |
/// Write a buffer into this writer, returning how many bytes were written. |
| 616 |
/// |
| 617 |
/// This function will attempt to write the entire contents of `buf`, but |
| 618 |
/// the entire write may not succeed, or the write may also generate an |
| 619 |
/// error. A call to `write` represents *at most one* attempt to write to |
| 620 |
/// any wrapped object. |
| 621 |
/// |
| 622 |
/// Calls to `write` are not guaranteed to block waiting for data to be |
| 623 |
/// written, and a write which would otherwise block can be indicated through |
| 624 |
/// an [`Err`] variant. |
| 625 |
/// |
| 626 |
/// If the return value is [`Ok(n)`] then it must be guaranteed that |
| 627 |
/// `n <= buf.len()`. A return value of `0` typically means that the |
| 628 |
/// underlying object is no longer able to accept bytes and will likely not |
| 629 |
/// be able to in the future as well, or that the buffer provided is empty. |
| 630 |
/// |
| 631 |
/// # Errors |
| 632 |
/// |
| 633 |
/// Each call to `write` may generate an I/O error indicating that the |
| 634 |
/// operation could not be completed. If an error is returned then no bytes |
| 635 |
/// in the buffer were written to this writer. |
| 636 |
/// |
| 637 |
/// It is **not** considered an error if the entire buffer could not be |
| 638 |
/// written to this writer. |
| 639 |
/// |
| 640 |
/// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the |
| 641 |
/// write operation should be retried if there is nothing else to do. |
| 642 |
/// |
| 643 |
/// # Examples |
| 644 |
/// |
| 645 |
/// ```no_run |
| 646 |
/// use std::io::prelude::*; |
| 647 |
/// use std::fs::File; |
| 648 |
/// |
| 649 |
/// fn main() -> std::io::Result<()> { |
| 650 |
/// let mut buffer = File::create("foo.txt")?; |
| 651 |
/// |
| 652 |
/// // Writes some prefix of the byte string, not necessarily all of it. |
| 653 |
/// buffer.write(b"some bytes")?; |
| 654 |
/// Ok(()) |
| 655 |
/// } |
| 656 |
/// ``` |
| 657 |
/// |
| 658 |
/// [`Ok(n)`]: Ok |
| 659 |
fn write(&mut self, buf: &[u8]) -> Result<usize>; |
| 660 |
|
| 661 |
/// Flush this output stream, ensuring that all intermediately buffered |
| 662 |
/// contents reach their destination. |
| 663 |
/// |
| 664 |
/// # Errors |
| 665 |
/// |
| 666 |
/// It is considered an error if not all bytes could be written due to |
| 667 |
/// I/O errors or EOF being reached. |
| 668 |
/// |
| 669 |
/// # Examples |
| 670 |
/// |
| 671 |
/// ```no_run |
| 672 |
/// use std::io::prelude::*; |
| 673 |
/// use std::io::BufWriter; |
| 674 |
/// use std::fs::File; |
| 675 |
/// |
| 676 |
/// fn main() -> std::io::Result<()> { |
| 677 |
/// let mut buffer = BufWriter::new(File::create("foo.txt")?); |
| 678 |
/// |
| 679 |
/// buffer.write_all(b"some bytes")?; |
| 680 |
/// buffer.flush()?; |
| 681 |
/// Ok(()) |
| 682 |
/// } |
| 683 |
/// ``` |
| 684 |
fn flush(&mut self) -> Result<()>; |
| 685 |
|
| 686 |
/// Attempts to write an entire buffer into this writer. |
| 687 |
/// |
| 688 |
/// This method will continuously call [`write`] until there is no more data |
| 689 |
/// to be written or an error of non-[`ErrorKind::Interrupted`] kind is |
| 690 |
/// returned. This method will not return until the entire buffer has been |
| 691 |
/// successfully written or such an error occurs. The first error that is |
| 692 |
/// not of [`ErrorKind::Interrupted`] kind generated from this method will be |
| 693 |
/// returned. |
| 694 |
/// |
| 695 |
/// If the buffer contains no data, this will never call [`write`]. |
| 696 |
/// |
| 697 |
/// # Errors |
| 698 |
/// |
| 699 |
/// This function will return the first error of |
| 700 |
/// non-[`ErrorKind::Interrupted`] kind that [`write`] returns. |
| 701 |
/// |
| 702 |
/// [`write`]: Write::write |
| 703 |
/// |
| 704 |
/// # Examples |
| 705 |
/// |
| 706 |
/// ```no_run |
| 707 |
/// use std::io::prelude::*; |
| 708 |
/// use std::fs::File; |
| 709 |
/// |
| 710 |
/// fn main() -> std::io::Result<()> { |
| 711 |
/// let mut buffer = File::create("foo.txt")?; |
| 712 |
/// |
| 713 |
/// buffer.write_all(b"some bytes")?; |
| 714 |
/// Ok(()) |
| 715 |
/// } |
| 716 |
/// ``` |
| 717 |
fn write_all(&mut self, mut buf: &[u8]) -> Result<()> { |
| 718 |
while !buf.is_empty() { |
| 719 |
match self.write(buf) { |
| 720 |
Ok(0) => { |
| 721 |
return Err(Error::new( |
| 722 |
ErrorKind::WriteZero, |
| 723 |
"failed to write whole buffer", |
| 724 |
)); |
| 725 |
} |
| 726 |
Ok(n) => buf = &buf[n..], |
| 727 |
Err(ref e) if e.kind() == ErrorKind::Interrupted => {} |
| 728 |
Err(e) => return Err(e), |
| 729 |
} |
| 730 |
} |
| 731 |
Ok(()) |
| 732 |
} |
| 733 |
/// Writes a formatted string into this writer, returning any error |
| 734 |
/// encountered. |
| 735 |
/// |
| 736 |
/// This method is primarily used to interface with the |
| 737 |
/// [`format_args!()`] macro, but it is rare that this should |
| 738 |
/// explicitly be called. The [`write!()`] macro should be favored to |
| 739 |
/// invoke this method instead. |
| 740 |
/// |
| 741 |
/// This function internally uses the [`write_all`] method on |
| 742 |
/// this trait and hence will continuously write data so long as no errors |
| 743 |
/// are received. This also means that partial writes are not indicated in |
| 744 |
/// this signature. |
| 745 |
/// |
| 746 |
/// [`write_all`]: Write::write_all |
| 747 |
/// |
| 748 |
/// # Errors |
| 749 |
/// |
| 750 |
/// This function will return any I/O error reported while formatting. |
| 751 |
/// |
| 752 |
/// # Examples |
| 753 |
/// |
| 754 |
/// ```no_run |
| 755 |
/// use std::io::prelude::*; |
| 756 |
/// use std::fs::File; |
| 757 |
/// |
| 758 |
/// fn main() -> std::io::Result<()> { |
| 759 |
/// let mut buffer = File::create("foo.txt")?; |
| 760 |
/// |
| 761 |
/// // this call |
| 762 |
/// write!(buffer, "{:.*}", 2, 1.234567)?; |
| 763 |
/// // turns into this: |
| 764 |
/// buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?; |
| 765 |
/// Ok(()) |
| 766 |
/// } |
| 767 |
/// ``` |
| 768 |
fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> { |
| 769 |
// Create a shim which translates a Write to a fmt::Write and saves |
| 770 |
// off I/O errors. instead of discarding them |
| 771 |
struct Adaptor<'a, T: ?Sized + 'a> { |
| 772 |
inner: &'a mut T, |
| 773 |
error: Result<()>, |
| 774 |
} |
| 775 |
|
| 776 |
impl<T: Write + ?Sized> fmt::Write for Adaptor<'_, T> { |
| 777 |
fn write_str(&mut self, s: &str) -> fmt::Result { |
| 778 |
match self.inner.write_all(s.as_bytes()) { |
| 779 |
Ok(()) => Ok(()), |
| 780 |
Err(e) => { |
| 781 |
self.error = Err(e); |
| 782 |
Err(fmt::Error) |
| 783 |
} |
| 784 |
} |
| 785 |
} |
| 786 |
} |
| 787 |
|
| 788 |
let mut output = Adaptor { |
| 789 |
inner: self, |
| 790 |
error: Ok(()), |
| 791 |
}; |
| 792 |
match fmt::write(&mut output, fmt) { |
| 793 |
Ok(()) => Ok(()), |
| 794 |
Err(..) => { |
| 795 |
// check if the error came from the underlying `Write` or not |
| 796 |
if output.error.is_err() { |
| 797 |
output.error |
| 798 |
} else { |
| 799 |
Err(Error::new(ErrorKind::Other, "formatter error")) |
| 800 |
} |
| 801 |
} |
| 802 |
} |
| 803 |
} |
| 804 |
|
| 805 |
/// Creates a "by reference" adaptor for this instance of `Write`. |
| 806 |
/// |
| 807 |
/// The returned adaptor also implements `Write` and will simply borrow this |
| 808 |
/// current writer. |
| 809 |
/// |
| 810 |
/// # Examples |
| 811 |
/// |
| 812 |
/// ```no_run |
| 813 |
/// use std::io::Write; |
| 814 |
/// use std::fs::File; |
| 815 |
/// |
| 816 |
/// fn main() -> std::io::Result<()> { |
| 817 |
/// let mut buffer = File::create("foo.txt")?; |
| 818 |
/// |
| 819 |
/// let reference = buffer.by_ref(); |
| 820 |
/// |
| 821 |
/// // we can use reference just like our original buffer |
| 822 |
/// reference.write_all(b"some bytes")?; |
| 823 |
/// Ok(()) |
| 824 |
/// } |
| 825 |
/// ``` |
| 826 |
fn by_ref(&mut self) -> &mut Self |
| 827 |
where |
| 828 |
Self: Sized, |
| 829 |
{ |
| 830 |
self |
| 831 |
} |
| 832 |
} |
| 833 |
|
| 834 |
/// The `Seek` trait provides a cursor which can be moved within a stream of |
| 835 |
/// bytes. |
| 836 |
/// |
| 837 |
/// The stream typically has a fixed size, allowing seeking relative to either |
| 838 |
/// end or the current offset. |
| 839 |
/// |
| 840 |
/// # Examples |
| 841 |
/// |
| 842 |
/// [`File`]s implement `Seek`: |
| 843 |
/// |
| 844 |
/// [`File`]: crate::fs::File |
| 845 |
/// |
| 846 |
/// ```no_run |
| 847 |
/// use std::io; |
| 848 |
/// use std::io::prelude::*; |
| 849 |
/// use std::fs::File; |
| 850 |
/// use std::io::SeekFrom; |
| 851 |
/// |
| 852 |
/// fn main() -> io::Result<()> { |
| 853 |
/// let mut f = File::open("foo.txt")?; |
| 854 |
/// |
| 855 |
/// // move the cursor 42 bytes from the start of the file |
| 856 |
/// f.seek(SeekFrom::Start(42))?; |
| 857 |
/// Ok(()) |
| 858 |
/// } |
| 859 |
/// ``` |
| 860 |
pub trait Seek { |
| 861 |
/// Seek to an offset, in bytes, in a stream. |
| 862 |
/// |
| 863 |
/// A seek beyond the end of a stream is allowed, but behavior is defined |
| 864 |
/// by the implementation. |
| 865 |
/// |
| 866 |
/// If the seek operation completed successfully, |
| 867 |
/// this method returns the new position from the start of the stream. |
| 868 |
/// That position can be used later with [`SeekFrom::Start`]. |
| 869 |
/// |
| 870 |
/// # Errors |
| 871 |
/// |
| 872 |
/// Seeking to a negative offset is considered an error. |
| 873 |
fn seek(&mut self, pos: SeekFrom) -> Result<u64>; |
| 874 |
} |
| 875 |
|
| 876 |
/// Enumeration of possible methods to seek within an I/O object. |
| 877 |
/// |
| 878 |
/// It is used by the [`Seek`] trait. |
| 879 |
#[derive(Copy, PartialEq, Eq, Clone, Debug)] |
| 880 |
pub enum SeekFrom { |
| 881 |
/// Sets the offset to the provided number of bytes. |
| 882 |
Start(u64), |
| 883 |
|
| 884 |
/// Sets the offset to the size of this object plus the specified number of |
| 885 |
/// bytes. |
| 886 |
/// |
| 887 |
/// It is possible to seek beyond the end of an object, but it's an error to |
| 888 |
/// seek before byte 0. |
| 889 |
End(i64), |
| 890 |
|
| 891 |
/// Sets the offset to the current position plus the specified number of |
| 892 |
/// bytes. |
| 893 |
/// |
| 894 |
/// It is possible to seek beyond the end of an object, but it's an error to |
| 895 |
/// seek before byte 0. |
| 896 |
Current(i64), |
| 897 |
} |
| 898 |
|
| 899 |
/// An iterator over `u8` values of a reader. |
| 900 |
/// |
| 901 |
/// This struct is generally created by calling [`bytes`] on a reader. |
| 902 |
/// Please see the documentation of [`bytes`] for more details. |
| 903 |
/// |
| 904 |
/// [`bytes`]: Read::bytes |
| 905 |
#[derive(Debug)] |
| 906 |
pub struct Bytes<R> { |
| 907 |
inner: R, |
| 908 |
} |
| 909 |
|
| 910 |
impl<R: Read> Iterator for Bytes<R> { |
| 911 |
type Item = Result<u8>; |
| 912 |
|
| 913 |
fn next(&mut self) -> Option<Result<u8>> { |
| 914 |
let mut byte = 0; |
| 915 |
loop { |
| 916 |
return match self.inner.read(slice::from_mut(&mut byte)) { |
| 917 |
Ok(0) => None, |
| 918 |
Ok(..) => Some(Ok(byte)), |
| 919 |
Err(ref e) if e.kind() == ErrorKind::Interrupted => continue, |
| 920 |
Err(e) => Some(Err(e)), |
| 921 |
}; |
| 922 |
} |
| 923 |
} |
| 924 |
} |
| 925 |
|
| 926 |
/// A `BufRead` is a type of `Read`er which has an internal buffer, allowing it |
| 927 |
/// to perform extra ways of reading. |
| 928 |
/// |
| 929 |
/// For example, reading line-by-line is inefficient without using a buffer, so |
| 930 |
/// if you want to read by line, you'll need `BufRead`, which includes a |
| 931 |
/// [`read_line`] method as well as a [`lines`] iterator. |
| 932 |
/// |
| 933 |
/// # Examples |
| 934 |
/// |
| 935 |
/// A locked standard input implements `BufRead`: |
| 936 |
/// |
| 937 |
/// ```no_run |
| 938 |
/// use std::io; |
| 939 |
/// use std::io::prelude::*; |
| 940 |
/// |
| 941 |
/// let stdin = io::stdin(); |
| 942 |
/// for line in stdin.lock().lines() { |
| 943 |
/// println!("{}", line.unwrap()); |
| 944 |
/// } |
| 945 |
/// ``` |
| 946 |
/// |
| 947 |
/// If you have something that implements [`Read`], you can use the [`BufReader` |
| 948 |
/// type][`BufReader`] to turn it into a `BufRead`. |
| 949 |
/// |
| 950 |
/// For example, [`File`] implements [`Read`], but not `BufRead`. |
| 951 |
/// [`BufReader`] to the rescue! |
| 952 |
/// |
| 953 |
/// [`File`]: crate::fs::File |
| 954 |
/// [`read_line`]: BufRead::read_line |
| 955 |
/// [`lines`]: BufRead::lines |
| 956 |
/// |
| 957 |
/// ```no_run |
| 958 |
/// use std::io::{self, BufReader}; |
| 959 |
/// use std::io::prelude::*; |
| 960 |
/// use std::fs::File; |
| 961 |
/// |
| 962 |
/// fn main() -> io::Result<()> { |
| 963 |
/// let f = File::open("foo.txt")?; |
| 964 |
/// let f = BufReader::new(f); |
| 965 |
/// |
| 966 |
/// for line in f.lines() { |
| 967 |
/// println!("{}", line.unwrap()); |
| 968 |
/// } |
| 969 |
/// |
| 970 |
/// Ok(()) |
| 971 |
/// } |
| 972 |
/// ``` |
| 973 |
pub trait BufRead: Read { |
| 974 |
/// Returns the contents of the internal buffer, filling it with more data |
| 975 |
/// from the inner reader if it is empty. |
| 976 |
/// |
| 977 |
/// This function is a lower-level call. It needs to be paired with the |
| 978 |
/// [`consume`] method to function properly. When calling this |
| 979 |
/// method, none of the contents will be "read" in the sense that later |
| 980 |
/// calling `read` may return the same contents. As such, [`consume`] must |
| 981 |
/// be called with the number of bytes that are consumed from this buffer to |
| 982 |
/// ensure that the bytes are never returned twice. |
| 983 |
/// |
| 984 |
/// [`consume`]: BufRead::consume |
| 985 |
/// |
| 986 |
/// An empty buffer returned indicates that the stream has reached EOF. |
| 987 |
/// |
| 988 |
/// # Errors |
| 989 |
/// |
| 990 |
/// This function will return an I/O error if the underlying reader was |
| 991 |
/// read, but returned an error. |
| 992 |
/// |
| 993 |
/// # Examples |
| 994 |
/// |
| 995 |
/// A locked standard input implements `BufRead`: |
| 996 |
/// |
| 997 |
/// ```no_run |
| 998 |
/// use std::io; |
| 999 |
/// use std::io::prelude::*; |
| 1000 |
/// |
| 1001 |
/// let stdin = io::stdin(); |
| 1002 |
/// let mut stdin = stdin.lock(); |
| 1003 |
/// |
| 1004 |
/// let buffer = stdin.fill_buf().unwrap(); |
| 1005 |
/// |
| 1006 |
/// // work with buffer |
| 1007 |
/// println!("{:?}", buffer); |
| 1008 |
/// |
| 1009 |
/// // ensure the bytes we worked with aren't returned again later |
| 1010 |
/// let length = buffer.len(); |
| 1011 |
/// stdin.consume(length); |
| 1012 |
/// ``` |
| 1013 |
fn fill_buf(&mut self) -> Result<&[u8]>; |
| 1014 |
|
| 1015 |
/// Tells this buffer that `amt` bytes have been consumed from the buffer, |
| 1016 |
/// so they should no longer be returned in calls to `read`. |
| 1017 |
/// |
| 1018 |
/// This function is a lower-level call. It needs to be paired with the |
| 1019 |
/// [`fill_buf`] method to function properly. This function does |
| 1020 |
/// not perform any I/O, it simply informs this object that some amount of |
| 1021 |
/// its buffer, returned from [`fill_buf`], has been consumed and should |
| 1022 |
/// no longer be returned. As such, this function may do odd things if |
| 1023 |
/// [`fill_buf`] isn't called before calling it. |
| 1024 |
/// |
| 1025 |
/// The `amt` must be `<=` the number of bytes in the buffer returned by |
| 1026 |
/// [`fill_buf`]. |
| 1027 |
/// |
| 1028 |
/// # Examples |
| 1029 |
/// |
| 1030 |
/// Since `consume()` is meant to be used with [`fill_buf`], |
| 1031 |
/// that method's example includes an example of `consume()`. |
| 1032 |
/// |
| 1033 |
/// [`fill_buf`]: BufRead::fill_buf |
| 1034 |
fn consume(&mut self, amt: usize); |
| 1035 |
} |
| 1036 |
|
| 1037 |
/// Adaptor to chain together two readers. |
| 1038 |
/// |
| 1039 |
/// This struct is generally created by calling [`chain`] on a reader. |
| 1040 |
/// Please see the documentation of [`chain`] for more details. |
| 1041 |
/// |
| 1042 |
/// [`chain`]: Read::chain |
| 1043 |
pub struct Chain<T, U> { |
| 1044 |
first: T, |
| 1045 |
second: U, |
| 1046 |
done_first: bool, |
| 1047 |
} |
| 1048 |
|
| 1049 |
impl<T, U> Chain<T, U> { |
| 1050 |
/// Consumes the `Chain`, returning the wrapped readers. |
| 1051 |
/// |
| 1052 |
/// # Examples |
| 1053 |
/// |
| 1054 |
/// ```no_run |
| 1055 |
/// use std::io; |
| 1056 |
/// use std::io::prelude::*; |
| 1057 |
/// use std::fs::File; |
| 1058 |
/// |
| 1059 |
/// fn main() -> io::Result<()> { |
| 1060 |
/// let mut foo_file = File::open("foo.txt")?; |
| 1061 |
/// let mut bar_file = File::open("bar.txt")?; |
| 1062 |
/// |
| 1063 |
/// let chain = foo_file.chain(bar_file); |
| 1064 |
/// let (foo_file, bar_file) = chain.into_inner(); |
| 1065 |
/// Ok(()) |
| 1066 |
/// } |
| 1067 |
/// ``` |
| 1068 |
pub fn into_inner(self) -> (T, U) { |
| 1069 |
(self.first, self.second) |
| 1070 |
} |
| 1071 |
|
| 1072 |
/// Gets references to the underlying readers in this `Chain`. |
| 1073 |
/// |
| 1074 |
/// # Examples |
| 1075 |
/// |
| 1076 |
/// ```no_run |
| 1077 |
/// use std::io; |
| 1078 |
/// use std::io::prelude::*; |
| 1079 |
/// use std::fs::File; |
| 1080 |
/// |
| 1081 |
/// fn main() -> io::Result<()> { |
| 1082 |
/// let mut foo_file = File::open("foo.txt")?; |
| 1083 |
/// let mut bar_file = File::open("bar.txt")?; |
| 1084 |
/// |
| 1085 |
/// let chain = foo_file.chain(bar_file); |
| 1086 |
/// let (foo_file, bar_file) = chain.get_ref(); |
| 1087 |
/// Ok(()) |
| 1088 |
/// } |
| 1089 |
/// ``` |
| 1090 |
pub fn get_ref(&self) -> (&T, &U) { |
| 1091 |
(&self.first, &self.second) |
| 1092 |
} |
| 1093 |
|
| 1094 |
/// Gets mutable references to the underlying readers in this `Chain`. |
| 1095 |
/// |
| 1096 |
/// Care should be taken to avoid modifying the internal I/O state of the |
| 1097 |
/// underlying readers as doing so may corrupt the internal state of this |
| 1098 |
/// `Chain`. |
| 1099 |
/// |
| 1100 |
/// # Examples |
| 1101 |
/// |
| 1102 |
/// ```no_run |
| 1103 |
/// use std::io; |
| 1104 |
/// use std::io::prelude::*; |
| 1105 |
/// use std::fs::File; |
| 1106 |
/// |
| 1107 |
/// fn main() -> io::Result<()> { |
| 1108 |
/// let mut foo_file = File::open("foo.txt")?; |
| 1109 |
/// let mut bar_file = File::open("bar.txt")?; |
| 1110 |
/// |
| 1111 |
/// let mut chain = foo_file.chain(bar_file); |
| 1112 |
/// let (foo_file, bar_file) = chain.get_mut(); |
| 1113 |
/// Ok(()) |
| 1114 |
/// } |
| 1115 |
/// ``` |
| 1116 |
pub fn get_mut(&mut self) -> (&mut T, &mut U) { |
| 1117 |
(&mut self.first, &mut self.second) |
| 1118 |
} |
| 1119 |
} |
| 1120 |
|
| 1121 |
impl<T: fmt::Debug, U: fmt::Debug> fmt::Debug for Chain<T, U> { |
| 1122 |
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 1123 |
f.debug_struct("Chain") |
| 1124 |
.field("t", &self.first) |
| 1125 |
.field("u", &self.second) |
| 1126 |
.finish() |
| 1127 |
} |
| 1128 |
} |
| 1129 |
|
| 1130 |
impl<T: Read, U: Read> Read for Chain<T, U> { |
| 1131 |
fn read(&mut self, buf: &mut [u8]) -> Result<usize> { |
| 1132 |
if !self.done_first { |
| 1133 |
match self.first.read(buf)? { |
| 1134 |
0 if !buf.is_empty() => self.done_first = true, |
| 1135 |
n => return Ok(n), |
| 1136 |
} |
| 1137 |
} |
| 1138 |
self.second.read(buf) |
| 1139 |
} |
| 1140 |
|
| 1141 |
unsafe fn initializer(&self) -> Initializer { |
| 1142 |
let initializer = self.first.initializer(); |
| 1143 |
if initializer.should_initialize() { |
| 1144 |
initializer |
| 1145 |
} else { |
| 1146 |
self.second.initializer() |
| 1147 |
} |
| 1148 |
} |
| 1149 |
} |
| 1150 |
|
| 1151 |
impl<T: BufRead, U: BufRead> BufRead for Chain<T, U> { |
| 1152 |
fn fill_buf(&mut self) -> Result<&[u8]> { |
| 1153 |
if !self.done_first { |
| 1154 |
match self.first.fill_buf()? { |
| 1155 |
buf if buf.is_empty() => { |
| 1156 |
self.done_first = true; |
| 1157 |
} |
| 1158 |
buf => return Ok(buf), |
| 1159 |
} |
| 1160 |
} |
| 1161 |
self.second.fill_buf() |
| 1162 |
} |
| 1163 |
|
| 1164 |
fn consume(&mut self, amt: usize) { |
| 1165 |
if !self.done_first { |
| 1166 |
self.first.consume(amt) |
| 1167 |
} else { |
| 1168 |
self.second.consume(amt) |
| 1169 |
} |
| 1170 |
} |
| 1171 |
} |
| 1172 |
|
| 1173 |
/// Reader adaptor which limits the bytes read from an underlying reader. |
| 1174 |
/// |
| 1175 |
/// This struct is generally created by calling [`take`] on a reader. |
| 1176 |
/// Please see the documentation of [`take`] for more details. |
| 1177 |
/// |
| 1178 |
/// [`take`]: Read::take |
| 1179 |
#[derive(Debug)] |
| 1180 |
pub struct Take<T> { |
| 1181 |
inner: T, |
| 1182 |
limit: u64, |
| 1183 |
} |
| 1184 |
|
| 1185 |
impl<T> Take<T> { |
| 1186 |
/// Returns the number of bytes that can be read before this instance will |
| 1187 |
/// return EOF. |
| 1188 |
/// |
| 1189 |
/// # Note |
| 1190 |
/// |
| 1191 |
/// This instance may reach `EOF` after reading fewer bytes than indicated by |
| 1192 |
/// this method if the underlying [`Read`] instance reaches EOF. |
| 1193 |
/// |
| 1194 |
/// # Examples |
| 1195 |
/// |
| 1196 |
/// ```no_run |
| 1197 |
/// use std::io; |
| 1198 |
/// use std::io::prelude::*; |
| 1199 |
/// use std::fs::File; |
| 1200 |
/// |
| 1201 |
/// fn main() -> io::Result<()> { |
| 1202 |
/// let f = File::open("foo.txt")?; |
| 1203 |
/// |
| 1204 |
/// // read at most five bytes |
| 1205 |
/// let handle = f.take(5); |
| 1206 |
/// |
| 1207 |
/// println!("limit: {}", handle.limit()); |
| 1208 |
/// Ok(()) |
| 1209 |
/// } |
| 1210 |
/// ``` |
| 1211 |
pub fn limit(&self) -> u64 { |
| 1212 |
self.limit |
| 1213 |
} |
| 1214 |
|
| 1215 |
/// Sets the number of bytes that can be read before this instance will |
| 1216 |
/// return EOF. This is the same as constructing a new `Take` instance, so |
| 1217 |
/// the amount of bytes read and the previous limit value don't matter when |
| 1218 |
/// calling this method. |
| 1219 |
/// |
| 1220 |
/// # Examples |
| 1221 |
/// |
| 1222 |
/// ```no_run |
| 1223 |
/// use std::io; |
| 1224 |
/// use std::io::prelude::*; |
| 1225 |
/// use std::fs::File; |
| 1226 |
/// |
| 1227 |
/// fn main() -> io::Result<()> { |
| 1228 |
/// let f = File::open("foo.txt")?; |
| 1229 |
/// |
| 1230 |
/// // read at most five bytes |
| 1231 |
/// let mut handle = f.take(5); |
| 1232 |
/// handle.set_limit(10); |
| 1233 |
/// |
| 1234 |
/// assert_eq!(handle.limit(), 10); |
| 1235 |
/// Ok(()) |
| 1236 |
/// } |
| 1237 |
/// ``` |
| 1238 |
pub fn set_limit(&mut self, limit: u64) { |
| 1239 |
self.limit = limit; |
| 1240 |
} |
| 1241 |
|
| 1242 |
/// Consumes the `Take`, returning the wrapped reader. |
| 1243 |
/// |
| 1244 |
/// # Examples |
| 1245 |
/// |
| 1246 |
/// ```no_run |
| 1247 |
/// use std::io; |
| 1248 |
/// use std::io::prelude::*; |
| 1249 |
/// use std::fs::File; |
| 1250 |
/// |
| 1251 |
/// fn main() -> io::Result<()> { |
| 1252 |
/// let mut file = File::open("foo.txt")?; |
| 1253 |
/// |
| 1254 |
/// let mut buffer = [0; 5]; |
| 1255 |
/// let mut handle = file.take(5); |
| 1256 |
/// handle.read(&mut buffer)?; |
| 1257 |
/// |
| 1258 |
/// let file = handle.into_inner(); |
| 1259 |
/// Ok(()) |
| 1260 |
/// } |
| 1261 |
/// ``` |
| 1262 |
pub fn into_inner(self) -> T { |
| 1263 |
self.inner |
| 1264 |
} |
| 1265 |
|
| 1266 |
/// Gets a reference to the underlying reader. |
| 1267 |
/// |
| 1268 |
/// # Examples |
| 1269 |
/// |
| 1270 |
/// ```no_run |
| 1271 |
/// use std::io; |
| 1272 |
/// use std::io::prelude::*; |
| 1273 |
/// use std::fs::File; |
| 1274 |
/// |
| 1275 |
/// fn main() -> io::Result<()> { |
| 1276 |
/// let mut file = File::open("foo.txt")?; |
| 1277 |
/// |
| 1278 |
/// let mut buffer = [0; 5]; |
| 1279 |
/// let mut handle = file.take(5); |
| 1280 |
/// handle.read(&mut buffer)?; |
| 1281 |
/// |
| 1282 |
/// let file = handle.get_ref(); |
| 1283 |
/// Ok(()) |
| 1284 |
/// } |
| 1285 |
/// ``` |
| 1286 |
pub fn get_ref(&self) -> &T { |
| 1287 |
&self.inner |
| 1288 |
} |
| 1289 |
|
| 1290 |
/// Gets a mutable reference to the underlying reader. |
| 1291 |
/// |
| 1292 |
/// Care should be taken to avoid modifying the internal I/O state of the |
| 1293 |
/// underlying reader as doing so may corrupt the internal limit of this |
| 1294 |
/// `Take`. |
| 1295 |
/// |
| 1296 |
/// # Examples |
| 1297 |
/// |
| 1298 |
/// ```no_run |
| 1299 |
/// use std::io; |
| 1300 |
/// use std::io::prelude::*; |
| 1301 |
/// use std::fs::File; |
| 1302 |
/// |
| 1303 |
/// fn main() -> io::Result<()> { |
| 1304 |
/// let mut file = File::open("foo.txt")?; |
| 1305 |
/// |
| 1306 |
/// let mut buffer = [0; 5]; |
| 1307 |
/// let mut handle = file.take(5); |
| 1308 |
/// handle.read(&mut buffer)?; |
| 1309 |
/// |
| 1310 |
/// let file = handle.get_mut(); |
| 1311 |
/// Ok(()) |
| 1312 |
/// } |
| 1313 |
/// ``` |
| 1314 |
pub fn get_mut(&mut self) -> &mut T { |
| 1315 |
&mut self.inner |
| 1316 |
} |
| 1317 |
} |
| 1318 |
|
| 1319 |
impl<T: Read> Read for Take<T> { |
| 1320 |
fn read(&mut self, buf: &mut [u8]) -> Result<usize> { |
| 1321 |
// Don't call into inner reader at all at EOF because it may still block |
| 1322 |
if self.limit == 0 { |
| 1323 |
return Ok(0); |
| 1324 |
} |
| 1325 |
|
| 1326 |
let max = cmp::min(buf.len() as u64, self.limit) as usize; |
| 1327 |
let n = self.inner.read(&mut buf[..max])?; |
| 1328 |
self.limit -= n as u64; |
| 1329 |
Ok(n) |
| 1330 |
} |
| 1331 |
|
| 1332 |
unsafe fn initializer(&self) -> Initializer { |
| 1333 |
self.inner.initializer() |
| 1334 |
} |
| 1335 |
|
| 1336 |
#[cfg(feature = "alloc")] |
| 1337 |
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> { |
| 1338 |
// Pass in a reservation_size closure that respects the current value |
| 1339 |
// of limit for each read. If we hit the read limit, this prevents the |
| 1340 |
// final zero-byte read from allocating again. |
| 1341 |
read_to_end_with_reservation(self, buf, |self_| cmp::min(self_.limit, 32) as usize) |
| 1342 |
} |
| 1343 |
} |
| 1344 |
|
| 1345 |
impl<T: BufRead> BufRead for Take<T> { |
| 1346 |
fn fill_buf(&mut self) -> Result<&[u8]> { |
| 1347 |
// Don't call into inner reader at all at EOF because it may still block |
| 1348 |
if self.limit == 0 { |
| 1349 |
return Ok(&[]); |
| 1350 |
} |
| 1351 |
|
| 1352 |
let buf = self.inner.fill_buf()?; |
| 1353 |
let cap = cmp::min(buf.len() as u64, self.limit) as usize; |
| 1354 |
Ok(&buf[..cap]) |
| 1355 |
} |
| 1356 |
|
| 1357 |
fn consume(&mut self, amt: usize) { |
| 1358 |
// Don't let callers reset the limit by passing an overlarge value |
| 1359 |
let amt = cmp::min(amt as u64, self.limit) as usize; |
| 1360 |
self.limit -= amt as u64; |
| 1361 |
self.inner.consume(amt); |
| 1362 |
} |
| 1363 |
} |