diff --git a/io_buffer.c b/io_buffer.c index 22d68d82f0b..012de4759d1 100644 --- a/io_buffer.c +++ b/io_buffer.c @@ -1667,22 +1667,23 @@ rb_io_buffer_locked(VALUE self) * * for a buffer created from scratch: free memory. * * for a buffer created from string: undo the association. * - * After the buffer is freed, no further operations can be performed on it. + * After releasing any referenced memory, the buffer is reset to a valid, + * empty, null state. It has no backing storage and its size is zero. + * Zero-length operations remain valid, while operations requiring bytes fail + * normal bounds checking. * - * You can resize a freed buffer to re-allocate it. + * You can resize the buffer to allocate new storage. * * buffer = IO::Buffer.for('test') * buffer.free * # => # * - * buffer.get_value(:U8, 0) - * # in `get_value': The buffer is not allocated! (IO::Buffer::AllocationError) + * buffer.null? # => true + * buffer.empty? # => true + * buffer.valid? # => true + * buffer.get_string # => "" * - * buffer.get_string - * # in `get_string': The buffer is not allocated! (IO::Buffer::AllocationError) - * - * buffer.null? - * # => true + * buffer.get_value(:U8, 0) # raises ArgumentError */ VALUE rb_io_buffer_free(VALUE self) diff --git a/spec/ruby/core/io/buffer/free_spec.rb b/spec/ruby/core/io/buffer/free_spec.rb index 20fb7b901f4..11613ec56b2 100644 --- a/spec/ruby/core/io/buffer/free_spec.rb +++ b/spec/ruby/core/io/buffer/free_spec.rb @@ -69,6 +69,18 @@ describe "IO::Buffer#free" do buffer.null?.should == true end + ruby_version_is "3.4" do + it "resets the buffer to a valid empty state" do + buffer = IO::Buffer.new(4) + buffer.free + + buffer.null?.should == true + buffer.empty?.should == true + buffer.valid?.should == true + buffer.get_string.should == "" + end + end + it "is disallowed while locked, raising IO::Buffer::LockedError" do buffer = IO::Buffer.new(4) buffer.locked do