//! Alternative implementation of many functions found in [`std::io`],
//! but suitable for blocking IO over networks.
//!
//! The main reason for this crate is the handling of [`ErrorKind`]`::Interrupted` in
//! `std::io`.
//! Except for [`std::io::Read::read`] and [`std::io::Write::write`], almost all functions
//! will ignore interrupts and just retry.
//!
//! This crate provides alternative implementations using a similar API but allow for interrupts
//! whithout losing any content.
//!
//! Most functions are based on buffered readers instead of plain readers to ensure that no
//! content is lost on retry.
//!
//! [`std::io`]: https://doc.rust-lang.org/nightly/std/io/index.html
//! [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
//! [`std::io::Read::read`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html#tymethod.read
//! [`std::io::Write::write`]:
//!     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write

extern crate memchr;
pub extern crate buf_redux;

use std::io;

mod impls;
mod adapt;
mod iter;
mod utf8;

pub mod mock;

pub use buf_redux as buf_redux_reexport;
use buf_redux_reexport as br;

pub use adapt::{Retry, Take, Repeat};
pub use iter::{Bytes, Split, Collect};
pub use utf8::Utf8Reader;


/// Alternative to `std::io::BufReader`
pub type BufReader<R> = br::BufReader<R, br::DefaultReadStrategy, br::DefaultMoveStrategy>;

/// Copies the entire content of a buffered reader into a writer.
///
/// Similar to [`std::io::copy`], this function will continuously read data from reader and
/// then write it into writer in a streaming fashion until reader returns EOF.
///
/// Errors
/// ======
/// This function will return an error immediately if any call to [`fill_buf`] or
/// [`write`] returns any kind of error.
/// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
///
/// All bytes consumed from the buffered reader will be written to the specified writer and vice
/// versa.
/// It is guaranteed that no data is lost in case of error.
///
/// Differences to `std::io::copy`
/// ==============================
/// - Does not retry on [`ErrorKind`]`::Interrupted`.
/// - Uses [`BufRead`] instead of [`Read`].
/// - Does not return the number of bytes that are copied.
///
/// Advantages
/// ----------
/// - Allows for reliable retry on errors.
/// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
/// - Avoids double buffering if the source already implements [`BufRead`].
/// - Allows different buffer sizes by using [`BufReader::with_capacity`].
///
/// Disadvantages
/// -------------
/// The fact that it does not return the number of bytes copied stems from the fact that it cannot
/// return this information in case of error.
/// This would go against the goal of allowing reliable retry.
///
/// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
/// [`write`]: ./trait.Write.html#tymethod.write
/// [`Read`]: ./trait.Read.html
/// [`BufRead`]: ./trait.BufRead.html
/// [`BufReader::with_capacity`]: ./buf_redux_reexport/struct.BufReader.html#method.with_capacity
/// [`std::io::copy`]: https://doc.rust-lang.org/nightly/std/io/fn.copy.html
/// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> io::Result<()>
    where R: BufRead,
          W: Write
{
    loop {
        let written = {
            let buf = try!(reader.fill_buf());
            if buf.len() == 0 {
                return Ok(());
            }
            try!(writer.write(buf))
        };
        if written == 0 {
            return Err(io::Error::new(io::ErrorKind::WriteZero, "no bytes could be written"));
        }
        reader.consume(written);
    }
}

/// Copies the content of a buffered reader into a writer until a delimiter is reached.
///
/// This function will continuously read data from reader and then write it into writer in a
/// streaming fashion until until the delimiter or EOF is found.
///
/// Errors
/// ======
/// This function will return an error immediately if any call to [`fill_buf`] or
/// [`write`] returns any kind of error.
/// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
///
/// All bytes consumed from the buffered reader will be written to the specified writer and vice
/// versa.
/// It is guaranteed that no data is lost in case of error.
///
/// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
/// [`write`]: ./trait.Write.html#tymethod.write
/// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
pub fn copy_until<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W, delim: u8) -> io::Result<()>
    where R: BufRead,
          W: Write
{
    loop {
        let (found, used) = {
            let buf = try!(reader.fill_buf());
            if buf.len() == 0 {
                return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                                          "Stream did not contain the delimiter"));
            }
            match memchr::memchr(delim, buf) {
                Some(i) => {
                    let written = try!(writer.write(&buf[..i + 1]));
                    (written == i + 1, written)
                }
                None => (false, try!(writer.write(buf))),
            }
        };
        if used == 0 {
            return Err(io::Error::new(io::ErrorKind::WriteZero, "no bytes could be written"));
        }
        reader.consume(used);
        if found {
            return Ok(());
        }
    }
}

