轉載自https://www.cnblogs.com/golove/p/5888441.html
標準庫 - fmt/scan.go 解讀
// Copyright 2010 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// go/src/fmt/scan.go
// version 1.7
// 格式化輸入輸出的用法請參考：http://www.cnblogs.com/golove/p/3284304.html
package fmt
import (
"errors"
"io"
"math"
"os"
"reflect"
"strconv"
"sync"
"unicode/utf8"
)
// ScanState 將掃描器的狀態報告給自定義類型的 Scan 方法。
type ScanState interface {
// ReadRune 從輸入端讀取一個字符，如果用在 Scanln 類的掃描器中，
// 則該方法會在讀到第一個換行符之後或讀到指定寬度之後返回 EOF。
// r ：讀取的字符
// size：字符所佔用的字節數
// err ：遇到的錯誤信息
ReadRune() (r rune, size int, err error)
// UnreadRune 撤消最後一次的 ReadRune 操作，
// 使下次的 ReadRune 操作得到與前一次 ReadRune 相同的結果。
// 返回：遇到的錯誤信息
UnreadRune() error
// SkipSpace 爲自定義的 Scan 方法提供跳過開頭空白的能力。
// 根據掃描器的不同（Scan 或 Scanln）決定是否跳過換行符。
SkipSpace()
// Token 用於從輸入端讀取符合要求的字符串，準備解析。
// Token 從輸入端讀取連續的符合 f(c) 的字符 c。如果 f 爲 nil，則使用
// !unicode.IsSpace(c) 代替 f(c)。
// skipSpace：是否跳過輸入端開頭的連續空白（通過 SkipSpace 方法）。
// token ：存放讀取到的數據。
// err ：遇到的錯誤信息。
// 注意：token 指向共享的數據，下次的 Token 操作可能會覆蓋本次的結果。
Token(skipSpace bool, f func(rune) bool) (token []byte, err error)
// Width 返回佔位符中指定的寬度值（寬度值是字符個數，不是字節個數）。
// wid：獲取到的寬度值
// ok ：是否指定了寬度值
Width() (wid int, ok bool)
// 因爲上面實現了 ReadRune 方法，所以 Read 方法永遠不應該被 Scan 方法調用。
// 一個好的 ScanState 應該讓 Read 直接返回相應的錯誤信息。
Read(buf []byte) (n int, err error)
}
// Scanner 用於讓自定義類型實現自己的掃描過程。
// Scan 方法會從輸入端讀取數據並將處理結果存入接收端，接收端必須是有效的指針。
// Scan 方法會被掃描器調用，只要對應的 arg 實現了該方法。
type Scanner interface {
Scan(state ScanState, verb rune) error
}
// Scan 從標準輸入中讀取字符串（以空白分隔的值的序列）並解析爲具體的值，
// 存入參數 a 所提供的變量中（參數 a 必須提供變量的地址）。換行視爲空白。
// 當讀到 EOF 或所有變量都填寫完畢則停止掃描。
// n ：成功解析的參數數量
// err：解析過程中遇到的錯誤信息
func Scan(a ...interface{}) (n int, err error) {
return Fscan(os.Stdin, a...)
}
// Scanln 和 Scan 類似，只不過遇到換行符就停止掃描。
func Scanln(a ...interface{}) (n int, err error) {
return Fscanln(os.Stdin, a...)
}
// Scanf 從標準輸入中讀取字符串，並根據格式字符串 format 對讀取的數據進行解析，
// 存入參數 a 所提供的變量中（參數 a 必須提供變量的地址）。
// 輸入端的換行符必須和格式字符串中的換行符相對應（如果格式字符串中有換行符，則
// 輸入端必須輸入相應的換行符）。
// 佔位符 %c 總是匹配下一個字符，包括空白，比如空格符、製表符、換行符。
// n ：成功解析的參數數量
// err：解析過程中遇到的錯誤信息
func Scanf(format string, a ...interface{}) (n int, err error) {
return Fscanf(os.Stdin, format, a...)
}
// 實現了 Reader 接口的字符串類型
type stringReader string
func (r *stringReader) Read(b []byte) (n int, err error) {
n = copy(b, *r)
*r = (*r)[n:]
if n == 0 {
err = io.EOF
}
return
}
// Sscan 和 Scan 類似，只不過從 str 中讀取數據。
func Sscan(str string, a ...interface{}) (n int, err error) {
return Fscan((*stringReader)(&str), a...)
}
// Sscanln 和 Scanln 類似，只不過從 str 中讀取數據。
func Sscanln(str string, a ...interface{}) (n int, err error) {
return Fscanln((*stringReader)(&str), a...)
}
// Sscanf 和 Scanf 類似，只不過從 str 中讀取數據。
func Sscanf(str string, format string, a ...interface{}) (n int, err error) {
return Fscanf((*stringReader)(&str), format, a...)
}
// Fscan 和 Scan 類似，只不過從 r 中讀取數據。
func Fscan(r io.Reader, a ...interface{}) (n int, err error) {
s, old := newScanState(r, true, false) // 創建掃描器
n, err = s.doScan(a) // 開始掃描
s.free(old) // 回收掃描器
return
}
// Fscanln 和 Fcanln 類似，只不過從 r 中讀取數據。
func Fscanln(r io.Reader, a ...interface{}) (n int, err error) {
s, old := newScanState(r, false, true) // 創建掃描器
n, err = s.doScan(a) // 開始掃描
s.free(old) // 回收掃描器
return
}
// Fscanf 和 Scanf 類似，只不過從 r 中讀取數據。
func Fscanf(r io.Reader, format string, a ...interface{}) (n int, err error) {
s, old := newScanState(r, false, false) // 創建掃描器
n, err = s.doScanf(format, a) // 開始掃描
s.free(old) // 回收掃描器
return
}
// scanError 聲明本地錯誤類型，用於 recover 時辨別 panic 是否由本地代碼產生的。
type scanError struct {
err error
}
// 本地代碼用 -1 表示遇到 EOF
const eof = -1
// ss 是掃描器，整個掃描過程都是由它完成的。
// 它從 rs 中讀取數據並進行解析。
type ss struct {
rs io.RuneScanner // 輸入端
buf buffer // 緩衝區
count int // 已讀取的字符數
atEOF bool // 是否讀到 EOF
ssave // 一些需要經常復位的字段
}
// ssave 是 ss 的一部分，存儲一些需要經常復位的字段
type ssave struct {
validSave bool // 平時用不上，遞歸時使用
nlIsEnd bool // 是否在換行符之後停止讀取
nlIsSpace bool // 是否將換行符視爲空白
argLimit int // 已讀的字符數不能超過 argLimit（argLimit <= limit）
limit int // 已讀的字符數不能超過 limit（好像就當做常量在使用，用於復位 argLimit）
maxWid int // 存儲佔位符中指定的寬度值
}
// 實現 ScanState 接口
// Read 方法僅用於 ScanState 以滿足 io.Reader 接口。
// 在內部永遠不會調用它，所以沒有必要讓它有任何動作。
func (s *ss) Read(buf []byte) (n int, err error) {
return 0, errors.New("ScanState's Read should not be called. Use ReadRune")
}
// 實現 ScanState 接口
func (s *ss) ReadRune() (r rune, size int, err error) {
// 讀到 EOF 或超出讀取限制，則返回 0 0 nil
if s.atEOF || s.count >= s.argLimit {
err = io.EOF
return
}
r, size, err = s.rs.ReadRune()
if err == nil {
s.count++ // 統計被讀出的字符數
if s.nlIsEnd && r == '\n' {
s.atEOF = true // 拒絕再次 ReadRune
}
} else if err == io.EOF {
s.atEOF = true // 拒絕再次 ReadRune
}
return
}
// 實現 ScanState 接口
func (s *ss) Width() (wid int, ok bool) {
if s.maxWid == hugeWid { // hugeWid 是常量 1 << 30
return 0, false
}
return s.maxWid, true
}
// 讀取一個字符，如果遇到 EOF 則返回 eof（即 -1）
// 如果遇到其它錯誤，則中止整個掃描過程，返回 err。
func (s *ss) getRune() (r rune) {
r, _, err := s.ReadRune()
if err != nil {
if err == io.EOF {
return eof
}
s.error(err)
}
return
}
// 功能同 getRune，只不過遇到 EOF 也中止整個掃描過程，返回 err。
func (s *ss) mustReadRune() (r rune) {
r = s.getRune()
if r == eof {
s.error(io.ErrUnexpectedEOF)
}
return
}
// 實現 ScanState 接口
func (s *ss) UnreadRune() error {
s.rs.UnreadRune()
s.atEOF = false // 允許再次 ReadRune
s.count-- // 統計被讀出的字符數
return nil // UnreadRune 可以反覆調用，不返回錯誤信息。
}
// 將錯誤信息轉換爲 panic。
// 用於配合 recover 快速結束函數調用鏈，避免過多的返回值判斷。
// 類似於 break label 的用法。
func (s *ss) error(err error) {
panic(scanError{err})
}
// 作用同上面的 error 方法
func (s *ss) errorString(err string) {
panic(scanError{errors.New(err)})
}
// 實現 ScanState 接口
func (s *ss) Token(skipSpace bool, f func(rune) bool) (tok []byte, err error) {
// 遇到本地錯誤則僅僅返回 err 信息。
// 遇到其它錯誤則 panic。
defer func() {
if e := recover(); e != nil {
if se, ok := e.(scanError); ok {
err = se.err
} else {
panic(e)
}
}
}()
// 確定審查函數
if f == nil {
f = notSpace
}
// 準備緩衝區給 s.token 用
s.buf = s.buf[:0]
tok = s.token(skipSpace, f)
return
}
// space 是 unicode.White_Space 的拷貝，避免包的深度依賴。
// 這些都是空白字符的 Unicode 碼點範圍
var space = [][2]uint16{
{0x0009, 0x000d},
{0x0020, 0x0020},
{0x0085, 0x0085},
{0x00a0, 0x00a0},
{0x1680, 0x1680},
{0x2000, 0x200a},
{0x2028, 0x2029},
{0x202f, 0x202f},
{0x205f, 0x205f},
{0x3000, 0x3000},
}
// 判斷 r 是否爲空白字符
func isSpace(r rune) bool {
// 空白字符的碼點不會超過 2 個字節
if r >= 1<<16 {
return false
}
// 開始判斷
rx := uint16(r)
for _, rng := range space {
if rx < rng[0] {
return false
}
if rx <= rng[1] {
return true
}
}
return false
}
// notSpace 是 Token 中的默認審查函數。
func notSpace(r rune) bool {
return !isSpace(r)
}
// 實現 ScanState 接口
func (s *ss) SkipSpace() {
s.skipSpace(false)
}
// readRune 用於將 io.Reader 包裝成 io.RuneScanner
type readRune struct {
reader io.Reader // 被包裝的 io.Reader
buf [utf8.UTFMax]byte // 僅在 ReadRune 方法中使用
pending int // pendBuf 中存放的字節數，遇到無效 UTF8 編碼時使用。
pendBuf [utf8.UTFMax]byte // 存放讀取的無效 UTF-8 編碼，一次處理不完，留着下次處理
peekRune rune // 用於 UnreadRune 存放撤銷的字符。
}
// readByte 讀取一個字節
// 它可能是上次 ReadRune 時未處理完的不完整 UTF8 編碼。
func (r *readRune) readByte() (b byte, err error) {
// 如果之前的 ReadRune 有未處理完的字節，則重新讀出這些字節。
if r.pending > 0 {
// 讀出一個字節
b = r.pendBuf[0]
// 剩下的字節向前移動一格
copy(r.pendBuf[0:], r.pendBuf[1:])
r.pending--
return
}
// 如果沒有未處理的字節，則從輸入端讀出一個字節
n, err := io.ReadFull(r.reader, r.pendBuf[:1])
if n != 1 {
return 0, err
}
return r.pendBuf[0], err
}
// 實現 io.RuneScanner 接口
func (r *readRune) ReadRune() (rr rune, size int, err error) {
// 之前 UnreadRune 撤銷的字符，存在 peekRune 中，有則直接取出。
if r.peekRune >= 0 {
rr = r.peekRune
// 將 peekRune 取反爲負數，表示允許 UnreadRune 執行撤銷操作
r.peekRune = ^r.peekRune
size = utf8.RuneLen(rr)
return
}
// 沒有撤銷的字符，則從輸入端讀取一個
r.buf[0], err = r.readByte()
if err != nil {
return
}
// 如果讀出的是一個單字節字符，則讀取完畢。
if r.buf[0] < utf8.RuneSelf {
rr = rune(r.buf[0])
size = 1
// 將讀出的內容寫入 peekRune 後取反，以便 UnreadRune 可以撤銷。
r.peekRune = ^rr
return
}
// 讀出的不是單字節字符
var n int
// FullRune 的功能不太好理解，總的來說，就是判斷首字符的編碼長度是否完整，
// 如果不完整則返回 false，其它情況都返回 true（包括無效編碼）。
// 循環直到 r.buf[:n] 是完整的 UTF-8 編碼（或無效編碼）
for n = 1; !utf8.FullRune(r.buf[:n]); n++ {
// 如果字符編碼長度不夠，則再讀出一個字節，繼續判斷
r.buf[n], err = r.readByte()
if err != nil {
if err == io.EOF {
err = nil // 之前有讀出的字節未處理，跳出去處理
break
}
return
}
}
// 解碼剛讀出的 UTF-8 序列
rr, size = utf8.DecodeRune(r.buf[:n])
if size < n {
// 遇到錯誤，保存未處理的字節，用於下一次讀取。
copy(r.pendBuf[r.pending:], r.buf[size:n])
r.pending += n - size
}
// 將讀出的內容寫入 peekRune 後取反，以便 UnreadRune 可以撤銷。
r.peekRune = ^rr
return
}
// 實現 io.RuneScanner 接口
func (r *readRune) UnreadRune() error {
// 之前執行過 UnreadRune，不能重複執行。
// 只有 UnreadRune 才能讓 peekRune 大於 0。
if r.peekRune >= 0 {
return errors.New("fmt: scanning called UnreadRune with no rune available")
}
// 開始撤銷
// 反轉 peekRune 中的二進制位，使其成爲有效的字符。
r.peekRune = ^r.peekRune
return nil
}
// 臨時對象池
var ssFree = sync.Pool{
New: func() interface{} { return new(ss) },
}
// 創建掃描器，或從臨時對象池中獲取一個。
func newScanState(r io.Reader, nlIsSpace, nlIsEnd bool) (s *ss, old ssave) {
// 從臨時對象池中獲取一個掃描器
s = ssFree.Get().(*ss)
// 如果參數 r 不是一個 RuneScanner，則將其包裝成 RuneScanner 再賦值給 s.rs
if rs, ok := r.(io.RuneScanner); ok {
s.rs = rs
} else {
// 注意：r 只有 Read 方法，沒有撤銷方法，所以這裏包裝的 readRune 對象
// 無法將 UnreadRune 所撤銷的內容返回到 r 中。也就是說，儘量爲 r 提供
// RuneScanner，否則可能造成 r 中的數據丟失。
s.rs = &readRune{reader: r, peekRune: -1}
}
// 復位參數
s.nlIsSpace = nlIsSpace
s.nlIsEnd = nlIsEnd
s.atEOF = false
s.limit = hugeWid
s.argLimit = hugeWid
s.maxWid = hugeWid
s.validSave = true
s.count = 0
return
}
// 回收掃描器，避免再次分配。
func (s *ss) free(old ssave) {
// 如果掃描器被遞歸使用，則只需要恢復舊狀態，然後繼續使用。
if old.validSave {
s.ssave = old
return
}
// 不回收緩衝區太大的掃描器，避免內存浪費。
if cap(s.buf) > 1024 {
return
}
// 復位並存入
s.buf = s.buf[:0]
s.rs = nil
ssFree.Put(s)
}
// 用於實現 ScanState 接口
func (s *ss) skipSpace(stopAtNewline bool) {
for {
r := s.getRune()
if r == eof {
return
}
// \r\n 當 \n 處理
// peek 判斷即將讀取的字符是否在字符串 "\n" 中（只判斷不讀取）。
if r == '\r' && s.peek("\n") {
continue
}
if r == '\n' {
if stopAtNewline { // 換行符之後停止讀取
break
}
if s.nlIsSpace { // 換行符當空白處理
continue
}
// 換行符當非空白字符處理
// 在這裏不允許，所以中止整個掃描過程，返回 err。
s.errorString("unexpected newline")
return
}
// 非空白字符，撤銷讀取並返回。
if !isSpace(r) {
s.UnreadRune()
break
}
}
}
// 用於實現 ScanState 接口
func (s *ss) token(skipSpace bool, f func(rune) bool) []byte {
if skipSpace {
s.skipSpace(false)
}
// 循環讀取直到不滿足 f(r) 或遇到 EOF
for {
r := s.getRune()
if r == eof {
break
}
if !f(r) {
s.UnreadRune()
break
}
s.buf.WriteRune(r)
}
return s.buf
}
var complexError = errors.New("syntax error scanning complex number")
var boolError = errors.New("syntax error scanning boolean")
// 返回 r 在 s 中的字符序號（不是字節下標）
func indexRune(s string, r rune) int {
for i, c := range s {
if c == r {
return i
}
}
return -1
}
// 判斷即將讀取的字符是否在 ok 中。
// 如果 accept 爲 flase 則讀取並丟棄該字符，無論結果如何。
// 如果 accept 爲 true，則根據結果做進一步處理：
// 結果爲 true ：將字符讀入 s.buf 中
// 結果爲 false：不讀取該字符
func (s *ss) consume(ok string, accept bool) bool {
r := s.getRune()
if r == eof {
return false
}
// r 在 ok 中
if indexRune(ok, r) >= 0 {
if accept {
s.buf.WriteRune(r)
}
return true
}
// r 不在 ok 中（上面已經判斷過 r == eof，所以這裏沒必要再次判斷）
if r != eof && accept {
s.UnreadRune() // 不讀取該字符
}
return false
}
// 判斷即將讀取的字符是否在 ok 中，但不讀取該字符。
func (s *ss) peek(ok string) bool {
r := s.getRune()
if r != eof {
s.UnreadRune()
}
// 在 ok 中查找 r 的下標，判斷您是否 >= 0
return indexRune(ok, r) >= 0
}
// 判斷輸入端是否有數據可讀
// 如果沒有數據可讀，則中止整個掃描過程，返回 err。
func (s *ss) notEOF() {
if r := s.getRune(); r == eof {
panic(io.EOF)
}
s.UnreadRune()
}
// 判斷即將讀取的字符是否在 ok 中，如果在，則將其讀入 s.buf 中，
// 並返回 true，否則不讀取，並返回 false。
func (s *ss) accept(ok string) bool {
return s.consume(ok, true)
}
// 判斷 verb 是否在 okVerbs 中，
// 如果在，則返回 true。如果不在，則中止整個掃描過程，返回 err。
// 沒有返回 false 的情況。typ 用於在 err 中指示類型信息。
func (s *ss) okVerb(verb rune, okVerbs, typ string) bool {
for _, v := range okVerbs {
if v == verb {
return true
}
}
s.errorString("bad verb '%" + string(verb) + "' for " + typ)
return false
}
// 從輸入端讀取一個布爾值，verb 必須爲 t 或 v，否則讀取失敗。
// 可探測 0、1、t、f、true、false，忽略大小寫。
func (s *ss) scanBool(verb rune) bool {
// 跳過行首空白（包括換行符）
s.skipSpace(false)
// 輸入端必須有內容可讀
s.notEOF()
// 動詞不是 t 或 v，不符合布爾型的要求
if !s.okVerb(verb, "tv", "boolean") {
return false
}
// 布爾型的語法檢測很討厭，我們不做嚴格要求。
// 如果遇到不完整的 tr、tru 或 fa、fal、fals 則中止整個掃描過程，返回 err。
switch s.getRune() {
case '0':
return false
case '1':
return true
case 't', 'T':
if s.accept("rR") && (!s.accept("uU") || !s.accept("eE")) {
s.error(boolError)
}
return true
case 'f', 'F':
if s.accept("aA") && (!s.accept("lL") || !s.accept("sS") || !s.accept("eE")) {
s.error(boolError)
}
return false
}
return false
}
// 數值元素
const (
binaryDigits = "01"
octalDigits = "01234567"
decimalDigits = "0123456789"
hexadecimalDigits = "0123456789aAbBcCdDeEfF"
sign = "+-"
period = "."
exponent = "eEp"
)
// 返回 verb 所代表的進位制，及其字符範圍（即上面的常量）
func (s *ss) getBase(verb rune) (base int, digits string) {
// 判斷 verb 是否符合整型要求。
// 如果不符合，則中止整個掃描過程，返回 err。
s.okVerb(verb, "bdoUxXv", "integer")
base = 10 // 默認爲十進制
digits = decimalDigits
switch verb {
case 'b': // 二進制
base = 2
digits = binaryDigits
case 'o': // 八進制
base = 8
digits = octalDigits
case 'x', 'X', 'U': // 十六進制
base = 16
digits = hexadecimalDigits
}
return
}
// 從輸入端讀取數值字符串到 s.buf 中。
// digits 是可接收的字符範圍（不同進位制有不同的字符範圍）
// haveDigits 表示 s.buf 中是否已經有數值存在，
// 如果沒有，則本方法必須讀出數值，否則中止整個掃描過程，返回 err。
func (s *ss) scanNumber(digits string, haveDigits bool) string {
if !haveDigits {
// 輸入端必須有內容可讀
s.notEOF()
if !s.accept(digits) {
// 如果沒有讀到指定進制的字符，則中止整個掃描過程，返回 err。
s.errorString("expected integer")
}
}
// 繼續讀取合格的字符，存入 s.buf 中
for s.accept(digits) {
}
// 返回讀出的字符串
return string(s.buf)
}
// 功能同 ReadRune，只不過通過 bitSize 限制讀取字符的位寬。
// 如果讀出的字符在指定位寬內，則返回，否則中止整個掃描過程，返回 err。
func (s *ss) scanRune(bitSize int) int64 {
s.notEOF()
r := int64(s.getRune())
n := uint(bitSize)
// 位寬判斷
x := (r << (64 - n)) >> (64 - n)
if x != r {
s.errorString("overflow on character value " + string(r))
}
return r
}
// 根據輸入端的前導符 0 或 0x 判斷進位制並返回，同時返回字符範圍。
// found 表示檢測到前導符。只有當動詞是 %v 的時候纔會被調用。
func (s *ss) scanBasePrefix() (base int, digits string, found bool) {
// 如果不是以 0 開頭，表示是十進制數
if !s.peek("0") {
return 10, decimalDigits, false
}
// 如果是 0 開頭，則將其讀入 s.buf 中
s.accept("0")
found = true // 已經讀出一個 0，如果前導符後面沒有數值，將使用該 0 值。
// 繼續判斷是八進制還是十六進制
base, digits = 8, octalDigits
if s.peek("xX") {
s.consume("xX", false) // 丟棄匹配的 x 或 X 字符
base, digits = 16, hexadecimalDigits
}
return
}
// 讀取一個 int64 整數。bitSize 用於限制整數的位寬。
// 如果讀出的整數在指定位寬內，則返回，否則中止整個掃描過程，返回 err。
func (s *ss) scanInt(verb rune, bitSize int) int64 {
// 只需要讀取一個字符
if verb == 'c' {
return s.scanRune(bitSize)
}
s.skipSpace(false)
s.notEOF()
// 根據不同的動詞獲取進位制信息
base, digits := s.getBase(verb)
haveDigits := false // 是否已經讀出數值
if verb == 'U' {
// 丟棄前導符 U+
// 如果沒有讀取到 U+ 則中止整個掃描過程，返回 err。
if !s.consume("U", false) || !s.consume("+", false) {
s.errorString("bad unicode format ")
}
} else {
// sign 是常量 +-，如果能讀取到符號，則將其存入 s.buf 中。
s.accept(sign)
if verb == 'v' {
// 根據輸入端的前導符 0 或 0x 確定進位制
// 如果有前導符，則已經讀出一個 0，前導符後面可以沒有數值。
base, digits, haveDigits = s.scanBasePrefix()
}
}
// 讀出數值字符串，如果讀取失敗，則中止整個掃描過程，返回 err。
tok := s.scanNumber(digits, haveDigits)
// 轉換爲整型
i, err := strconv.ParseInt(tok, base, 64)
if err != nil {
s.error(err)
}
// 位寬判斷
n := uint(bitSize)
x := (i << (64 - n)) >> (64 - n)
if x != i {
s.errorString("integer overflow on token " + tok)
}
return i
}
// 功能同 scanInt，只不過返回的是無符號整數。
func (s *ss) scanUint(verb rune, bitSize int) uint64 {
if verb == 'c' {
return uint64(s.scanRune(bitSize))
}
s.skipSpace(false)
s.notEOF()
base, digits := s.getBase(verb)
haveDigits := false
if verb == 'U' {
if !s.consume("U", false) || !s.consume("+", false) {
s.errorString("bad unicode format ")
}
} else if verb == 'v' {
base, digits, haveDigits = s.scanBasePrefix()
}
tok := s.scanNumber(digits, haveDigits)
i, err := strconv.ParseUint(tok, base, 64)
if err != nil {
s.error(err)
}
n := uint(bitSize)
x := (i << (64 - n)) >> (64 - n)
if x != i {
s.errorString("unsigned integer overflow on token " + tok)
}
return i
}
// 讀取一個浮點數，如果指定了寬度值，則不會超過寬度值。
// 沒有檢查“只有指數沒有小數”的情況，但是 Atof 會進行檢查。
func (s *ss) floatToken() string {
s.buf = s.buf[:0]
// 非數值 NAN
if s.accept("nN") && s.accept("aA") && s.accept("nN") {
return string(s.buf)
}
// 符號 +-
s.accept(sign)
// 無窮大 INF
if s.accept("iI") && s.accept("nN") && s.accept("fF") {
return string(s.buf)
}
// 整數部分
for s.accept(decimalDigits) {
}
// 小數點
if s.accept(period) {
// 小數部分
for s.accept(decimalDigits) {
}
}
// 指數標誌
if s.accept(exponent) {
// 指數符號
s.accept(sign)
// 指數值
for s.accept(decimalDigits) {
}
}
return string(s.buf)
}
// 讀出一個虛數的實部和虛部。
// 虛數可以加上括號，虛數格式必須爲 N+Ni，N 必須是浮點數，中間不能有空格。
func (s *ss) complexTokens() (real, imag string) {
// TODO: 未實現純實部和純虛部的讀取
parens := s.accept("(") // 登記是否以 "(" 開頭
real = s.floatToken() // 讀取實部
s.buf = s.buf[:0]
// 虛部必須有符號
if !s.accept("+-") { // 讀取符號到 s.buf
s.error(complexError)
}
imagSign := string(s.buf) // 取出符號
imag = s.floatToken() // 讀取虛部
if !s.accept("i") { // 虛部後面必須爲 i
s.error(complexError)
}
// 如果以 "(" 開頭，則必須以 ")" 結尾。
if parens && !s.accept(")") {
s.error(complexError)
}
return real, imagSign + imag
}
// 將一個字符串轉換爲 float64 類型的值。
// str 要轉換的字符串，n：要轉換出的浮點數類型（32 或 64）
// 如果轉換失敗，則中止整個掃描過程，返回 err。
func (s *ss) convertFloat(str string, n int) float64 {
// Atof 不處理以 2 爲底的指數，但是它們很容易計算。
if p := indexRune(str, 'p'); p >= 0 {
// 獲取小數部分
f, err := strconv.ParseFloat(str[:p], n)
if err != nil {
if e, ok := err.(*strconv.NumError); ok {
e.Num = str
}
s.error(err)
}
// 獲取指數部分
m, err := strconv.Atoi(str[p+1:])
if err != nil {
//
if e, ok := err.(*strconv.NumError); ok {
e.Num = str
}
s.error(err)
}
// 算出結果：f * (2 的 m 次方)
return math.Ldexp(f, m)
}
// 普通浮點數直接轉換
f, err := strconv.ParseFloat(str, n)
if err != nil {
s.error(err)
}
return f
}
// 讀取一個 complex128 類型的值。
func (s *ss) scanComplex(verb rune, n int) complex128 {
// 檢查 verb 的有效性（floatVerbs 是常量 "beEfFgGv"）
if !s.okVerb(verb, floatVerbs, "complex") {
return 0
}
s.skipSpace(false)
s.notEOF()
// 讀取實部和虛部
sreal, simag := s.complexTokens()
real := s.convertFloat(sreal, n/2)
imag := s.convertFloat(simag, n/2)
return complex(real, imag)
}
// 讀取一個字符串。
func (s *ss) convertString(verb rune) (str string) {
// 檢查 verb 的有效性
if !s.okVerb(verb, "svqxX", "string") {
return ""
}
s.skipSpace(false)
s.notEOF()
switch verb {
case 'q': // 帶引號字符串
str = s.quotedString()
case 'x', 'X': // 十六進制格式的字符串
str = s.hexString()
default:
// %s 和 %v 僅返回連續的非空白字符
str = string(s.token(true, notSpace))
}
return
}
// 讀取雙引號或反引號字符串。
func (s *ss) quotedString() string {
s.notEOF()
quote := s.getRune()
switch quote {
case '`':
// 讀取直到遇到下一個反引號或 EOF
for {
r := s.mustReadRune()
if r == quote {
break
}
s.buf.WriteRune(r)
}
return string(s.buf)
case '"':
s.buf.WriteByte('"')
for {
r := s.mustReadRune()
s.buf.WriteRune(r)
if r == '\\' {
// strconv.Unquote 會處理轉義字符，這裏只需要寫入。
s.buf.WriteRune(s.mustReadRune())
} else if r == '"' {
break
}
}
result, err := strconv.Unquote(string(s.buf))
if err != nil {
s.error(err)
}
return result
default:
s.errorString("expected quoted string")
}
return ""
}
// hexDigit 返回十六進制字符所代表的十進制值
func hexDigit(d rune) (int, bool) {
digit := int(d)
switch digit {
case '0', '1', '2', '3', '4', '5', '6', '7', '8', '9':
return digit - '0', true
case 'a', 'b', 'c', 'd', 'e', 'f':
return 10 + digit - 'a', true
case 'A', 'B', 'C', 'D', 'E', 'F':
return 10 + digit - 'A', true
}
return -1, false
}
// 讀取兩個十六進制字符，並返回其所表示的字節。
// b ：讀取的字節
// ok：是否讀取成功
// 如果缺少後一個字符，則中止整個掃描過程，返回 err。
func (s *ss) hexByte() (b byte, ok bool) {
// 處理第一個字符
rune1 := s.getRune()
if rune1 == eof {
return
}
value1, ok := hexDigit(rune1)
if !ok {
s.UnreadRune()
return
}
// 處理第二個字符
value2, ok := hexDigit(s.mustReadRune())
if !ok {
s.errorString("illegal hex digit")
return
}
// 轉換爲十進制數值
return byte(value1<<4 | value2), true
}
// 讀取十六進制字符串，並返回其所表示的內容
// 兩個十六進制字符表示一個字節
// 讀取失敗則中止整個掃描過程，返回 err。
func (s *ss) hexString() string {
s.notEOF()
for {
// 讀取兩個十六進制字符所表示的一個字節
b, ok := s.hexByte()
if !ok {
break
}
s.buf.WriteByte(b)
}
if len(s.buf) == 0 {
s.errorString("no hex data for %x string")
return ""
}
return string(s.buf)
}
const (
floatVerbs = "beEfFgGv"
hugeWid = 1 << 30
intBits = 32 << (^uint(0) >> 63)
uintptrBits = 32 << (^uintptr(0) >> 63)
)
// 處理一個 arg。
// 遇到錯誤則中止整個掃描過程，返回 err。
func (s *ss) scanOne(verb rune, arg interface{}) {
s.buf = s.buf[:0]
var err error
// 如果參數有它自己的 Scan 方法，則調用它。
if v, ok := arg.(Scanner); ok {
err = v.Scan(s, verb)
if err != nil {
if err == io.EOF {
err = io.ErrUnexpectedEOF
}
s.error(err)
}
return
}
// 根據不同的 arg 類型選擇不同的解析方法。
switch v := arg.(type) {
case *bool:
*v = s.scanBool(verb)
case *complex64:
*v = complex64(s.scanComplex(verb, 64))
case *complex128:
*v = s.scanComplex(verb, 128)
case *int:
*v = int(s.scanInt(verb, intBits))
case *int8:
*v = int8(s.scanInt(verb, 8))
case *int16:
*v = int16(s.scanInt(verb, 16))
case *int32:
*v = int32(s.scanInt(verb, 32))
case *int64:
*v = s.scanInt(verb, 64)
case *uint:
*v = uint(s.scanUint(verb, intBits))
case *uint8:
*v = uint8(s.scanUint(verb, 8))
case *uint16:
*v = uint16(s.scanUint(verb, 16))
case *uint32:
*v = uint32(s.scanUint(verb, 32))
case *uint64:
*v = s.scanUint(verb, 64)
case *uintptr:
*v = uintptr(s.scanUint(verb, uintptrBits))
case *float32:
if s.okVerb(verb, floatVerbs, "float32") {
s.skipSpace(false)
s.notEOF()
*v = float32(s.convertFloat(s.floatToken(), 32))
}
case *float64:
if s.okVerb(verb, floatVerbs, "float64") {
s.skipSpace(false)
s.notEOF()
*v = s.convertFloat(s.floatToken(), 64)
}
case *string:
*v = s.convertString(verb)
case *[]byte:
// 先掃描成字符串，然後再轉換爲 []byte，所以得到的是一個副本，
// 如果我們掃描成 []byte，那麼結果將指向緩衝區。
*v = []byte(s.convertString(verb))
default:
val := reflect.ValueOf(v)
ptr := val
// arg 必須是一個指針，就像其它 arg 那樣
if ptr.Kind() != reflect.Ptr {
s.errorString("type not a pointer: " + val.Type().String())
return
}
// 接下來的流程和上面一樣
switch v := ptr.Elem(); v.Kind() {
case reflect.Bool:
v.SetBool(s.scanBool(verb))
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
v.SetInt(s.scanInt(verb, v.Type().Bits()))
case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
v.SetUint(s.scanUint(verb, v.Type().Bits()))
case reflect.String:
v.SetString(s.convertString(verb))
case reflect.Slice:
typ := v.Type()
// 對於切片，只能處理 []byte 的別名類型。
if typ.Elem().Kind() != reflect.Uint8 {
s.errorString("can't scan type: " + val.Type().String())
}
// 解析出字符串
str := s.convertString(verb)
// 轉換爲字節切片返回
v.Set(reflect.MakeSlice(typ, len(str), len(str)))
for i := 0; i < len(str); i++ {
v.Index(i).SetUint(uint64(str[i]))
}
case reflect.Float32, reflect.Float64:
s.skipSpace(false)
s.notEOF()
v.SetFloat(s.convertFloat(s.floatToken(), v.Type().Bits()))
case reflect.Complex64, reflect.Complex128:
v.SetComplex(s.scanComplex(verb, v.Type().Bits()))
default:
s.errorString("can't scan type: " + val.Type().String())
}
}
}
// 將本地引發的 panic（scanError 類型）和 EOF panic 轉換爲 error。
func errorHandler(errp *error) {
if e := recover(); e != nil {
// 本地 panic 轉換爲 error
if se, ok := e.(scanError); ok {
*errp = se.err
// EOF panic 也轉換爲 error
} else if eof, ok := e.(error); ok && eof == io.EOF {
*errp = eof
} else {
panic(e)
}
}
}
// 掃描器的掃描過程
func (s *ss) doScan(a []interface{}) (numProcessed int, err error) {
defer errorHandler(&err)
// 循環處理所有 arg
for _, arg := range a {
s.scanOne('v', arg)
numProcessed++
}
// 所有參數掃描結束
// 檢查是否以換行符或 EOF 結尾（Scanln 等需要這個錯誤信息）
if s.nlIsEnd {
for {
r := s.getRune()
if r == '\n' || r == eof {
break
}
// 跳過空白字符後再次判斷
if !isSpace(r) {
s.errorString("expected newline")
break
}
}
}
return
}
// 處理非佔位字符串，返回已處理的字節數。處理結果分爲以下幾種情況：
// 遇到佔位符 ：返回 % 之前的字節數
// 不匹配 ：返回 -1
// 完全匹配（format 被讀完）：返回 len(foramt)
// 輸入端被讀完 ：強行中止掃描
// advance 的邏輯比較複雜，要配合 doScanf 理解，很難完全理解。
func (s *ss) advance(format string) (i int) {
// 這裏的 format 不是完整的格式字符串，而是由 doScanf 提供的
// 未處理部分的格式字符串。doScanf 處理完一個佔位符後，就把
// 剩下的格式字符串交給 advance 處理。
for i < len(format) {
// 解碼一個待處理字符
fmtc, w := utf8.DecodeRuneInString(format[i:])
// 1、處理遇到的 % 號
if fmtc == '%' {
// 不能以 % 結尾
if i+w == len(format) {
s.errorString("missing verb: % at end of format string")
}
nextc, _ := utf8.DecodeRuneInString(format[i+w:])
// 遇到單獨的 %（佔位符）則返回 % 的下標 i（即 % 之前已處理的字節數）
if nextc != '%' {
return
}
// %% 被解析爲一個 %，當做普通字符，交給後面處理
i += w // 跳過 %% 中的前一個 %
}
// 2、處理 format 中的連續空白字符
sawSpace := false // 是否遇到連續的空白字符（包括換行符）
wasNewline := false // 是否遇到換行符
// 跳過連續的空白符
for isSpace(fmtc) && i < len(format) {
if fmtc == '\n' {
if wasNewline {
// 一次只處理一個換行符，之後的換行符交給後面處理
break
}
// 登記遇到換行符
wasNewline = true
}
// 登記遇到空白字符
sawSpace = true
i += w // 跳過已處理的空白字符
// 更新待處理字符
fmtc, w = utf8.DecodeRuneInString(format[i:])
}
// 到此，表示沒有連續空白或已跳過連續空白，
// 此時 i 指向非空白字符或換行符（即前面遇到的未處理的換行符）。
// 3、對比輸入端的連續空白字符
if sawSpace {
inputc := s.getRune()
if inputc == eof {
// 輸入端被讀空，返回已處理的字節數。
// 返回後，在 doScanf 中繼續判斷 format 是否也被讀完。
return
}
// 輸入端未遇到空白字符，匹配失敗，中止整個掃描過程，返回 err。
if !isSpace(inputc) {
s.errorString("expected space in input to match format")
}
// 輸入端也遇到空白字符，跳過空白部分。
for inputc != '\n' && isSpace(inputc) {
inputc = s.getRune()
}
// 此時 inputc 有可能爲 eof
// 輸入端遇到換行符
if inputc == '\n' {
// format 中未遇到換行符，匹配失敗，中止整個掃描過程，返回 err。
if !wasNewline {
s.errorString("newline in input does not match format")
}
// 到此，輸入端和 format 中都遇到換行符，匹配成功。
// 輸入端換行符之後的空白沒有繼續處理，而 format 中卻處理了，
// 這將導致 "\n a %d" 無法匹配 "\n a 1"。使用的時候要注意。
// 匹配完畢，返回已處理的字節數
// 這裏把 \n 當做一次掃描結束，這種行爲類似於 Scanln。
return
}
// 輸入端空白字符處理完畢，未遇到換行符，則讀取的應該是非空白字符。
// 撤銷對非空白字符的讀取，交給下一輪去處理。
// 如果之前讀取的是 eof 則 UnreadRune 不會撤銷任何內容。
s.UnreadRune()
// format 中遇到換行符，與輸入端不匹配
if wasNewline {
s.errorString("newline in format does not match input")
}
// 空白部分（第二個換行符之前的）全部匹配成功，繼續下一輪，處理後面的字符。
continue
}
// 到此，表示 format 中沒遇到空白字符或空白字符已經處理完畢。
// 4、處理 format 中的非空白字符
// 使用 mustReadRune 而不是 getRune 表示如果讀取失敗（EOF），
// 則中止整個掃描過程，返回 err。
inputc := s.mustReadRune()
// 非空白字符匹配失敗，撤銷對 input 的讀取，並返回 -1
if fmtc != inputc {
// 匹配失敗，應該不需要再做什麼了，不過 advance 作爲一個獨立的功能函數，
// 還是要嚴謹一些，執行 s.UnreadRune 是爲了保證輸入端中已處理的內容與
// format 中 i 的位置對齊。
s.UnreadRune()
return -1
}
// 非空白字符匹配成功，繼續處理下一個字符。
i += w
}
// 全部處理完畢，返回 len(format)
return
}
// 掃描器的格式化掃描過程
func (s *ss) doScanf(format string, a []interface{}) (numProcessed int, err error) {
// 消化本地 panic，結束整個掃描過程。
defer errorHandler(&err)
end := len(format) - 1
for i := 0; i <= end; {
// 先處理 format 中的非佔位符部分。
w := s.advance(format[i:])
// 循環直到遇到 % 字符
if w > 0 {
i += w
continue
// 這裏有一個作用，就是當 i == len(format) 時，
// 會終止循環，不會繼續在後面訪問 format[i]
}
// 到這裏，表示 format 沒有處理完，而且應該處理佔位符了。
// 沒有遇找到佔位符，看看是什麼原因
if format[i] != '%' {
// 非空白字符匹配失敗
if w < 0 {
s.errorString("input does not match format")
}
// 到此，表示遇到 EOF
// 不過代碼不會執行到這裏，因爲在 advance 中 EOF 會引發 panic
// 爲了邏輯的嚴謹，這裏還是需要添加一個 break，以防 advance 發生改變。
break
}
i++ // 跳過 % 號
// 讀取佔位符中的寬度信息
var widPresent bool
s.maxWid, widPresent, i = parsenum(format, i, end)
// 如果沒有設置寬度信息，則將寬度設置爲默認值 hugeWid
if !widPresent {
s.maxWid = hugeWid // hugeWid 是常量 1 << 30
}
// 獲取動詞
c, w := utf8.DecodeRuneInString(format[i:])
i += w // 跳過動詞
// 如果動詞不是 c，則跳過輸入端開頭的空白
if c != 'c' {
s.SkipSpace()
}
// 默認讀取限制
s.argLimit = s.limit
// 根據佔位符中的寬度信息設置輸入端允許讀出的最大字符數
if f := s.count + s.maxWid; f < s.argLimit {
s.argLimit = f
}
// arg 太少，佔位符太多，數量不匹配。
if numProcessed >= len(a) {
s.errorString("too few operands for format '%" + format[i-w:] + "'")
break
}
arg := a[numProcessed]
s.scanOne(c, arg) // 處理一個 arg
numProcessed++ // 跳過已處理的 arg
// 恢復默認讀取限制
s.argLimit = s.limit
}
// arg 太多，佔位符太少，數量不匹配。
if numProcessed < len(a) {
s.errorString("too many operands")
}
return
}