lib/bio-bgzf/reader.rb in bio-bgzf-0.1.1 vs lib/bio-bgzf/reader.rb in bio-bgzf-0.2.0

@@ -8,18 +8,36 @@
     def initialize(f)
       @f = f
       @cur_block = nil
     end
 
+    # Returns the reader's current virtual offset. Between
+    # {#read_block} calls, the file position will always be at the
+    # start of a block or at EOF, so the low 16 bits of the virtual
+    # offset will always be zero.
+    #
+    # @return [Integer] virtual offset for current position
     def tell
       f.tell << 16
     end
 
+    # Reads the BGZF block at the current position. Returns its
+    # decompressed data.
+    #
+    # @return [String] decompressed block data
     def read_block
       decompress_block(f)
     end
 
+    # Reads a portion of a BGZF block, starting from the given virtual
+    # offset. If the offset is the start of a block (low 16 bits are
+    # zero) the entire block's data will be returned. Otherwise, the
+    # subset of the data starting at the given offset will be
+    # returned.
+    #
+    # @param [Integer] vo virtual offset to start from
+    # @return [String] decompressed block data
     def read_block_at(vo)
       block_offset = vo_block_offset(vo)
       data_offset = vo_data_offset(vo)
       f.seek(block_offset)
       block_data = decompress_block(f)
@@ -28,13 +46,17 @@
       else
         return block_data.slice(data_offset...block_data.size)
       end
     end
 
+    # Iterates over the blocks in a BGZF file, yielding [block, vo] pairs where 
     def each_block
       if block_given?
-        while b = read_block
-          yield b
+        while true
+          pos = tell
+          b = read_block
+          break unless b
+          yield b, pos
         end
       else
         enum_for(:each_block)
       end
     end