/// Base trait for generic stream operations
///
/// Most of these function are generalizations of functions already present in [`std::io::Read`]
/// and/or [`std::io::Write`]:
///
/// - `by_ref` ← [`std::io::Read::by_ref`] and [`std::io::Write::by_ref`]
/// - `take` ← [`std::io::Read::take`]
///
/// New methods without counterpart in `std::io`
///
/// - `retry`
///
/// [`std::io::Read`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
/// [`std::io::Write`]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html
/// [`std::io::Read::by_ref`]:
///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.by_ref
/// [`std::io::Read::take`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.take
/// [`std::io::Write::by_ref`]:
///     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#method.by_ref
pub trait Stream {
    /// Creates a "by reference" adaptor for this stream.
    ///
    /// This method is equivalent to [`std::io::Read::by_ref`] and [`std::io::Write::by_ref`]
    ///
    /// [`std::io::Read::by_ref`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.by_ref
    /// [`std::io::Write::by_ref`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#method.by_ref
    #[inline]
    fn by_ref(&mut self) -> &mut Self where Self: Sized {
        self
    }

    /// Creates an adapter which will limits the total number of bytes of this stream.
    ///
    /// This function returns a new stream instance of which will read write at most
    /// `limit` bytes, after which it will always return EOF (`Ok(0)`). Any
    /// errors will not count towards the number of bytes read and future
    /// calls to `read` or `write` may succeed.
    ///
    /// Differences to `std::io::Read::take`
    /// ====================================
    /// This function is equivalent to [`std::io::Read::take`] except that the returned
    /// adapter implements [`BufReadGrow`] and [`std::io::Write`] if possible.
    ///
    /// [`BufReadGrow`]: ./trait.BufReadGrow.html
    /// [`std::io::Read::take`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.take
    /// [`std::io::Write`]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html
    #[inline]
    fn take(self, limit: u64) -> Take<Self>
        where Self: Sized
    {
        Take::new(self, limit)
    }

    /// Transforms this stream into a stream that automatically retries on interrupts
    ///
    /// The returned adapter will behave identically to the original stream, except that it retries
    /// all operations automatically if an error of kind
    /// [`ErrorKind`]`::Interrupted` occurs.
    ///
    /// Note
    /// ----
    /// Methods that are already expected to retry are forwarded directly to the underlying reader.
    ///
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn retry(self) -> Retry<Self>
        where Self: Sized
    {
        Retry::new(self)
    }
}

impl<R: ?Sized> Stream for R { }

/// Alternative to `std::io::Read`
///
/// This trait is automatically implemented for all types that implement [`std::io::Read`].
///
/// Diffrerences to `std::io::Read`
/// ===============================
/// Methods that are just wrappers around the equivalent methods of `std::io::Read`:
///
/// - `read`
/// - `chain`
///
/// New methods that have no counterpart in `std::io::Read`:
///
/// - `buffer`
/// - `repeat`
///
/// Functions that were removed or moved to a different place,
/// because they cannot be implemented with providing all desired guarantees:
///
/// - `read_to_end` → [`BufRead::read_to_end`]
/// - `read_to_string` → [`Utf8Reader::read_to_string`]
/// - `read_exact` → [`BufRead::read_exact`]
/// - `bytes` → [`BufRead::bytes`]
/// - `chars` → [`Utf8Reader::chars`]
///
/// [`BufRead::read_to_end`]: trait.BufRead.html#method.read_to_end
/// [`BufRead::read_exact`]: trait.BufRead.html#method.read_exact
/// [`BufRead::bytes`]: trait.BufRead.html#method.bytes
/// [`Utf8Reader::read_to_string`]: struct.Utf8Reader.html#method.read_to_string
/// [`Utf8Reader::chars`]: struct.Utf8Reader.html#method.chars
/// [`std::io::Read`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
pub trait Read : Stream {
    /// Pull some bytes from this source into the specified buffer, returning
    /// how many bytes were read.
    ///
    /// This methode is equivalent to [`std::io::Read::read`].
    ///
    /// [`std::io::Read::read`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#tymethod.read
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;

