@@ -48,7 +48,9 @@ type Scanner struct {
4848//
4949// Scanning stops if the function returns an error, in which case some of
5050// the input may be discarded. If that error is [ErrFinalToken], scanning
51- // stops with no error.
51+ // stops with no error. A non-nil token delivered with [ErrFinalToken]
52+ // will be the last token, and a nil token with [ErrFinalToken]
53+ // immediately stops the scanning.
5254//
5355// Otherwise, the [Scanner] advances the input. If the token is not nil,
5456// the [Scanner] returns it to the user. If the token is nil, the
@@ -114,18 +116,20 @@ func (s *Scanner) Text() string {
114116}
115117
116118// ErrFinalToken is a special sentinel error value. It is intended to be
117- // returned by a Split function to indicate that the token being delivered
118- // with the error is the last token and scanning should stop after this one.
119- // After ErrFinalToken is received by Scan, scanning stops with no error.
119+ // returned by a Split function to indicate that the scanning should stop
120+ // with no error. If the token being delivered with this error is not nil,
121+ // the token is the last token.
122+ //
120123// The value is useful to stop processing early or when it is necessary to
121- // deliver a final empty token. One could achieve the same behavior
122- // with a custom error value but providing one here is tidier.
124+ // deliver a final empty token (which is different from a nil token).
125+ // One could achieve the same behavior with a custom error value but
126+ // providing one here is tidier.
123127// See the emptyFinalToken example for a use of this value.
124128var ErrFinalToken = errors .New ("final token" )
125129
126130// Scan advances the [Scanner] to the next token, which will then be
127- // available through the [Scanner.Bytes] or [Scanner.Text] method. It returns false when the
128- // scan stops , either by reaching the end of the input or an error.
131+ // available through the [Scanner.Bytes] or [Scanner.Text] method. It returns false when
132+ // there are no more tokens , either by reaching the end of the input or an error.
129133// After Scan returns false, the [Scanner.Err] method will return any error that
130134// occurred during scanning, except that if it was [io.EOF], [Scanner.Err]
131135// will return nil.
@@ -148,7 +152,10 @@ func (s *Scanner) Scan() bool {
148152 if err == ErrFinalToken {
149153 s .token = token
150154 s .done = true
151- return true
155+ // When token is not nil, it means the scanning stops
156+ // with a trailing token, and thus the return value
157+ // should be true to indicate the existence of the token.
158+ return token != nil
152159 }
153160 s .setErr (err )
154161 return false
0 commit comments