//! Alternative implementation of many functions found in [`std::io`][stdio],
//! but suitable for blocking IO over networks.
//!
//! The main reason for this crate is the handling of [`ErrorKind::Interrupted`][errorkind] in
//! `std::io`.
//! Except for [`Read::read()`][readread] and [`Write::write()`][writewrite], 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 [`BufRead`][bufread] instead of [`Read`][read] to ensure that no
//! content is lost on retry.
//!
//! [stdio]: https://doc.rust-lang.org/nightly/std/io/index.html
//! [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
//! [read]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
//! [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
//! [readread]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html#tymethod.read
//! [writewrite]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write

extern crate memchr;
extern crate buf_redux as br;

use std::{io, str};
use std::io::{BufRead, Write};

mod impls;
mod adapt;
mod iter;

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

/// Copies the entire content of a buffered reader into a writer.
///
/// Similar to [`std::io::copy`][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`][fillbuf] or
/// [`write`][writewrite] returns any kind of error.
/// Instances of [`ErrorKind::Interrupted`][errorkind] 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`][errorkind].
/// - Uses [`BufRead`][bufread] instead of [`Read`][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`][bufread].
/// - Allows different buffer sizes by using [`BufReader::with_capacity`][withcap].
///
/// 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.
///
/// [copy]: https://doc.rust-lang.org/nightly/std/io/fn.copy.html
/// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
/// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
/// [writewrite]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write
/// [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
/// [read]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
/// [withcap]: https://doc.rust-lang.org/nightly/std/io/struct.BufReader.html#method.with_capacity
pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> io::Result<()>
    where R: io::BufRead, W: io::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`][fillbuf] or
/// [`write`][writewrite] returns any kind of error.
/// Instances of [`ErrorKind::Interrupted`][errorkind] 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.
///
/// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
/// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
/// [writewrite]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write
pub fn copy_until<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W, delim: u8) -> io::Result<()>
    where R: io::BufRead, W: io::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(());
        }
    }
}

/// Extension methods for `std::io::Read`
///
/// This trait is automatically implemented for all types that implement `std::io::Read`.
pub trait ReadExt : io::Read {
    /// Creates a buffered reader with default capacity and default strategies
    ///
    /// Please see the documentation of [`buf_redux::BufReader`][bufreader] for more details
    ///
    /// [bufreader]: ../buf_redux/struct.BufReader.html
    fn buffer(self) -> br::BufReader<Self, br::DefaultReadStrategy, br::DefaultMoveStrategy> where Self: Sized {
        br::BufReader::new(self)
    }

    /// Transforms this reader into a reader that automatically retries on interrupts
    ///
    /// The returned adapter will behave identically to the original reader, except that it retries
    /// the reading operation automatically if an error of kind
    /// [`ErrorKind::Interrupted`][errorkind] 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
    fn retry(self) -> Retry<Self> where Self: Sized {
        Retry::new(self)
    }

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

    /// Creates an adapter which will read at most `limit` bytes from it.
    ///
    /// This function returns a new instance of `Read` which will read at most
    /// `limit` bytes, after which it will always return EOF (`Ok(0)`). Any
    /// read errors will not count towards the number of bytes read and future
    /// calls to `read` may succeed.
    ///
    /// This function is equivalent to `std::io::Read::take` but the returened adapter implements
    /// `BufReadGrow` if possible.
    fn take_net(self, limit: u64) -> Take<Self> where Self: Sized {
        Take::new(self, limit)
    }
}

impl<R: io::Read> ReadExt for R { }

/// Extension methods for `std::io::Write`
///
/// This trait is automatically implemented for all types that implement `std::io::Write`.
pub trait WriteExt : io::Write {
    /// Transforms this writer into a writer that automatically retries on interrupts
    ///
    /// The returned adapter will behave identically to the original reader, except that it retries
    /// the writing operation automatically if an error of kind
    /// [`ErrorKind::Interrupted`][errorkind] occurs.
    ///
    /// Note
    /// ----
    /// Methods that are already expected to retry are forwarded directly to the underlying writer.
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn retry(self) -> Retry<Self> where Self: Sized {
        Retry::new(self)
    }

    /// Attempts to write an entire buffer into this write.
    ///
    /// 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`][writewrite] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] 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.
    ///
    /// [writewrite]: https://doc.rust-lang.org/nightly/std/io/trait.Write.html#tymethod.write
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn write_all_net(&mut self, buf: &mut &[u8]) -> io::Result<()> {
        copy(buf, self)
    }

    /// Creates an adapter which will write at most `limit` bytes to it.
    ///
    /// This function returns a new instance of `Write` which will write at most
    /// `limit` bytes, after which it will always return Ok(0).
    /// Any write errors will not count towards the number of bytes written and future
    /// calls to `write` may succeed.
    ///
    /// This function is equivalent to `std::io::Read::take` but the returened adapter implements
    /// `Write`.
    fn take_net(self, limit: u64) -> Take<Self> where Self: Sized {
        Take::new(self, limit)
    }
}

