Golang bufio包Scanner源码

浅浅的花香味﹌ 2022-11-25 11:44 205阅读 0赞

Go jdk版本1.10.3  Scanner源码在bufio包中的scan.go文件中

### 一、**Scanner介绍** ###

Scanner提供一个按指定规则来读取数据的缓冲区IO，比如通过”行匹配函数”来逐行读取数据，Scanner通过Scan方法来按”匹配函数”读取数。

Scan方法会通过一个“匹配函数”读取数据中符合要求的部分，跳过不符合要求的部分。

“匹配函数”由调用者指定。本包中提供的匹配函数有"行匹配函数"、"字节匹配函数"、"字符匹配函数"、"单词匹配函数"，用户也可以自定义"匹配函数"。默认的匹配函数为"行匹配函数"，用于获取数据中的一行内容(不包括行尾标记)。

Scanner使用了缓存，所以匹配部分的长度不能超出缓存的容量。默认缓存容量为bufio.MaxScanTokenSize，用户可以通过Buffer方法指定缓存及最大容量

Scan方法 在遇到下面的情况时会终止扫描并返回 false（扫描一旦终止，将无法再继续）：

1、遇到 io.EOF

2、遇到读写错误

3、“匹配部分”的长度超过了缓存的长度

## ##

### **二、Scanner源码** ###

**结构体**

type Scanner struct {
       r            io.Reader // The reader provided by the client.  由用户提供的io.Reader
       split        SplitFunc // The function to split the tokens.  用于拆分tokens的函数(匹配函数，默认是行匹配)
       maxTokenSize int       // Maximum size of a token; modified by tests.   token的最大长度
       token        []byte    // Last token returned by split.  记录最后一次Scan操作匹配到的数据
       buf          []byte    // Buffer used as argument to split.
       start        int       // First non-processed byte in buf. 记录缓冲区buf中第一个未处理(扫描过)的位置
       end          int       // End of data in buf.  记录buf的结束位置
       err          error     // Sticky error.
       empties      int       // Count of successive empty tokens.  记录匹配到空数据的次数，如果超过指定maxConsecutiveEmptyReads次数，则会panic
       scanCalled   bool      // Scan has been called; buffer is in use.   标记Scan方法是否已经调用过，如果已经调用过则置为true，说明buffer在正在使用。
       done         bool      // Scan has finished.  标记是否已经扫描结束
    }

type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)

SplitFunc用来定义"匹配函数"类型，data是缓存中的数据，atEOF标记数据是否读完。

advance返回data中已处理的数据的长度。token返回找到的"匹配部分"数据,"匹配部分"可以是缓存的切片，也可以是自己新建的数据(比如bufio.errorRune)。"匹配部分"将在Scan之后通过Bytes和Text反馈给用户。err返回错误信息

如果在 data 中无法找到一个完整的“匹配部分”则应返回 (0, nil, nil)，以便告诉Scanner 向缓存中填充更多数据，然后再次扫描（Scan 会自动重新扫描）。如果缓存已经达到最大容量还没有找到，则 Scan 会终止并返回 false。

如果 data 为空，则“匹配函数”将不会被调用，意思是在“匹配函数”中不必考虑data 为空的情况。

如果 err != nil，扫描将终止，如果 err == ErrFinalToken，则 Scan 将返回 true，表示扫描正常结束，如果 err 是其它错误，则 Scan 将返回 false，表示扫描出错。错误信息可以在 Scan 之后通过 Err 方法获取。

SplitFunc 的作用很简单，从 data 中找出你感兴趣的数据，然后返回，同时返回已经处理的数据的长度。

**初始化Scanner**

func NewScanner(r io.Reader) *Scanner {
       return &Scanner{
          r:            r,
          split:        ScanLines,
          maxTokenSize: MaxScanTokenSize,
       }
    }

NewScanner函数用于初始化一个Scanner对象，NewScanner返回一个新的Scanner来扫描r，默认匹配函数为ScanLines（行匹配函数）

func (s *Scanner) Buffer(buf []byte, max int) {
       if s.scanCalled {
          panic("Buffer called after Scan")
       }
       s.buf = buf[0:cap(buf)]
       s.maxTokenSize = max
    }

Buffer方法用于指定该Scanner的缓冲区大小和最大可扩展的范围(即maxTokenSize)，如果max小于len(buf)，则buf的尺寸将固定不可调。