    /// Creates an adaptor which will chain this stream with another.
    ///
    /// This method is equivalent to [`std::io::Read::chain`].
    ///
    /// [`std::io::Read::chain`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.chain
    fn chain<R: io::Read>(self, next: R) -> io::Chain<Self, R> where Self: Sized;

    /// Creates a buffered reader with default capacity and default strategies
    ///
    /// Please see the documentation of [`BufReader`] for more details
    ///
    /// [`BufReader`]: ./buf_redux_reexport/struct.BufReader.html
    #[inline]
    fn buffer(self) -> BufReader<Self>
        where Self: Sized
    {
        BufReader::new(self)
    }

    /// Transforms this reader into a reader that automatically restarts from the beginning after
    /// EOF is reached
    #[inline]
    fn repeat(self) -> Repeat<Self>
        where Self: Sized
    {
        Repeat::new(self)
    }
}

impl<R: ?Sized+io::Read> Read for R {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        io::Read::read(self, buf)
    }

    #[inline]
    fn chain<N: io::Read>(self, next: N) -> io::Chain<Self, N>
        where Self: Sized
    {
        io::Read::chain(self, next)
    }
}

/// Alternative to `std::io::Write`
///
/// This trait is automatically implemented for all types that implement `std::io::Write`.
///
/// Differences to `std::io::Write`
/// ===============================
/// Methods that are just wrappers around the equivalent methods of `std::io::Write`:
///
/// - `write`
/// - `flush`
///
/// Methods that provide a slightly different functionality than their counterparts in
/// `std::io::Write`:
///
/// - `write_all`
///
/// Functions that were removed or moved to a different trait,
/// because they cannot be implemented with providing all desired guarantees:
///
/// - `write_fmt` → removed
pub trait Write : Stream {
    /// Write a buffer into this object, returning how many bytes were written.
    ///
    /// This method is equivalent to [`std::io::Write::write`].
    ///
    /// [`std::io::Write::write`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write
    fn write(&mut self, buf: &[u8]) -> io::Result<usize>;

    /// Flush this output stream, ensuring that all intermediately buffered
    /// contents reach their destination.
    ///
    /// This method is equivalent to [`std::io::Write::flush`].
    ///
    /// [`std::io::Write::flush`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.flush
    fn flush(&mut self) -> io::Result<()>;

    /// Attempts to write an entire buffer into this write.
    ///
    /// Similarly to [`std::io::Write::write_all`],
    /// this method will continuously call `write` while there is more data to write.
    /// This method will not return until the entire buffer has been
    /// successfully written or an error occurs. The first error generated from
    /// this method will be returned.
    ///
    /// The supplied buffer will be consumed by the writing operation.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`write`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// All bytes consumed from the buffer will be written to the the writer and vice versa.
    /// It is guaranteed that no data is lost in case of error.
    ///
    /// Differences to `std::io::Write::write_all`
    /// ==========================================
    /// - Does not retry on [`ErrorKind`]`::Interrupted`.
    /// - Takes a `BufRead` instance instead of just a plain `&[u8]`.
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - In case of error, it is always clear how much data was already written. No data is lost.
    ///
    /// [`write`]: ./trait.Write.html#tymethod.write
    /// [`std::io::Write::write_all`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Write.html#method.write_all
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn write_all<R: BufRead + ?Sized>(&mut self, buf: &mut R) -> io::Result<()> {
        copy(buf, self)
    }
}

impl<W: ?Sized+io::Write> Write for W {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        io::Write::write(self, buf)
    }

    #[inline]
    fn flush(&mut self) -> io::Result<()> {
        io::Write::flush(self)
    }
}

