From cf97cd317be0d5fc1fa7b861f143060d7fd9b361 Mon Sep 17 00:00:00 2001 From: cui fliter Date: Thu, 12 Oct 2023 14:13:36 +0800 Subject: [PATCH] bufio: add available godoc link Change-Id: Id32bae57c9fcc2074f82089ba9c69be9a601f128 Reviewed-on: https://go-review.googlesource.com/c/go/+/534758 Reviewed-by: Dmitri Shuralyov Run-TryBot: shuang cui Reviewed-by: Ian Lance Taylor Auto-Submit: Ian Lance Taylor TryBot-Result: Gopher Robot --- src/bufio/bufio.go | 80 +++++++++++++++++++++++----------------------- src/bufio/scan.go | 60 +++++++++++++++++----------------- 2 files changed, 70 insertions(+), 70 deletions(-) diff --git a/src/bufio/bufio.go b/src/bufio/bufio.go index 1266383f933..880e52798e1 100644 --- a/src/bufio/bufio.go +++ b/src/bufio/bufio.go @@ -41,9 +41,9 @@ type Reader struct { const minReadBufferSize = 16 const maxConsecutiveEmptyReads = 100 -// NewReaderSize returns a new Reader whose buffer has at least the specified -// size. If the argument io.Reader is already a Reader with large enough -// size, it returns the underlying Reader. +// NewReaderSize returns a new [Reader] whose buffer has at least the specified +// size. If the argument io.Reader is already a [Reader] with large enough +// size, it returns the underlying [Reader]. func NewReaderSize(rd io.Reader, size int) *Reader { // Is it already a Reader? b, ok := rd.(*Reader) @@ -55,7 +55,7 @@ func NewReaderSize(rd io.Reader, size int) *Reader { return r } -// NewReader returns a new Reader whose buffer has the default size. +// NewReader returns a new [Reader] whose buffer has the default size. func NewReader(rd io.Reader) *Reader { return NewReaderSize(rd, defaultBufSize) } @@ -65,9 +65,9 @@ func (b *Reader) Size() int { return len(b.buf) } // Reset discards any buffered data, resets all state, and switches // the buffered reader to read from r. -// Calling Reset on the zero value of Reader initializes the internal buffer +// Calling Reset on the zero value of [Reader] initializes the internal buffer // to the default size. -// Calling b.Reset(b) (that is, resetting a Reader to itself) does nothing. +// Calling b.Reset(b) (that is, resetting a [Reader] to itself) does nothing. func (b *Reader) Reset(r io.Reader) { // If a Reader r is passed to NewReader, NewReader will return r. // Different layers of code may do that, and then later pass r @@ -132,9 +132,9 @@ func (b *Reader) readErr() error { // Peek returns the next n bytes without advancing the reader. The bytes stop // being valid at the next read call. If Peek returns fewer than n bytes, it // also returns an error explaining why the read is short. The error is -// ErrBufferFull if n is larger than b's buffer size. +// [ErrBufferFull] if n is larger than b's buffer size. // -// Calling Peek prevents a UnreadByte or UnreadRune call from succeeding +// Calling Peek prevents a [Reader.UnreadByte] or [Reader.UnreadRune] call from succeeding // until the next read operation. func (b *Reader) Peek(n int) ([]byte, error) { if n < 0 { @@ -204,10 +204,10 @@ func (b *Reader) Discard(n int) (discarded int, err error) { // Read reads data into p. // It returns the number of bytes read into p. -// The bytes are taken from at most one Read on the underlying Reader, +// The bytes are taken from at most one Read on the underlying [Reader], // hence n may be less than len(p). // To read exactly len(p) bytes, use io.ReadFull(b, p). -// If the underlying Reader can return a non-zero count with io.EOF, +// If the underlying [Reader] can return a non-zero count with io.EOF, // then this Read method can do so as well; see the [io.Reader] docs. func (b *Reader) Read(p []byte) (n int, err error) { n = len(p) @@ -277,7 +277,7 @@ func (b *Reader) ReadByte() (byte, error) { // UnreadByte unreads the last byte. Only the most recently read byte can be unread. // // UnreadByte returns an error if the most recent method called on the -// Reader was not a read operation. Notably, Peek, Discard, and WriteTo are not +// [Reader] was not a read operation. Notably, [Reader.Peek], [Reader.Discard], and [Reader.WriteTo] are not // considered read operations. func (b *Reader) UnreadByte() error { if b.lastByte < 0 || b.r == 0 && b.w > 0 { @@ -318,8 +318,8 @@ func (b *Reader) ReadRune() (r rune, size int, err error) { } // UnreadRune unreads the last rune. If the most recent method called on -// the Reader was not a ReadRune, UnreadRune returns an error. (In this -// regard it is stricter than UnreadByte, which will unread the last byte +// the [Reader] was not a [Reader.ReadRune], [Reader.UnreadRune] returns an error. (In this +// regard it is stricter than [Reader.UnreadByte], which will unread the last byte // from any read operation.) func (b *Reader) UnreadRune() error { if b.lastRuneSize < 0 || b.r < b.lastRuneSize { @@ -339,10 +339,10 @@ func (b *Reader) Buffered() int { return b.w - b.r } // The bytes stop being valid at the next read. // If ReadSlice encounters an error before finding a delimiter, // it returns all the data in the buffer and the error itself (often io.EOF). -// ReadSlice fails with error ErrBufferFull if the buffer fills without a delim. +// ReadSlice fails with error [ErrBufferFull] if the buffer fills without a delim. // Because the data returned from ReadSlice will be overwritten // by the next I/O operation, most clients should use -// ReadBytes or ReadString instead. +// [Reader.ReadBytes] or ReadString instead. // ReadSlice returns err != nil if and only if line does not end in delim. func (b *Reader) ReadSlice(delim byte) (line []byte, err error) { s := 0 // search start index @@ -386,7 +386,7 @@ func (b *Reader) ReadSlice(delim byte) (line []byte, err error) { } // ReadLine is a low-level line-reading primitive. Most callers should use -// ReadBytes('\n') or ReadString('\n') instead or use a Scanner. +// [Reader.ReadBytes]('\n') or [Reader.ReadString]('\n') instead or use a [Scanner]. // // ReadLine tries to return a single line, not including the end-of-line bytes. // If the line was too long for the buffer then isPrefix is set and the @@ -398,7 +398,7 @@ func (b *Reader) ReadSlice(delim byte) (line []byte, err error) { // // The text returned from ReadLine does not include the line end ("\r\n" or "\n"). // No indication or error is given if the input ends without a final line end. -// Calling UnreadByte after ReadLine will always unread the last byte read +// Calling [Reader.UnreadByte] after ReadLine will always unread the last byte read // (possibly a character belonging to the line end) even if that byte is not // part of the line returned by ReadLine. func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) { @@ -508,9 +508,9 @@ func (b *Reader) ReadString(delim byte) (string, error) { } // WriteTo implements io.WriterTo. -// This may make multiple calls to the Read method of the underlying Reader. -// If the underlying reader supports the WriteTo method, -// this calls the underlying WriteTo without buffering. +// This may make multiple calls to the [Reader.Read] method of the underlying [Reader]. +// If the underlying reader supports the [Reader.WriteTo] method, +// this calls the underlying [Reader.WriteTo] without buffering. func (b *Reader) WriteTo(w io.Writer) (n int64, err error) { b.lastByte = -1 b.lastRuneSize = -1 @@ -555,7 +555,7 @@ func (b *Reader) WriteTo(w io.Writer) (n int64, err error) { var errNegativeWrite = errors.New("bufio: writer returned negative count from Write") -// writeBuf writes the Reader's buffer to the writer. +// writeBuf writes the [Reader]'s buffer to the writer. func (b *Reader) writeBuf(w io.Writer) (int64, error) { n, err := w.Write(b.buf[b.r:b.w]) if n < 0 { @@ -567,12 +567,12 @@ func (b *Reader) writeBuf(w io.Writer) (int64, error) { // buffered output -// Writer implements buffering for an io.Writer object. -// If an error occurs writing to a Writer, no more data will be -// accepted and all subsequent writes, and Flush, will return the error. +// Writer implements buffering for an [io.Writer] object. +// If an error occurs writing to a [Writer], no more data will be +// accepted and all subsequent writes, and [Writer.Flush], will return the error. // After all data has been written, the client should call the -// Flush method to guarantee all data has been forwarded to -// the underlying io.Writer. +// [Writer.Flush] method to guarantee all data has been forwarded to +// the underlying [io.Writer]. type Writer struct { err error buf []byte @@ -580,9 +580,9 @@ type Writer struct { wr io.Writer } -// NewWriterSize returns a new Writer whose buffer has at least the specified -// size. If the argument io.Writer is already a Writer with large enough -// size, it returns the underlying Writer. +// NewWriterSize returns a new [Writer] whose buffer has at least the specified +// size. If the argument io.Writer is already a [Writer] with large enough +// size, it returns the underlying [Writer]. func NewWriterSize(w io.Writer, size int) *Writer { // Is it already a Writer? b, ok := w.(*Writer) @@ -598,9 +598,9 @@ func NewWriterSize(w io.Writer, size int) *Writer { } } -// NewWriter returns a new Writer whose buffer has the default size. -// If the argument io.Writer is already a Writer with large enough buffer size, -// it returns the underlying Writer. +// NewWriter returns a new [Writer] whose buffer has the default size. +// If the argument io.Writer is already a [Writer] with large enough buffer size, +// it returns the underlying [Writer]. func NewWriter(w io.Writer) *Writer { return NewWriterSize(w, defaultBufSize) } @@ -610,9 +610,9 @@ func (b *Writer) Size() int { return len(b.buf) } // Reset discards any unflushed buffered data, clears any error, and // resets b to write its output to w. -// Calling Reset on the zero value of Writer initializes the internal buffer +// Calling Reset on the zero value of [Writer] initializes the internal buffer // to the default size. -// Calling w.Reset(w) (that is, resetting a Writer to itself) does nothing. +// Calling w.Reset(w) (that is, resetting a [Writer] to itself) does nothing. func (b *Writer) Reset(w io.Writer) { // If a Writer w is passed to NewWriter, NewWriter will return w. // Different layers of code may do that, and then later pass w @@ -628,7 +628,7 @@ func (b *Writer) Reset(w io.Writer) { b.wr = w } -// Flush writes any buffered data to the underlying io.Writer. +// Flush writes any buffered data to the underlying [io.Writer]. func (b *Writer) Flush() error { if b.err != nil { return b.err @@ -657,7 +657,7 @@ func (b *Writer) Available() int { return len(b.buf) - b.n } // AvailableBuffer returns an empty buffer with b.Available() capacity. // This buffer is intended to be appended to and -// passed to an immediately succeeding Write call. +// passed to an immediately succeeding [Writer.Write] call. // The buffer is only valid until the next write operation on b. func (b *Writer) AvailableBuffer() []byte { return b.buf[b.n:][:0] @@ -774,7 +774,7 @@ func (b *Writer) WriteString(s string) (int, error) { return nn, nil } -// ReadFrom implements io.ReaderFrom. If the underlying writer +// ReadFrom implements [io.ReaderFrom]. If the underlying writer // supports the ReadFrom method, this calls the underlying ReadFrom. // If there is buffered data and an underlying ReadFrom, this fills // the buffer and writes it before calling ReadFrom. @@ -826,14 +826,14 @@ func (b *Writer) ReadFrom(r io.Reader) (n int64, err error) { // buffered input and output -// ReadWriter stores pointers to a Reader and a Writer. -// It implements io.ReadWriter. +// ReadWriter stores pointers to a [Reader] and a [Writer]. +// It implements [io.ReadWriter]. type ReadWriter struct { *Reader *Writer } -// NewReadWriter allocates a new ReadWriter that dispatches to r and w. +// NewReadWriter allocates a new [ReadWriter] that dispatches to r and w. func NewReadWriter(r *Reader, w *Writer) *ReadWriter { return &ReadWriter{r, w} } diff --git a/src/bufio/scan.go b/src/bufio/scan.go index d8dcf13ca10..558e168b2d7 100644 --- a/src/bufio/scan.go +++ b/src/bufio/scan.go @@ -13,10 +13,10 @@ import ( // Scanner provides a convenient interface for reading data such as // a file of newline-delimited lines of text. Successive calls to -// the Scan method will step through the 'tokens' of a file, skipping +// the [Scanner.Scan] method will step through the 'tokens' of a file, skipping // the bytes between the tokens. The specification of a token is -// defined by a split function of type SplitFunc; the default split -// function breaks the input into lines with line termination stripped. Split +// defined by a split function of type [SplitFunc]; the default split +// function breaks the input into lines with line termination stripped. [Scanner.Split] // functions are defined in this package for scanning a file into // lines, bytes, UTF-8-encoded runes, and space-delimited words. The // client may instead provide a custom split function. @@ -25,7 +25,7 @@ import ( // large to fit in the buffer. When a scan stops, the reader may have // advanced arbitrarily far past the last token. Programs that need more // control over error handling or large tokens, or must run sequential scans -// on a reader, should use bufio.Reader instead. +// on a reader, should use [bufio.Reader] instead. type Scanner struct { r io.Reader // The reader provided by the client. split SplitFunc // The function to split the tokens. @@ -42,21 +42,21 @@ type Scanner struct { // SplitFunc is the signature of the split function used to tokenize the // input. The arguments are an initial substring of the remaining unprocessed -// data and a flag, atEOF, that reports whether the Reader has no more data +// data and a flag, atEOF, that reports whether the [Reader] has no more data // to give. The return values are the number of bytes to advance the input // and the next token to return to the user, if any, plus an error, if any. // // Scanning stops if the function returns an error, in which case some of -// the input may be discarded. If that error is ErrFinalToken, scanning +// the input may be discarded. If that error is [ErrFinalToken], scanning // stops with no error. // -// Otherwise, the Scanner advances the input. If the token is not nil, -// the Scanner returns it to the user. If the token is nil, the +// Otherwise, the [Scanner] advances the input. If the token is not nil, +// the [Scanner] returns it to the user. If the token is nil, the // Scanner reads more data and continues scanning; if there is no more -// data--if atEOF was true--the Scanner returns. If the data does not +// data--if atEOF was true--the [Scanner] returns. If the data does not // yet hold a complete token, for instance if it has no newline while -// scanning lines, a SplitFunc can return (0, nil, nil) to signal the -// Scanner to read more data into the slice and try again with a +// scanning lines, a [SplitFunc] can return (0, nil, nil) to signal the +// [Scanner] to read more data into the slice and try again with a // longer slice starting at the same point in the input. // // The function is never called with an empty data slice unless atEOF @@ -74,7 +74,7 @@ var ( const ( // MaxScanTokenSize is the maximum size used to buffer a token - // unless the user provides an explicit buffer with Scanner.Buffer. + // unless the user provides an explicit buffer with [Scanner.Buffer]. // The actual maximum token size may be smaller as the buffer // may need to include, for instance, a newline. MaxScanTokenSize = 64 * 1024 @@ -82,8 +82,8 @@ const ( startBufSize = 4096 // Size of initial allocation for buffer. ) -// NewScanner returns a new Scanner to read from r. -// The split function defaults to ScanLines. +// NewScanner returns a new [Scanner] to read from r. +// The split function defaults to [ScanLines]. func NewScanner(r io.Reader) *Scanner { return &Scanner{ r: r, @@ -92,7 +92,7 @@ func NewScanner(r io.Reader) *Scanner { } } -// Err returns the first non-EOF error that was encountered by the Scanner. +// Err returns the first non-EOF error that was encountered by the [Scanner]. func (s *Scanner) Err() error { if s.err == io.EOF { return nil @@ -100,14 +100,14 @@ func (s *Scanner) Err() error { return s.err } -// Bytes returns the most recent token generated by a call to Scan. +// Bytes returns the most recent token generated by a call to [Scanner.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 } -// Text returns the most recent token generated by a call to Scan +// Text returns the most recent token generated by a call to [Scanner.Scan] // as a newly allocated string holding its bytes. func (s *Scanner) Text() string { return string(s.token) @@ -123,11 +123,11 @@ func (s *Scanner) Text() string { // See the emptyFinalToken example for a use of this value. var ErrFinalToken = errors.New("final token") -// Scan advances the Scanner to the next token, which will then be -// available through the Bytes or Text method. It returns false when the +// Scan advances the [Scanner] to the next token, which will then be +// available through the [Scanner.Bytes] or [Scanner.Text] method. It returns false when the // scan stops, either by reaching the end of the input or an error. -// After Scan returns false, the Err method will return any error that -// occurred during scanning, except that if it was io.EOF, Err +// After Scan returns false, the [Scanner.Err] method will return any error that +// occurred during scanning, except that if it was [io.EOF], [Scanner.Err] // will return nil. // Scan panics if the split function returns too many empty // tokens without advancing the input. This is a common error mode for @@ -256,10 +256,10 @@ func (s *Scanner) setErr(err error) { // Buffer sets the initial buffer to use when scanning // and the maximum size of buffer that may be allocated during scanning. // The maximum token size must be less than the larger of max and cap(buf). -// If max <= cap(buf), Scan will use this buffer only and do no allocation. +// If max <= cap(buf), [Scanner.Scan] will use this buffer only and do no allocation. // -// By default, Scan uses an internal buffer and sets the -// maximum token size to MaxScanTokenSize. +// By default, [Scanner.Scan] uses an internal buffer and sets the +// maximum token size to [MaxScanTokenSize]. // // Buffer panics if it is called after scanning has started. func (s *Scanner) Buffer(buf []byte, max int) { @@ -270,8 +270,8 @@ func (s *Scanner) Buffer(buf []byte, max int) { s.maxTokenSize = max } -// Split sets the split function for the Scanner. -// The default split function is ScanLines. +// Split sets the split function for the [Scanner]. +// The default split function is [ScanLines]. // // Split panics if it is called after scanning has started. func (s *Scanner) Split(split SplitFunc) { @@ -283,7 +283,7 @@ func (s *Scanner) Split(split SplitFunc) { // Split functions -// ScanBytes is a split function for a Scanner that returns each byte as a token. +// ScanBytes is a split function for a [Scanner] that returns each byte as a token. func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error) { if atEOF && len(data) == 0 { return 0, nil, nil @@ -293,7 +293,7 @@ func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error) { var errorRune = []byte(string(utf8.RuneError)) -// ScanRunes is a split function for a Scanner that returns each +// ScanRunes is a split function for a [Scanner] that returns each // UTF-8-encoded rune as a token. The sequence of runes returned is // equivalent to that from a range loop over the input as a string, which // means that erroneous UTF-8 encodings translate to U+FFFD = "\xef\xbf\xbd". @@ -339,7 +339,7 @@ func dropCR(data []byte) []byte { return data } -// ScanLines is a split function for a Scanner that returns each line of +// ScanLines is a split function for a [Scanner] that returns each line of // text, stripped of any trailing end-of-line marker. The returned line may // be empty. The end-of-line marker is one optional carriage return followed // by one mandatory newline. In regular expression notation, it is `\r?\n`. @@ -386,7 +386,7 @@ func isSpace(r rune) bool { return false } -// ScanWords is a split function for a Scanner that returns each +// ScanWords is a split function for a [Scanner] that returns each // space-separated word of text, with surrounding spaces deleted. It will // never return an empty string. The definition of space is set by // unicode.IsSpace.