readpartial

readpartial

ri

 --------------------------------------------------------- IO#readpartial
      ios.readpartial(maxlen[, outbuf])    => string, outbuf
 ------------------------------------------------------------------------
      Reads at most _maxlen_ bytes from the I/O stream but it blocks only
      if _ios_ has no data immediately available. If the optional
      _outbuf_ argument is present, it must reference a String, which
      will receive the data. It raises  EOFError  on end of file.
 
      readpartial is designed for streams such as pipe, socket, tty, etc.
      It blocks only when no data immediately available. This means that
      it blocks only when following all conditions hold.
 
      *   the buffer in the IO object is empty.
 
      *   the content of the stream is empty.
 
      *   the stream is not reached to EOF.
 
      When readpartial blocks, it waits data or EOF on the stream. If
      some data is reached, readpartial returns with the data. If EOF is
      reached, readpartial raises EOFError.
 
      When readpartial doesn't blocks, it returns or raises immediately.
      If the buffer is not empty, it returns the data in the buffer.
      Otherwise if the stream has some content, it returns the data in
      the stream. Otherwise if the stream is reached to EOF, it raises
      EOFError.
 
         r, w = IO.pipe           #               buffer          pipe content
         w << "abc"               #               ""              "abc".
         r.readpartial(4096)      #=> "abc"       ""              ""
         r.readpartial(4096)      # blocks because buffer and pipe is empty.
      
         r, w = IO.pipe           #               buffer          pipe content
         w << "abc"               #               ""              "abc"
         w.close                  #               ""              "abc" EOF
         r.readpartial(4096)      #=> "abc"       ""              EOF
         r.readpartial(4096)      # raises EOFError
      
         r, w = IO.pipe           #               buffer          pipe content
         w << "abc\ndef\n"        #               ""              "abc\ndef\n"
         r.gets                   #=> "abc\n"     "def\n"         ""
         w << "ghi\n"             #               "def\n"         "ghi\n"
         r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
         r.readpartial(4096)      #=> "ghi\n"     ""              ""
 
      Note that readpartial is nonblocking-flag insensitive. It blocks
      even if the nonblocking-flag is set.
 
      Also note that readpartial behaves similar to sysread in blocking
      mode. The behavior is identical when the buffer is empty.