RUBY-2435 Document & test ByteBuffer length decreasing after reads (#223)

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

ext/bson/init.c

@@ -56,6 +56,16 @@ void Init_bson_native()
 
   rb_define_alloc_func(rb_byte_buffer_class, rb_bson_byte_buffer_allocate);
   rb_define_method(rb_byte_buffer_class, "initialize", rb_bson_byte_buffer_initialize, -1);
+
+  /*
+   * call-seq:
+   *   buffer.length -> Fixnum
+   *
+   * Returns the number of bytes available to be read in the buffer.
+   *
+   * When a buffer is being written to, each added byte increases its length.
+   * When a buffer is being read from, each read byte decreases its length.
+   */
   rb_define_method(rb_byte_buffer_class, "length", rb_bson_byte_buffer_length, 0);
 
   /*

spec/bson/byte_buffer_spec.rb

@@ -42,7 +42,6 @@
       end
     end
 
-
     context 'when the byte buffer is initialized with some bytes' do
 
       let(:buffer) do
@@ -53,6 +52,19 @@
         expect(buffer.length).to eq(2)
       end
     end
+
+    context 'after the byte buffer was read from' do
+
+      let(:buffer) do
+        described_class.new({}.to_bson.to_s)
+      end
+
+      it 'returns the number of bytes remaining in the buffer' do
+        expect(buffer.length).to eq(5)
+        buffer.get_int32
+        expect(buffer.length).to eq(1)
+      end
+    end
   end
 
   describe '#rewind!' do