impl<W: io::Write> WriteExt for W { }

/// Extension methods for `std::io::BufRead`
///
/// This trait is automatically implemented for all types that implement `std::io::BufRead`.
pub trait BufReadExt : io::BufRead {
    //=============================================================================================
    // Methods originally implemented in std::io::Read
    //=============================================================================================

    /// Read all bytes until EOF in this source, placing them into `buf`.
    ///
    /// Similar to [`std::io::Read::read_to_end`][readtoend], all bytes read from this source will
    /// be appended to the specified buffer `buf`.
    ///
    /// This function will continuously call [`fill_buf`][fillbuf] and [`consume`][consume] to
    /// append more data to `buf` until [`fill_buf`][fillbuf] returns either `Ok(&[])` or any kind
    /// of error.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] 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`][errorkind].
    /// - Uses [`BufRead`][bufread] instead of [`Read`][read].
    /// - Does not return the number of bytes that are copied.
    /// - Different reallocation behavior of the buffer.
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - Avoids double buffering if the source already implements [`BufRead`][bufread].
    /// - Allows different buffer sizes by using [`BufReader::with_capacity`][withcap].
    ///
    /// 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.
    ///
    /// [readtoend]: 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
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    /// [consume]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.consume
    /// [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
    /// [read]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
    /// [withcap]: https://doc.rust-lang.org/nightly/std/io/struct.BufReader.html#method.with_capacity
    fn read_to_end_net(&mut self, buf: &mut Vec<u8>) -> io::Result<()> {
        copy(self, buf)
    }

    /// Skip all bytes until EOF in this source.
    ///
    /// Acts like [`read_to_end_net`][readtoendnet], but all bytes read from this source are
    /// discarded.
    ///
    /// This function will continuously call [`fill_buf`][fillbuf] and [`consume`][consume] until
    /// [`fill_buf`][fillbuf] returns either `Ok(&[])` or any kind of error.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// [readtoendnet]: #method.read_to_end_net
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    /// [consume]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.consume
    fn skip_to_end_net(&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`][readexact], 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`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] 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`][errorkind].
    ///
    /// 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`][errorkind].
    /// - Uses [`BufRead`][bufread] instead of [`Read`][read].
    /// - In case of error the buffer contains all bytes read up to that point.
    /// - Takes a [`Cursor`][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.
    ///
    /// [readexact]: 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
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    /// [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
    /// [read]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
    /// [cursor]: https://doc.rust-lang.org/nightly/std/io/struct.Cursor.html
    fn read_exact_net(&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!(self.fill_buf());
                if available.len() == 0 {
                    return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                        "Stream is already at EOF"));
                }
                try!(buf.write(available))
            };
            remaining = remaining - written;
            self.consume(written);
        }
        Ok(())
    }

    /// Transforms this [`BufRead`][bufread] instance to an [`Iterator`][iterator] over its bytes.
    ///
    /// This method is approximately equivalent to [`std::io::Read::bytes`][bytes].
    ///
    /// The returned type implements [`Iterator`][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`][errorkind] are *not* handled by the iterator.
    ///
    /// Differences to `std::io::Read::bytes`
    /// =====================================
    /// - Uses [`BufRead`][bufread] instead of [`Read`][read].
    ///
    /// Advantages
    /// ----------
    /// - No accidentialy unbuffered reading of single bytes
    ///
    /// [iterator]: https://doc.rust-lang.org/nightly/std/iter/trait.Iterator.html
    /// [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
    /// [bytes]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.bytes
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [read]: https://doc.rust-lang.org/nightly/std/io/trait.Read.html
    fn bytes_net(self) -> Bytes<Self> where Self: Sized {
        Bytes::new(self)
    }

    //=============================================================================================
    // Methods originally implemented in std::io::BufRead
    //=============================================================================================

    /// Read all bytes into a buffer until a delimiter is reached.
    ///
    /// Similar to [`std::io::BufRead::read_until`][readuntil] ,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`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// 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`][errorkind].
    /// - Does not return the number of bytes that are read.
    /// - Returns an error on EOF instead of success.
    ///
    /// 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.
    ///
    /// [readuntil]: 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
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    fn read_until_net(&mut self, delim: u8, buf: &mut Vec<u8>) -> 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_net`][readuntilnet], but all bytes read from this source are
    /// discarded.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// [readuntilnet]: #method.read_until_net
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    fn skip_until_net(&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_net`][readuntilnet] would have also
    /// returned an error.
    ///
    /// [readuntilnet]: #method.read_until_net
    fn split_net(self, byte: u8) -> Split<Self> where Self: Sized {
        Split::new(self, byte)
    }
}