/// Alternative to `std::io::BufRead`
///
/// This trait is automatically implemented for all types that implement `std::io::BufRead`.
///
/// Differences to [`std::io::BufRead`]
/// ===================================
/// Methods that are just wrappers around the equivalent methods of [`std::io::BufRead`]:
///
/// - `fill_buf`
/// - `consume`
///
/// Methods that provide a slightly different functionality than their counterparts in
/// [`std::io::BufRead`]:
///
/// - `read_until`
/// - `split`
///
/// Methods originally implemented in a different place:
///
/// - `read_to_end` ← [`std::io::Read::read_to_end`]
/// - `read_exact` ← [`std::io::Read::read_exact`]
/// - `bytes` ← [`std::io::Read::bytes`]
///
/// New methods that have no counterpart in `std::io`:
///
/// - `skip_to_end`
/// - `skip_until`
///
/// Functions that were removed or moved to a different trait,
/// because they cannot be implemented with providing all desired guarantees:
///
/// - `read_line` → [`Utf8Reader::read_line`]
///
/// [`Utf8Reader::read_line`]: ./struct.Utf8Reader.html#method.read_line
/// [`std::io::Read::read_to_end`]:
///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_end
/// [`std::io::Read::read_exact`]:
///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_exact
/// [`std::io::Read::bytes`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.bytes
/// [`std::io::Read`]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
pub trait BufRead {
    /// Fills the internal buffer of this object, returning the buffer contents.
    ///
    /// This method is equivalent to [`std::io::BufRead::fill_buf`].
    ///
    /// [`std::io::BufRead::fill_buf`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    fn fill_buf(&mut self) -> io::Result<&[u8]>;

    /// Tells this buffer that `amt` bytes have been consumed from the buffer,
    /// so they should no longer be returned in calls to `read`.
    ///
    /// This method is equivalent to [`std::io::BufRead::consume`].
    ///
    /// [`std::io::BufRead::consume`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.consume
    #[inline]
    fn consume(&mut self, amt: usize);

