Merge pull request #2647 from ksss/pread-pwrite

Add sig `IO#pread` and `IO#pwrite`

Author: ksss

core/io.rbs

@@ -1443,6 +1443,61 @@ class IO < Object
   #
   def puts: (*untyped objects) -> nil
 
+  # <!--
+  #   rdoc-file=io.c
+  #   - pread(maxlen, offset)             -> string
+  #   - pread(maxlen, offset, out_string) -> string
+  # -->
+  # Behaves like IO#readpartial, except that it:
+  #
+  # *   Reads at the given `offset` (in bytes).
+  # *   Disregards, and does not modify, the stream's position (see
+  #     [Position](rdoc-ref:IO@Position)).
+  # *   Bypasses any user space buffering in the stream.
+  #
+  # Because this method does not disturb the stream's state (its position, in
+  # particular), `pread` allows multiple threads and processes to use the same IO
+  # object for reading at various offsets.
+  #
+  #     f = File.open('t.txt')
+  #     f.read # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #     f.pos  # => 52
+  #     # Read 12 bytes at offset 0.
+  #     f.pread(12, 0) # => "First line\n"
+  #     # Read 9 bytes at offset 8.
+  #     f.pread(9, 8)  # => "ne\nSecon"
+  #     f.close
+  #
+  # Not available on some platforms.
+  #
+  def pread: (int maxlen, int offset, ?string out_string) -> String
+
+  # <!--
+  #   rdoc-file=io.c
+  #   - pwrite(object, offset) -> integer
+  # -->
+  # Behaves like IO#write, except that it:
+  #
+  # *   Writes at the given `offset` (in bytes).
+  # *   Disregards, and does not modify, the stream's position (see
+  #     [Position](rdoc-ref:IO@Position)).
+  # *   Bypasses any user space buffering in the stream.
+  #
+  # Because this method does not disturb the stream's state (its position, in
+  # particular), `pwrite` allows multiple threads and processes to use the same IO
+  # object for writing at various offsets.
+  #
+  #     f = File.open('t.tmp', 'w+')
+  #     # Write 6 bytes at offset 3.
+  #     f.pwrite('ABCDEF', 3) # => 6
+  #     f.rewind
+  #     f.read # => "\u0000\u0000\u0000ABCDEF"
+  #     f.close
+  #
+  # Not available on some platforms.
+  #
+  def pwrite: (_ToS object, int offset) -> Integer
+
   # <!--
   #   rdoc-file=io.c
   #   - read(maxlen = nil, out_string = nil) -> new_string, out_string, or nil

test/stdlib/IO_test.rb

@@ -484,6 +484,40 @@ def test_readline
                        io, :readline, "\n", 100, chomp: true
     end
   end
+
+  def test_pwrite
+    Dir.mktmpdir do |dir|
+      File.open(File.join(dir, "io-pwrite"), "w") do |io|
+        with_int(0) do |offset|
+          assert_send_type "(String, int) -> Integer",
+                          io, :pwrite, "hello", offset
+        end
+      end
+    end
+  rescue NotImplementedError
+    omit "Not implemented"
+  end
+
+  def test_pread
+    IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
+      with_int(10) do |maxlen|
+        with_int(0) do |offset|
+          assert_send_type(
+            "(int, int) -> String",
+            io, :pread, maxlen, offset
+          )
+          with_string(+"buffer") do |buffer|
+            assert_send_type(
+              "(int, int, string) -> String",
+              io, :pread, maxlen, offset, buffer
+            )
+          end
+        end
+      end
+    end
+  rescue NotImplementedError
+    omit "Not implemented"
+  end
 end
 
 class IOWaitTest < Test::Unit::TestCase