diff options
author | Victor Shepelev <zverok.offline@gmail.com> | 2022-12-24 00:48:58 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-12-24 11:48:58 +1300 |
commit | c3c116f6a6b92d0224b35e7423959a7ab39ddc6b (patch) | |
tree | ca2dc80b919a87835a6abdb1f1630d9c3f0ff7a7 /io_buffer.c | |
parent | 11ad9a42d76ba785b2ec93f327469ead9b810ef4 (diff) |
[DOC] Document new methods of IO::Buffer and Fiber::Scheduler (#7016)
Co-authored-by: Samuel Williams <samuel.williams@oriontransfer.co.nz>
Notes
Notes:
Merged-By: ioquatix <samuel@codeotaku.com>
Diffstat (limited to 'io_buffer.c')
-rw-r--r-- | io_buffer.c | 79 |
1 files changed, 69 insertions, 10 deletions
diff --git a/io_buffer.c b/io_buffer.c index d866c967b7..c5f0b193c3 100644 --- a/io_buffer.c +++ b/io_buffer.c @@ -2415,10 +2415,10 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset) } /* - * call-seq: read(io, [length, [offset]]) -> self + * call-seq: read(io, [length, [offset]]) -> read length or -errno * * Read at most +length+ bytes from +io+ into the buffer, starting at - * +offset+. + * +offset+. If an error occurs, return <tt>-errno</tt>. * * If +length+ is not given, read until the end of the buffer. * @@ -2428,14 +2428,17 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset) * * Example: * - * buffer = IO::Buffer.for('test') - * # => - * # <IO::Buffer 0x00007fca40087c38+4 SLICE> - * # 0x00000000 74 65 73 74 test - * buffer.read(File.open('/dev/urandom', 'rb'), 4) - * # => - * # <IO::Buffer 0x00007fca40087c38+4 SLICE> - * # 0x00000000 2a 0e 0e 0e *... + * IO::Buffer.for('test') do |buffer| + * p buffer + * # => + * # <IO::Buffer 0x00007fca40087c38+4 SLICE> + * # 0x00000000 74 65 73 74 test + * buffer.read(File.open('/dev/urandom', 'rb'), 2) + * p buffer + * # => + * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE> + * # 0x00000000 05 35 73 74 .5st + * end */ static VALUE io_buffer_read(int argc, VALUE *argv, VALUE self) @@ -2536,6 +2539,32 @@ rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t of return rb_thread_io_blocking_region(io_buffer_pread_internal, &argument, descriptor); } +/* + * call-seq: pread(io, from, length, [offset]) -> read length or -errno + * + * Read at most +length+ bytes from +io+ into the buffer, starting at + * +from+, and put it in buffer starting from specified +offset+. + * If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, put it at the beginning of the buffer. + * + * Example: + * + * IO::Buffer.for('test') do |buffer| + * p buffer + * # => + * # <IO::Buffer 0x00007fca40087c38+4 SLICE> + * # 0x00000000 74 65 73 74 test + * + * # take 2 bytes from the beginning of urandom, + * # put them in buffer starting from position 2 + * buffer.pread(File.open('/dev/urandom', 'rb'), 0, 2, 2) + * p buffer + * # => + * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE> + * # 0x00000000 05 35 73 74 te.5 + * end + */ static VALUE io_buffer_pread(int argc, VALUE *argv, VALUE self) { @@ -2610,6 +2639,20 @@ rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset) return rb_thread_io_blocking_region(io_buffer_write_internal, &argument, descriptor); } +/* + * call-seq: write(io, length, [offset]) -> written length or -errno + * + * Writes +length+ bytes from buffer into +io+, starting at + * +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, the bytes are taken from the beginning + * of the buffer. + * + * out = File.open('output.txt', 'wb') + * IO::Buffer.for('1234567').write(out, 3) + * + * This leads to +123+ being written into <tt>output.txt</tt> + */ static VALUE io_buffer_write(int argc, VALUE *argv, VALUE self) { @@ -2709,6 +2752,22 @@ rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t o return rb_thread_io_blocking_region(io_buffer_pwrite_internal, &argument, descriptor); } +/* + * call-seq: pwrite(io, from, length, [offset]) -> written length or -errno + * + * Writes +length+ bytes from buffer into +io+, starting at + * +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, the bytes are taken from the beginning of the + * buffer. If the +offset+ is given and is beyond the end of the file, the + * gap will be filled with null (0 value) bytes. + * + * out = File.open('output.txt', File::RDWR) # open for read/write, no truncation + * IO::Buffer.for('1234567').pwrite(out, 2, 3, 1) + * + * This leads to +234+ (3 bytes, starting from position 1) being written into + * <tt>output.txt</tt>, starting from file position 2. + */ static VALUE io_buffer_pwrite(int argc, VALUE *argv, VALUE self) { |