    /// Read all bytes until EOF in this source, placing them into `buf`.
    ///
    /// Similar to [`std::io::Read::read_to_end`], all bytes read from this source will
    /// be appended to the specified buffer `buf`.
    ///
    /// This function will continuously call [`fill_buf`] and [`consume`] to
    /// append more data to `buf` until [`fill_buf`] returns either `Ok(&[])` or any kind of error.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// All bytes consumed from the reader will be written to the buffer and vice versa.
    /// It is guaranteed that no data is lost in case of error.
    ///
    /// Differences to `std::io::Read::read_to_end`
    /// ===========================================
    /// - Does not retry on [`ErrorKind`]`::Interrupted`.
    /// - Uses [`BufRead`] instead of [`Read`].
    /// - Does not return the number of bytes that are copied.
    /// - Works with all kind of writers, not just `Vec<u8>`
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - Avoids double buffering if the source already implements [`BufRead`].
    /// - Allows different buffer sizes by using [`BufReader::with_capacity`].
    ///
    /// Disadvantages
    /// -------------
    /// The fact that it does not return the number of bytes copied stems from the fact that it
    /// cannot return this information in case of error.
    /// This would go against the goal of allowing reliable retry.
    ///
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`consume`]: ./trait.BufRead.html#tymethod.consume
    /// [`BufRead`]: ./trait.BufRead.html
    /// [`Read`]: ./trait.Read.html
    /// [`BufReader::with_capacity`]:
    ///     ./buf_redux_reexport/struct.BufReader.html#method.with_capacity
    /// [`std::io::Read::read_to_end`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_end
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn read_to_end<R: Write + ?Sized>(&mut self, buf: &mut R) -> io::Result<()> {
        copy(self, buf)
    }

    /// Skip all bytes until EOF in this source.
    ///
    /// Acts like [`read_to_end`], but all bytes read from this source are
    /// discarded.
    ///
    /// This function will continuously call [`fill_buf`] and [`consume`] until
    /// [`fill_buf`] returns either `Ok(&[])` or any kind of error.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// [`read_to_end`]: #method.read_to_end
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`consume`]: ./trait.BufRead.html#tymethod.consume
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn skip_to_end(&mut self) -> io::Result<()> {
        copy(self, &mut io::sink())
    }

    /// Read the exact number of bytes required to fill `buf`.
    ///
    /// Similarliy to [`std::io::Read::read_exact`], this function reads as many bytes
    /// as necessary to completely fill the specified buffer `buf`.
    ///
    /// No guarantees are provided about the contents of `buf` when this
    /// function is called, implementations cannot rely on any property of the
    /// contents of `buf` being true. It is recommended that implementations
    /// only write data to `buf` instead of reading its contents.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// If this function encounters an "end of file" before completely filling
    /// the buffer, it returns an error of the kind [`ErrorKind`]`::UnexpectedEof`.
    ///
    /// If this function returns an error, the buffer will contain all bytes read up to that point.
    /// The position of the cursor will point one byte past the last read byte.
    ///
    /// All bytes consumed from the reader will be written to the buffer and vice versa.
    /// It is guaranteed that no data is lost in case of error.
    ///
    /// Differences to `std::io::Read::read_exact`
    /// ==========================================
    /// - Does not retry on [`ErrorKind`]`::Interrupted`.
    /// - Uses [`BufRead`] instead of [`Read`].
    /// - In case of error the buffer contains all bytes read up to that point.
    /// - Takes a [`Cursor`] instead of plain buffer to track the current position.
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - No data ist lost on error.
    ///
    /// Disadvantages
    /// -------------
    /// The function is slightly less ergonomic to use.
    ///
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`BufRead`]: ./trait.BufRead.html
    /// [`Read`]: ./trait.Read.html
    /// [`Cursor`]: https://doc.rust-lang.org/nightly/std/io/struct.Cursor.html
    /// [`std::io::Read::read_exact`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_exact
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn read_exact(&mut self, buf: &mut io::Cursor<&mut [u8]>) -> io::Result<()> {
        let mut remaining = buf.get_ref().len() - buf.position() as usize;
        while remaining > 0 {
            let written = {
                let available = try!(BufRead::fill_buf(self));
                if available.len() == 0 {
                    return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                                              "Stream is already at EOF"));
                }
                try!(buf.write(available))
            };
            remaining -= written;
            BufRead::consume(self, written);
        }
        Ok(())
    }

    /// Transforms this buffered reader into an iterator over its bytes.
    ///
    /// This method is approximately equivalent to [`std::io::Read::bytes`].
    ///
    /// The returned type implements [`std::iter::Iterator`]
    /// where the `Item` is `Result<u8, R::Err>`.
    /// The yielded item is `Ok` if a byte was successfully read and
    /// `Err` otherwise for I/O errors. EOF is mapped to returning `None` from
    /// this iterator.
    ///
    /// Errors
    /// ======
    /// If fill_buf returns any kind of error, the iterator yields `Some(Err)`. In case of error
    /// it is safe to iterate further to retry the reading operation.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by the iterator.
    ///
    /// Differences to `std::io::Read::bytes`
    /// =====================================
    /// - Uses [`BufRead`] instead of [`Read`].
    ///
    /// Advantages
    /// ----------
    /// - No accidentialy unbuffered reading of single bytes
    ///
    /// [`Read`]: ./trait.Read.html
    /// [`BufRead`]: ./trait.BufRead.html
    /// [`std::io::Read::bytes`]:
    ///     https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.bytes
    /// [`std::iter::Iterator`]: https://doc.rust-lang.org/nightly/std/iter/trait.Iterator.html
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn bytes(self) -> Bytes<Self>
        where Self: Sized
    {
        Bytes::new(self)
    }

    /// Read all bytes into a buffer until a delimiter is reached.
    ///
    /// Similar to [`std::io::BufRead::read_until`] ,this function will read bytes from
    /// the underlying stream and push them to the specified buffer `buf`, until the delimiter
    /// `delim` is found. If the delimiter is found, it is also part of the result.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind`]`::UnexpectedEof`.
    ///
    /// All bytes consumed from the buffered reader will be written to the specified buffer and
    /// vice versa.
    /// It is guaranteed that no data is lost in case of error.
    ///
    /// Differences to `std::io::BufRead::read_until`
    /// =============================================
    /// - Does not retry on [`ErrorKind`]`::Interrupted`.
    /// - Does not return the number of bytes that are read.
    /// - Returns an error on EOF instead of success.
    /// - Works with all kind of writers, not just `Vec<u8>`
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    ///
    /// Disadvantages
    /// -------------
    /// The fact that it does not return the number of bytes copied stems from the fact that it
    /// cannot return this information in case of error.
    /// This would go against the goal of allowing reliable retry.
    ///
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`std::io::BufRead::read_until`]:
    ///     http://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#method.read_until
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn read_until<W: Write + ?Sized>(&mut self, delim: u8, buf: &mut W) -> io::Result<()> {
        copy_until(self, buf, delim)
    }

    /// Skips all bytes until a delimiter is reached.
    ///
    /// This function will discard bytes from the underlying stream until the delimiter `delim` is
    /// found.
    ///
    /// Acts like [`read_until`], but all bytes read from this source are
    /// discarded.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind`]`::UnexpectedEof`.
    ///
    /// [`read_until`]: #method.read_until
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    #[inline]
    fn skip_until(&mut self, delim: u8) -> io::Result<()> {
        copy_until(self, &mut io::sink(), delim)
    }

    /// Returns an iterator over the contents of this reader split on a delimiter.
    ///
    /// The iterator returned from this function will return instances of
    /// `io::Result<Vec<u8>>`. Each vector returned will *not* have the
    /// delimiter byte at the end.
    ///
    /// Errors
    /// ======
    /// The iterator will yield an error whenever [`read_until`] would have also
    /// returned an error.
    ///
    /// [`read_until`]: #method.read_until
    #[inline]
    fn split(self, byte: u8) -> Split<Self>
        where Self: Sized
    {
        Split::new(self, byte)
    }
}