Buffer必须在第一次Scan之前设置，否则会引发panic

func (s *Scanner) Split(split SplitFunc) {
       if s.scanCalled {
          panic("Split called after Scan")
       }
       s.split = split
    }

Split用于设置匹配函数，初始化Scanner的时候默认的匹配函数为ScanLines（行匹配函数），如果想使用其他的匹配函数可以通过该方法设置。

Spit方法也必须在调用Scan前执行，否则会引起panic

**获取匹配(Scan)的结果**

func (s *Scanner) Err() error {
    	if s.err == io.EOF {
    		return nil
    	}
    	return s.err
    }

该Err方法 返回扫描过程中遇到的非 EOF 错误，供用户调用，以便获取错误信息。

// Bytes returns the most recent token generated by a call to Scan.
    // The underlying array may point to data that will be overwritten
    // by a subsequent call to Scan. It does no allocation.
    func (s *Scanner) Bytes() []byte {
    	return s.token
    }

Bytes方法将最后一次扫描出的“匹配部分”作为一个切片引用返回，下一次的 Scan 操作会覆盖本次引用的内容。

// Text returns the most recent token generated by a call to Scan
    // as a newly allocated string holding its bytes.
    func (s *Scanner) Text() string {
    	return string(s.token)
    }

Text方法返回最后一次扫描出的"匹配部分"作为字符串返回

核心的匹配方法Scan

func (s *Scanner) Scan() bool {
       if s.done {
          return false
       }
       s.scanCalled = true
       // Loop until we have a token.
       for {
          // See if we can get a token with what we already have.
          // If we've run out of data but have an error, give the split function
          // a chance to recover any remaining, possibly empty token.
          if s.end > s.start || s.err != nil { //如果缓冲区的结束位置 >  缓冲区未扫描的位置 或者err不为nil
             advance, token, err := s.split(s.buf[s.start:s.end], s.err != nil)  //尝试去缓冲区扫描匹配
             if err != nil {
                if err == ErrFinalToken {
                   s.token = token
                   s.done = true
                   return true
                }
                s.setErr(err)
                return false
             }
             if !s.advance(advance) {
                return false
             }
             s.token = token  //记录本次匹配的token
             if token != nil {
                if s.err == nil || advance > 0 {  //当有匹配的token，并且扫描的长度大于0，则置空empties
                   s.empties = 0   //emptis是记录连续匹配到为空的次数
                } else { //匹配到空数据
                   // Returning tokens not advancing input at EOF.
                   s.empties++
                   if s.empties > maxConsecutiveEmptyReads {
                      panic("bufio.Scan: too many empty tokens without progressing")
                   }
                }
                return true
             }
          }
          // We cannot generate a token with what we are holding.
          // If we've already hit EOF or an I/O error, we are done.
          if s.err != nil {
             // Shut it down.
             s.start = 0
             s.end = 0
             return false
          }
          // Must read more data.
          // First, shift data to beginning of buffer if there's lots of empty space
          // or space is needed.
          /*
          当start> 0 并且  s.end等于整个缓冲区的长度，或者start>0 并且 start大于缓冲区的一半
          则将未扫描的部分 移到 缓冲区的开头
          */
          if s.start > 0 && (s.end == len(s.buf) || s.start > len(s.buf)/2) {
             copy(s.buf, s.buf[s.start:s.end])
             s.end -= s.start
             s.start = 0
          }
          // Is the buffer full? If so, resize.
          /*
          如果缓冲区已满，
              1.如果缓冲区buf的长度已经大于等于maxTokenSize，或者缓冲区buf的长度大于maxInt的一半，则无法扩容
              2.将缓冲区扩大到现在缓冲区的2倍和maxTokenSize中的最小者，并设置start和end的值
          */
          if s.end == len(s.buf) {
             // Guarantee no overflow in the multiplication below.
             const maxInt = int(^uint(0) >> 1)
             if len(s.buf) >= s.maxTokenSize || len(s.buf) > maxInt/2 {
                s.setErr(ErrTooLong)
                return false
             }
             newSize := len(s.buf) * 2
             if newSize == 0 {
                newSize = startBufSize
             }
             if newSize > s.maxTokenSize {
                newSize = s.maxTokenSize
             }
             newBuf := make([]byte, newSize)
             copy(newBuf, s.buf[s.start:s.end])
             s.buf = newBuf
             s.end -= s.start
             s.start = 0
          }
          // Finally we can read some input. Make sure we don't get stuck with
          // a misbehaving Reader. Officially we don't need to do this, but let's
          // be extra careful: Scanner is for safe, simple jobs.
          //从输入流Reader中读取数据到缓冲区中
          for loop := 0; ; {
             n, err := s.r.Read(s.buf[s.end:len(s.buf)])
             s.end += n
             if err != nil {
                s.setErr(err)
                break
             }
             if n > 0 {
                s.empties = 0
                break
             }
             loop++
             if loop > maxConsecutiveEmptyReads {
                s.setErr(io.ErrNoProgress)
                break
             }
          }
       }
    }

