# CSV::StreamBuf (Class)

In: | csv.rb
Parent: | Object

DESCRIPTION

      CSV::StreamBuf -- a class for a bufferd stream.

EXAMPLE 1 — an IO.

      class MyBuf < StreamBuf
        # Do initialize myself before a super class.  Super class might call my
        # method 'read'. (Could be awful for C++ user. :-)
        def initialize(s)
          @s = s
          super()
        end

        # define my own 'read' method.
        # CAUTION: Returning nil means EnfOfStream.
        def read(size)
          @s.read(size)
        end

        # release buffers. in Ruby which has GC, you do not have to call this...
        def terminate
          @s = nil
          super()
        end
      end

      buf = MyBuf.new(STDIN)
      my_str = ''
      p buf[0, 0]               # => '' (null string)
      p buf[0]                  # => 97 (char code of 'a')
      p buf[0, 1]               # => 'a'
      my_str = buf[0, 5]
      p my_str                  # => 'abcde' (5 chars)
      p buf[0, 6]               # => "abcde\n" (6 chars)
      p buf[0, 7]               # => "abcde\n" (6 chars)
      p buf.drop(3)             # => 3 (dropped chars)
      p buf.get(0, 2)           # => 'de' (2 chars)
      p buf.is_eos?             # => false (is not EOS here)
      p buf.drop(5)             # => 3 (dropped chars)
      p buf.is_eos?             # => true (is EOS here)
      p buf[0]                  # => nil (is EOS here)

EXAMPLE 2 — String.

      This is a conceptual example.  No pros with this.

      class StrBuf < StreamBuf
        def initialize(s)
          @str = s
          @idx = 0
          super()
        end

        def read(size)
          str = @str[@idx, size]
          @idx += str.size
          str
        end
      end

## Methods

[] drop get is_eos? new

## Constants

BufSize | = | 1024 * 8

## Public Class methods

new()

SYNOPSIS

      N/A

DESCRIPTION

      Do not instanciate this class directly.  Define your own class which
      derives this class and define 'read' instance method.

[Source]

    # File csv.rb, line 1234
        def initialize
          @buf_list = []
          @cur_buf = @buf_tail_idx = -1
          @offset = 0
          @is_eos = false
          add_buf
          @cur_buf = @buf_tail_idx
        end

## Public Instance methods

[](idx, n = nil)

SYNOPSIS

      char/str = CSV::StreamBuf#get(idx, n = nil)
      char/str = CSV::StreamBuf#[idx, n = nil]

ARGS

      idx: index of a string to specify a start point of a string to get.
        Unlike String instance, idx < 0 returns nil.
      n: size of a string to get.

RETURNS

      char: if n == nil.  A char at idx.
      str: if n != nil.  A partial string, from idx to (idx + size).  At
        EOF, the string size could not equal to arg n.

DESCRIPTION

      Get a char or a partial string from the stream.

[Source]

    # File csv.rb, line 1125
        def [](idx, n = nil)
          if idx < 0
            return nil
          end
          if (idx_is_eos?(idx))
            if n and (@offset + idx == buf_size(@cur_buf))
              # Like a String, 'abc'[4, 1] returns nil and

              # 'abc'[3, 1] returns '' not nil.

              return ''
            else
              return nil
            end
          end
          my_buf = @cur_buf
          my_offset = @offset
          next_idx = idx
          while (my_offset + next_idx >= buf_size(my_buf))
            if (my_buf == @buf_tail_idx)
              unless add_buf
                break
              end
            end
            next_idx = my_offset + next_idx - buf_size(my_buf)
            my_buf += 1
            my_offset = 0
          end
          loc = my_offset + next_idx
          if !n
            return @buf_list[my_buf][loc]           # Fixnum of char code.

          elsif (loc + n - 1 < buf_size(my_buf))
            return @buf_list[my_buf][loc, n]        # String.

          else # should do loop insted of (tail) recursive call...

            res = @buf_list[my_buf][loc, BufSize]
            size_added = buf_size(my_buf) - loc
            if size_added > 0
              idx += size_added
              n -= size_added
              ret = self[idx, n]
              if ret
                res << ret
              end
            end
            return res
          end
        end

get(idx, n = nil)

Alias for #[]

drop(n)

SYNOPSIS

      size_dropped = CSV::StreamBuf#drop(n)

ARGS

      n: drop size

RETURNS

      size_dropped: droped size.  At EOF, dropped size might not equals to arg n.
        0 if n <= 0.

DESCRIPTION

      Drop a string from the stream.  Once you drop the head of the stream,
      access to the dropped part via [] or get returns nil.

[Source]

    # File csv.rb, line 1186
        def drop(n)
          if is_eos?
            return 0
          end
          size_dropped = 0
          while (n > 0)
            if (!@is_eos || (@cur_buf != @buf_tail_idx))
              if (@offset + n < buf_size(@cur_buf))
                size_dropped += n
                @offset += n
                n = 0
              else
                size = buf_size(@cur_buf) - @offset
                size_dropped += size
                n -= size
                @offset = 0
                unless rel_buf
                  unless add_buf
                    break
                  end
                  @cur_buf = @buf_tail_idx
                end
              end
            end
          end
          size_dropped
        end

is_eos?()

SYNOPSIS

      is_eos = CSV::StreamBuf#is_eos?

RETURNS

      is_eos: true if end of the stream or false.

DESCRIPTION

      Check EOF or not.

[Source]

    # File csv.rb, line 1223
        def is_eos?
          return idx_is_eos?(0)
        end

[Validate]