impl<R: ?Sized+io::BufRead> BufRead for R {
    #[inline]
    fn fill_buf(&mut self) -> io::Result<&[u8]> {
        io::BufRead::fill_buf(self)
    }

    #[inline]
    fn consume(&mut self, amt: usize) {
        io::BufRead::consume(self, amt)
    }
}

fn find2(delims: (u8, u8), buf: &[u8]) -> usize {
    let mut start = 0;
    while let Some(i) = memchr::memchr(delims.0, &buf[start..]) {
        let current = start + i;
        if (current == buf.len() - 1) || (buf[current + 1] == delims.1) {
            return current;
        }
        start = current + 1;
    }
    buf.len()
}

/// A `BufReadGrow` is a `BufRead`er that has the ability to read additional data even if the
/// buffer is not empty.
///
/// A `BufRead` guarantees an internal buffer of at only one byte with no possibility to read
/// additional data without consuming the already read data first.
/// With this limitation it is not possible to implement many functions in an interrupt-safe way.
///
/// Interrupt-safe function require that - when the function returns - all data is either left in
/// the stream or appended to the buffer.
/// But for example when read UTF-8 with a `BufRead`er,
/// this requirement can only be met by appending incomplete UTF-8 to the buffer which is also
/// unacceptable by itself.
///
/// For that reason, the `BufReadGrow` trait is introduced which extends `BufRead` by a method to
/// grow the internal buffer.
/// This requires the buffer to be able to relocate the data in the internal buffer.
pub trait BufReadGrow: io::BufRead {
    /// Grows the internal buffer of this object by at least one byte,
    /// returning the buffer contents.
    ///
    /// Like [`fill_buf`], this function is a lower-level call.
    /// It needs to be paired with the [`consume`] method to function properly.
    /// When calling this method, none of the contents will be "read" in the sense that later
    /// calling `read` may return the same contents. As such, `consume` must be
    /// called with the number of bytes that are consumed from this buffer to
    /// ensure that the bytes are never returned twice.
    ///
    /// Errors
    /// ======
    /// - Any error returned by the underlying call to `read` will be returned immediately.
    /// - If the stream has already reached EOF, an error of kind
    ///   [`ErrorKind`]`::UnexpectedEof` is returned.
    /// - If the internal buffer of is full, an appropriate error is returned.
    ///   Since there is no specific `ErrorKind` for this, [`ErrorKind`]`::Other`
    ///   should be used.
    ///
    /// [`fill_buf`]: trait.BufRead.html#tymethod.fill_buf
    /// [`consume`]: trait.BufRead.html#tymethod.consume
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn grow_buf(&mut self) -> io::Result<&[u8]>;