impl<R: io::BufRead> BufReadExt for R { }

fn utf8_valid_up_to(buf: &[u8]) -> io::Result<usize> {
    match str::from_utf8(buf) {
        Ok(_) => Ok(buf.len()),
        Err(e) if e.valid_up_to() > 0 => Ok(e.valid_up_to()),
        Err(_) if buf.len() > 4 => Err(io::Error::new(io::ErrorKind::InvalidData,
            "stream did not contain valid UTF-8")), // TODO: improve UTF-8 validity test
        Err(_) => Ok(0),
    }
}

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 `BufRead::fill_buf`, this function is a lower-level call.
    /// It needs to be paired with the [`consume`][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.
    ///
    /// Calling this function will either extend the current buffer size by at least one byte,
    /// or else return an error of kind [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// # Errors
    ///
    /// This function will return an I/O error if the underlying reader was
    /// read, but returned an error or if the underlying reader was already at EOF.
    ///
    /// [consume]: #tymethod.consume
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn grow_buf(&mut self) -> io::Result<&[u8]>;

    /// 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`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// 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.
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    fn read_until2_net(&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`][fillbuf] returns
    /// any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// If this reader has reached EOF then this function will return
    /// [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    fn skip_until2_net(&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(());
            }
        }
    }

    /// Fills the internal buffer of this object, returning the buffer content as a string
    ///
    /// This function will return at least one valid `char` except when reaching EOF.
    /// If invalid or incomplete UTF-8 is encountered, the function returns all valid UTF-8 up to
    /// that point.
    ///
    /// If the function returns an empty slice, the unterlying reader has reached EOF and all data
    /// in the stream was valid UTF-8.
    ///
    /// Errors
    /// ======
    /// - If either `fill_buf` or `grow_buf` return an error, this error is returned immediately.
    /// - If invalid UTF-8 is encountered at the beginning of the buffer, an error of kind
    ///   [`ErrorKind::InvalidData`][errorkind] is returned.
    /// - If an incomplete UTF-8 character followed by EOF is encountered at the beginning of the
    ///   buffer, an error of kind [`ErrorKind::UnexpectedEof`][errorkind] is returned.
    ///
    /// Issues
    /// ======
    /// Currently there's no way to decide if the remaining data is an incomplete UTF-8 char or
    /// just plain invalid UTF-8 if the remaining buffer is smaller or equal than 4 bytes.
    /// (Issue [`rust-lang/rust#32584`][issue])
    ///
    /// This case is currently just interpreted as [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [issue]: https://github.com/rust-lang/rust/issues/32584
    fn fill_buf_str(&mut self) -> io::Result<&str> {
        let (buflen, mut valid_up_to) = {
            let buf = try!(self.fill_buf());
            (buf.len(), try!(utf8_valid_up_to(buf)))
        };
        if buflen != 0 {
            while valid_up_to == 0 {
                valid_up_to = try!(utf8_valid_up_to(try!(self.grow_buf())));
            }
        }
        let buf = try!(self.fill_buf());
        Ok(unsafe{str::from_utf8_unchecked(&buf[0..valid_up_to])})
    }

    /// Grows the internal buffer of this object by at least one char,
    /// returning the buffer content as a string
    ///
    /// This function will return at least one additional valid `char` compared to a call to
    /// `fill_buf_str`.
    /// If invalid or incomplete UTF-8 is encountered, the function returns all valid UTF-8 up to
    /// that point.
    ///
    /// If the function returns an empty slice, the unterlying reader has reached EOF and all data
    /// in the stream was valid UTF-8.
    ///
    /// Errors
    /// ======
    /// - If either `fill_buf` or `grow_buf` return an error, this error is returned immediately.
    /// - If invalid UTF-8 is encountered at the beginning of the buffer s.t. no additional char
    ///   can be returned, an error of kind [`ErrorKind::InvalidData`][errorkind] is returned.
    /// - If EOF is encountered, such that no additional char can be returned, an error of kind
    ///   [`ErrorKind::UnexpectedEof`][errorkind] is returned.
    ///
    /// Issues
    /// ======
    /// Currently there's no way to decide if the remaining data is an incomplete UTF-8 char or
    /// just plain invalid UTF-8 if the remaining buffer is smaller or equal than 4 bytes.
    /// (Issue [`rust-lang/rust#32584`][issue])
    ///
    /// This case is currently just interpreted as [`ErrorKind::UnexpectedEof`][errorkind].
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [issue]: https://github.com/rust-lang/rust/issues/32584
    fn grow_buf_str(&mut self) -> io::Result<&str> {
        let start = try!(utf8_valid_up_to(try!(self.fill_buf())));
        let mut valid_up_to = start;
        while valid_up_to == start {
            let buf = try!(self.grow_buf());
            valid_up_to = valid_up_to + try!(utf8_valid_up_to(&buf[valid_up_to..]));
        }
        let buf = try!(self.fill_buf());
        Ok(unsafe{str::from_utf8_unchecked(&buf[0..valid_up_to])})
    }

    /// Read all bytes until EOF in this source, placing them into a string.
    ///
    /// This function will continuously call [`fill_buf`][fillbuf]/[`grow_buf`][growbuf] and
    /// [`consume`][consume] to append more data to `buf` until [`fill_buf`][fillbuf] returns
    /// either `Ok(&[])` or any kind of error occurs.
    ///
    /// Errors
    /// ======
    /// This function will return an error immediately if any call to [`fill_buf`][fillbuf] or
    /// [`grow_buf`][growbuf] returns any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// If invalid UTF-8 is encountered, an error of kind [`ErrorKind::InvalidData`][errorkind] is
    /// returned and the string will contain all valid UTF-8 up to that point.
    ///
    /// 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_string`
    /// ==============================================
    /// - Does not retry on [`ErrorKind::Interrupted`][errorkind].
    /// - Uses `BufReadGrow` instead of [`BufRead`][bufread].
    /// - Does not return the number of bytes that are copied.
    /// - On error, string will contain all valid UTF-8 up to that point.
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - No data ist lost on error (e.g. invalid UTF-8).
    ///
    /// 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.
    ///
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    /// [growbuf]: ./trait.BufReadGrow.html#tymethod.grow_buf
    /// [consume]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.consume
    /// [bufread]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html
    fn read_to_string_net(&mut self, buf: &mut String) -> io::Result<()> {
        loop {
            let written = {
                let available = try!(self.fill_buf_str());
                if available.is_empty() {
                    return Ok(());
                }
                buf.push_str(available);
                available.len()
            };
            self.consume(written);
        }
    }

    /// Read all bytes until a CRLF is reached, and append them to the provided buffer.
    ///
    /// This function will UTF-8 characters from the underlying stream and append them to the 'buf'
    /// until the CRLF delimiter (the 0xA 0xD bytes) is found.
    ///
    /// Errors
    /// ======
    /// Like `read_until2_net`, this function will return an error immediately if a call to
    /// [`fill_buf`][fillbuf] returns any kind of error.
    /// Instances of [`ErrorKind::Interrupted`][errorkind] are *not* handled by this function.
    ///
    /// This function will return an error of kind [`ErrorKind::InvalidData`][errorkind] if the
    /// read bytes are not valid UTF-8.
    /// If EOF is reached, an error of kind [`ErrorKind::UnexpectedEof`][errorkind] is returned.
    ///
    /// If any kind of error occurs, the buffer will contain all valid UTF-8 up to that point.
    ///
    /// 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.
    ///
    /// The read buffer will never contain a CR (`\r`) as last character, even in case of error.
    /// Doing so could lead to skipping a CRLF sequence in case of retry.
    /// In case of `ErrorKind::UnexpectedEof`, this behavior is a bit unexpected and may
    /// change in a future version.
    ///
    /// Differences to `std::io::BufRead::read_line`
    /// ============================================
    /// - Does not retry on [`ErrorKind::Interrupted`][errorkind].
    /// - Does not return the number of bytes that are read.
    /// - Returns an error on EOF instead of success.
    /// - Uses CRLF as line ending convention instead of just LF.
    ///
    /// Advantages
    /// ----------
    /// - Function is interruptable, e.g. to allow graceful shutdown for server applications.
    /// - Suitable for network protocols, because those usually use CRLF as line endings.
    ///
    /// 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.
    ///
    /// [fillbuf]: https://doc.rust-lang.org/nightly/std/io/trait.BufRead.html#tymethod.fill_buf
    /// [errorkind]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
    fn read_line_net(&mut self, buf: &mut String) -> io::Result<()> {
        let mut extend = false;
        loop {
            let (done, used) = {
                let available = if extend {try!(self.grow_buf_str())} else {try!(self.fill_buf_str())};
                if available.is_empty() {
                    return Err(io::Error::new(io::ErrorKind::UnexpectedEof,
                        "Stream did not contain the delimiters"));
                }
                extend = false;
                let found = find2((b'\r', b'\n'), available.as_bytes());
                let (done, used) = if found == available.len() {
                    (false, found)
                } else if found == available.len() - 1 {
                    extend = true;
                    (false, found)
                } else {
                    (true, found + 2)
                };
                buf.push_str(&available[..used]);
                (done, used)
            };
            self.consume(used);
            if done {
                return Ok(());
            }
        }
    }
}

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

    use {BufReadExt, BufReadGrow};

    #[test]
    fn read_until_net() {
        let mut buf = io::Cursor::new(&b"12"[..]);
        let mut v = Vec::new();
        assert_eq!(buf.read_until_net(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_net(b'3', &mut v).unwrap();
        assert_eq!(v, b"123");
        v.truncate(0);
        buf.read_until_net(b'3', &mut v).unwrap();
        assert_eq!(v, b"3");
        v.truncate(0);
        assert_eq!(buf.read_until_net(b'3', &mut v).unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"");
    }

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

        let mut c = io::Cursor::new(&b"1"[..]);
        let mut v = Vec::new();
        c.read_to_end_net(&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_net(&mut v).unwrap();
        io::Cursor::new(b).read_to_end_net(&mut v).unwrap();
        assert_eq!(v, data);
    }

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

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

        let mut c = io::Cursor::new(&b"\xff"[..]);
        let mut v = String::new();
        assert!(c.read_to_string_net(&mut v).is_err());
    }

    #[test]
    fn read_exact_net() {
        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_net(&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_net(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"1234");
        buf.set_position(0);
        c.read_exact_net(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"5678");
        buf.set_position(0);
        assert_eq!(c.read_exact_net(&mut buf).unwrap_err().kind(),
                   io::ErrorKind::UnexpectedEof);
        assert_eq!(buf.position(), 1);
    }

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

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

        let mut c = &b"123"[..];
        buf.set_position(0);
        assert_eq!(c.read_exact_net(&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_net(&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_net(&mut buf).unwrap();
        assert_eq!(buf.position(), 4);
        assert_eq!(buf.get_ref(), b"5678");
        assert_eq!(c, b"9");
    }

    #[test]
    fn read_until2_net() {
        let mut buf = io::Cursor::new(&b"1234321234554"[..]);
        let mut v = Vec::new();
        assert_eq!(buf.read_until2_net((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_net((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"1234");
        v.truncate(0);
        buf.read_until2_net((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"321234");
        v.truncate(0);
        assert_eq!(buf.read_until2_net((b'3', b'4'), &mut v).unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"554");
    }

    #[test]
    fn read_until2_net_smallbuffer() {
        let mut buf = br::BufReader::with_capacity(3, io::Cursor::new(&b"12343212334554"[..]));
        let mut v = Vec::new();
        assert_eq!(buf.read_until2_net((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_net((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"1234");
        v.truncate(0);
        buf.read_until2_net((b'3', b'4'), &mut v).unwrap();
        assert_eq!(v, b"3212334");
        v.truncate(0);
        assert_eq!(buf.read_until2_net((b'3', b'4'), &mut v).unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
        assert_eq!(v, b"554");
    }

    #[test]
    fn read_line_net() {
        let mut buf = io::Cursor::new(&b"hihi\r\nhoho\rhaha\nhehe\n\rhrhr\r\n\r\r\n\r\n"[..]);
        let mut v = String::new();
        buf.read_line_net(&mut v).unwrap();
        assert_eq!(v, "hihi\r\n");
        v.truncate(0);
        buf.read_line_net(&mut v).unwrap();
        assert_eq!(v, "hoho\rhaha\nhehe\n\rhrhr\r\n");
        v.truncate(0);
        buf.read_line_net(&mut v).unwrap();
        assert_eq!(v, "\r\r\n");
        v.truncate(0);
        buf.read_line_net(&mut v).unwrap();
        assert_eq!(v, "\r\n");
        v.truncate(0);
        assert_eq!(buf.read_line_net(&mut v).unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
        assert_eq!(v, "");
    }
}