Scan开始一次扫描匹配，如果匹配成功，可以通过Bytes()或Text()方法取出结果，如果遇到错误，则终止扫描，并返回false。

func (s *Scanner) advance(n int) bool {
       if n < 0 {
          s.setErr(ErrNegativeAdvance)
          return false
       }
       if n > s.end-s.start {
          s.setErr(ErrAdvanceTooFar)
          return false
       }
       s.start += n
       return true
    }

该advance方法用于Scan操作扫描了n个字节，这里会设置start的索引位置

**bufio中内置的匹配函数**

func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error) {
       if atEOF && len(data) == 0 {
          return 0, nil, nil
       }
       return 1, data[0:1], nil
    }

ScanBytes 函数是"字节匹配"函数，扫描下一个字节

func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error) {
       if atEOF && len(data) == 0 {
          return 0, nil, nil
       }
    
       // Fast path 1: ASCII.
       if data[0] < utf8.RuneSelf {
          return 1, data[0:1], nil
       }
    
       // Fast path 2: Correct UTF-8 decode without error.
       _, width := utf8.DecodeRune(data)
       if width > 1 {
          // It's a valid encoding. Width cannot be one for a correctly encoded
          // non-ASCII rune.
          return width, data[0:width], nil
       }
    
       // We know it's an error: we have width==1 and implicitly r==utf8.RuneError.
       // Is the error because there wasn't a full rune to be decoded?
       // FullRune distinguishes correctly between erroneous and incomplete encodings.
       if !atEOF && !utf8.FullRune(data) {
          // Incomplete; get more bytes.
          return 0, nil, nil
       }
    
       // We have a real UTF-8 encoding error. Return a properly encoded error rune
       // but advance only one byte. This matches the behavior of a range loop over
       // an incorrectly encoded string.
       return 1, errorRune, nil
    }

ScanRunes函数 是"字符匹配"函数,扫描下一个字符

func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error) {
       if atEOF && len(data) == 0 { //已经扫描结束
          return 0, nil, nil
       }
       if i := bytes.IndexByte(data, '\n'); i >= 0 {//如果缓冲区data中可以找到'\n'换行结束符
          // We have a full newline-terminated line.
          return i + 1, dropCR(data[0:i]), nil
       }
       // If we're at EOF, we have a final, non-terminated line. Return it.
       if atEOF {  //如果没有找到换行符，并且atEOF为true，则说明已经EOF，扫描结束，并返回剩余的数据
          return len(data), dropCR(data), nil
       }
       // Request more data.
       return 0, nil, nil
    }

ScanLines函数是一个"行匹配函数"，用来找出data中的单行数据并返回(包括空行)，返回值不包含行尾标记(\\n或\\r\\n)，advance返回data中已处理的数据长度，该函数也是NewScanner初始化Scanner时默认的匹配函数。

func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error) {
       // Skip leading spaces.
       start := 0
       for width := 0; start < len(data); start += width {
          var r rune
          r, width = utf8.DecodeRune(data[start:])
          if !isSpace(r) {
             break
          }
       }
       // Scan until space, marking end of word.
       for width, i := 0, start; i < len(data); i += width {
          var r rune
          r, width = utf8.DecodeRune(data[i:])
          if isSpace(r) {
             return i + width, data[start:i], nil
          }
       }
       // If we're at EOF, we have a final, non-empty, non-terminated word. Return it.
       if atEOF && len(data) > start {
          return len(data), data[start:], nil
       }
       // Request more data.
       return start, nil, nil
    }

ScanWords函数是"单词匹配"函数，它返回每个以空格分割的单词，并删除周围的空格。不会返回一个空字符串。