    /// Fills the internal buffer to at least the specified amount,
    /// returning the buffer contents.
    ///
    /// Like [`BufRead::fill_buf`][`fill_buf`] and [`grow_buf`], this function is a lower-level call.
    /// It needs to be paired with the [`consume`] method to function properly.
    /// When calling this method, none of the contents will be "read" in the sense that later
    /// calling `read` may return the same contents. As such, `consume` must be
    /// called with the number of bytes that are consumed from this buffer to
    /// ensure that the bytes are never returned twice.
    ///
    /// Errors
    /// ======
    /// - Any I/O error will be returned immediately.
    /// - If the stream has already reached EOF, an error of kind
    ///   [`ErrorKind`]`::UnexpectedEof` is returned.
    /// - If the internal buffer of is full, an appropriate error is returned.
    ///   See [`grow_buf`] for more details.
    ///
    /// [`grow_buf`]: #tymethod.grow_buf
    /// [`fill_buf`]: trait.BufRead.html#tymethod.fill_buf
    /// [`consume`]: trait.BufRead.html#tymethod.consume
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn fill_buf_min(&mut self, size: usize) -> io::Result<&[u8]> {
        let len = try!(self.fill_buf()).len();
        match len {
            0 => Err(io::Error::new(io::ErrorKind::UnexpectedEof, "Unexpected end of stream")),
            n if n == size - 1 => self.grow_buf(),
            n if n < size => {
                while try!(self.grow_buf()).len() < size { }
                self.fill_buf()
            }
            _ => self.fill_buf(),
        }
    }

    /// Read all bytes into a buffer until two consecutive delimiters are reached.
    ///
    /// This function will read bytes from the underlying stream and push them to the specified
    /// buffer `buf`, until the two consecutive delimiters `delims` are found.
    /// If the delimiters are found, they also part of the result.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if a call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind`]`::UnexpectedEof`.
    ///
    /// In case of an error, all bytes read up to that point are appended to the buffer and
    /// consumed from this buffered reader.
    /// There's one notable exception to that rule: If the last byte in the buffer would be the
    /// first delimiter, it is left in the buffered reader.
    /// Otherwise retrying on error would not work reliably.
    ///
    /// In any case, all bytes consumed from the buffered reader will be written to the specified
    /// buffer and vice versa.
    /// It is guaranteed that no data is lost in case of error.
    ///
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> io::Result<()> {
        let mut extend = false;
        loop {
            let (done, used) = {
                let available = if extend {
                    try!(self.grow_buf())
                } else {
                    try!(self.fill_buf())
                };
                if available.len() == 0 {
                    return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                                              "Stream did not contain the delimiters"));
                }
                extend = false;
                let found = find2(delims, available);
                let (done, used) = if found == available.len() {
                    (false, found)
                } else if found == available.len() - 1 {
                    extend = true;
                    (false, found)
                } else {
                    (true, found + 2)
                };
                buf.extend_from_slice(&available[..used]);
                (done, used)
            };
            self.consume(used);
            if done {
                return Ok(());
            }
        }
    }

    /// Skip all bytes until two consecutive delimiters are reached.
    ///
    /// This function will discard bytes from the underlying stream until the two consecutive
    /// delimiters `delims` are found.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if a call to [`fill_buf`] returns
    /// any kind of error.
    /// Instances of [`ErrorKind`]`::Interrupted` are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind`]`::UnexpectedEof`.
    ///
    /// [`fill_buf`]: ./trait.BufRead.html#tymethod.fill_buf
    /// [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn skip_until2(&mut self, delims: (u8, u8)) -> io::Result<()> {
        let mut extend = false;
        loop {
            let (done, used) = {
                let available = if extend {
                    try!(self.grow_buf())
                } else {
                    try!(self.fill_buf())
                };
                if available.len() == 0 {
                    return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                                              "Stream did not contain the delimiters"));
                }
                extend = false;
                let found = find2(delims, available);
                let (done, used) = if found == available.len() {
                    (false, found)
                } else if found == available.len() - 1 {
                    extend = true;
                    (false, found)
                } else {
                    (true, found + 2)
                };
                (done, used)
            };
            self.consume(used);
            if done {
                return Ok(());
            }
        }
    }

    fn decode_utf8(self) -> utf8::Utf8Reader<Self>
        where Self : Sized
    {
        utf8::Utf8Reader::new(self)
    }
}

#[cfg(test)]
mod tests {
    use std::io;
    use buf_redux_reexport as br;

    use {Read, BufRead, BufReadGrow};

    #[test]
    fn read_until() {
        let mut buf = io::Cursor::new(&b"12"[..]);
        let mut v = Vec::new();
        assert_eq!(buf.read_until(b'3', &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"12");

        let mut buf = io::Cursor::new(&b"1233"[..]);
        let mut v = Vec::new();
        buf.read_until(b'3', &mut v).unwrap();
        assert_eq!(v, b"123");
        v.truncate(0);
        buf.read_until(b'3', &mut v).unwrap();
        assert_eq!(v, b"3");
        v.truncate(0);
        assert_eq!(buf.read_until(b'3', &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"");
    }

    #[test]
    fn read_to_end() {
        let mut c = io::Cursor::new(&b""[..]);
        let mut v = Vec::new();
        c.read_to_end(&mut v).unwrap();
        assert_eq!(v, b"");

        let mut c = io::Cursor::new(&b"1"[..]);
        let mut v = Vec::new();
        c.read_to_end(&mut v).unwrap();
        assert_eq!(v, b"1");

        let cap = 1024 * 1024;
        let data = (0..cap).map(|i| (i / 3) as u8).collect::<Vec<_>>();
        let mut v = Vec::new();
        let (a, b) = data.split_at(data.len() / 2);
        io::Cursor::new(a).read_to_end(&mut v).unwrap();
        io::Cursor::new(b).read_to_end(&mut v).unwrap();
        assert_eq!(v, data);
    }

    #[test]
    fn read_exact() {
        let mut buf = [0; 4];
        let mut buf = io::Cursor::new(&mut buf[..]);

        let mut c = io::Cursor::new(&b""[..]);
        assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(buf.position(), 0);

        let mut c = io::Cursor::new(&b"123"[..]).chain(io::Cursor::new(&b"456789"[..]));
        buf.set_position(0);
        c.read_exact(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"1234");
        buf.set_position(0);
        c.read_exact(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"5678");
        buf.set_position(0);
        assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(buf.position(), 1);
    }

    #[test]
    fn read_exact_slice() {
        let mut buf = [0; 4];
        let mut buf = io::Cursor::new(&mut buf[..]);

        let mut c = &b""[..];
        assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);

        let mut c = &b"123"[..];
        buf.set_position(0);
        assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(buf.position(), 3);
        assert_eq!(buf.get_ref(), b"123\0");

        let mut c = &b"1234"[..];
        buf.set_position(0);
        c.read_exact(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"1234");

        let mut c = &b"56789"[..];
        buf.set_position(0);
        c.read_exact(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"5678");
        assert_eq!(c, b"9");
    }

    #[test]
    fn read_until2() {
        let mut buf = io::Cursor::new(&b"1234321234554"[..]);
        let mut v = Vec::new();
        assert_eq!(buf.read_until2((b'3', b'5'), &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"1234321234554");

        let mut buf = io::Cursor::new(&b"1234321234554"[..]);
        let mut v = Vec::new();
        buf.read_until2((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"1234");
        v.truncate(0);
        buf.read_until2((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"321234");
        v.truncate(0);
        assert_eq!(buf.read_until2((b'3', b'4'), &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"554");
    }

    #[test]
    fn read_until2_smallbuffer() {
        let mut buf = br::BufReader::with_capacity(3, io::Cursor::new(&b"12343212334554"[..]));
        let mut v = Vec::new();
        assert_eq!(buf.read_until2((b'3', b'5'), &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"12343212334554");

        let mut buf = br::BufReader::with_capacity(3, io::Cursor::new(&b"12343212334554"[..]));
        let mut v = Vec::new();
        buf.read_until2((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"1234");
        v.truncate(0);
        buf.read_until2((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"3212334");
        v.truncate(0);
        assert_eq!(buf.read_until2((b'3', b'4'), &mut v).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"554");
    }
}