From 6dd7462a04e2ce0a3e91cdb8fd85e98ac62ba0aa Mon Sep 17 00:00:00 2001 From: cui fliter Date: Thu, 12 Oct 2023 11:49:26 +0800 Subject: [PATCH] bytes,strings: add available godoc link Change-Id: Id9706a783d3321e3706eeee102286522e7968efd Reviewed-on: https://go-review.googlesource.com/c/go/+/534775 Reviewed-by: Ian Lance Taylor LUCI-TryBot-Result: Go LUCI Reviewed-by: Dmitri Shuralyov Auto-Submit: Ian Lance Taylor --- src/bytes/buffer.go | 52 +++++++++++++++++++++--------------------- src/bytes/reader.go | 26 ++++++++++----------- src/strings/builder.go | 4 ++-- src/strings/reader.go | 28 +++++++++++------------ src/strings/replace.go | 2 +- src/strings/strings.go | 10 ++++---- 6 files changed, 61 insertions(+), 61 deletions(-) diff --git a/src/bytes/buffer.go b/src/bytes/buffer.go index 5a68188423..ba844ba9d3 100644 --- a/src/bytes/buffer.go +++ b/src/bytes/buffer.go @@ -15,7 +15,7 @@ import ( // smallBufferSize is an initial allocation minimal capacity. const smallBufferSize = 64 -// A Buffer is a variable-sized buffer of bytes with Read and Write methods. +// A Buffer is a variable-sized buffer of bytes with [Buffer.Read] and [Buffer.Write] methods. // The zero value for Buffer is an empty buffer ready to use. type Buffer struct { buf []byte // contents are the bytes buf[off : len(buf)] @@ -48,19 +48,19 @@ const maxInt = int(^uint(0) >> 1) // Bytes returns a slice of length b.Len() holding the unread portion of the buffer. // The slice is valid for use only until the next buffer modification (that is, -// only until the next call to a method like Read, Write, Reset, or Truncate). +// only until the next call to a method like [Buffer.Read], [Buffer.Write], [Buffer.Reset], or [Buffer.Truncate]). // The slice aliases the buffer content at least until the next buffer modification, // so immediate changes to the slice will affect the result of future reads. func (b *Buffer) Bytes() []byte { return b.buf[b.off:] } // 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 [Buffer.Write] call. // The buffer is only valid until the next write operation on b. func (b *Buffer) AvailableBuffer() []byte { return b.buf[len(b.buf):] } // String returns the contents of the unread portion of the buffer -// as a string. If the Buffer is a nil pointer, it returns "". +// as a string. If the [Buffer] is a nil pointer, it returns "". // // To build strings more efficiently, see the strings.Builder type. func (b *Buffer) String() string { @@ -102,7 +102,7 @@ func (b *Buffer) Truncate(n int) { // Reset resets the buffer to be empty, // but it retains the underlying storage for use by future writes. -// Reset is the same as Truncate(0). +// Reset is the same as [Buffer.Truncate](0). func (b *Buffer) Reset() { b.buf = b.buf[:0] b.off = 0 @@ -160,7 +160,7 @@ func (b *Buffer) grow(n int) int { // another n bytes. After Grow(n), at least n bytes can be written to the // buffer without another allocation. // If n is negative, Grow will panic. -// If the buffer can't grow it will panic with ErrTooLarge. +// If the buffer can't grow it will panic with [ErrTooLarge]. func (b *Buffer) Grow(n int) { if n < 0 { panic("bytes.Buffer.Grow: negative count") @@ -171,7 +171,7 @@ func (b *Buffer) Grow(n int) { // Write appends the contents of p to the buffer, growing the buffer as // needed. The return value n is the length of p; err is always nil. If the -// buffer becomes too large, Write will panic with ErrTooLarge. +// buffer becomes too large, Write will panic with [ErrTooLarge]. func (b *Buffer) Write(p []byte) (n int, err error) { b.lastRead = opInvalid m, ok := b.tryGrowByReslice(len(p)) @@ -183,7 +183,7 @@ func (b *Buffer) Write(p []byte) (n int, err error) { // WriteString appends the contents of s to the buffer, growing the buffer as // needed. The return value n is the length of s; err is always nil. If the -// buffer becomes too large, WriteString will panic with ErrTooLarge. +// buffer becomes too large, WriteString will panic with [ErrTooLarge]. func (b *Buffer) WriteString(s string) (n int, err error) { b.lastRead = opInvalid m, ok := b.tryGrowByReslice(len(s)) @@ -194,7 +194,7 @@ func (b *Buffer) WriteString(s string) (n int, err error) { } // MinRead is the minimum slice size passed to a Read call by -// Buffer.ReadFrom. As long as the Buffer has at least MinRead bytes beyond +// [Buffer.ReadFrom]. As long as the [Buffer] has at least MinRead bytes beyond // what is required to hold the contents of r, ReadFrom will not grow the // underlying buffer. const MinRead = 512 @@ -202,7 +202,7 @@ const MinRead = 512 // ReadFrom reads data from r until EOF and appends it to the buffer, growing // the buffer as needed. The return value n is the number of bytes read. Any // error except io.EOF encountered during the read is also returned. If the -// buffer becomes too large, ReadFrom will panic with ErrTooLarge. +// buffer becomes too large, ReadFrom will panic with [ErrTooLarge]. func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) { b.lastRead = opInvalid for { @@ -279,9 +279,9 @@ func (b *Buffer) WriteTo(w io.Writer) (n int64, err error) { } // WriteByte appends the byte c to the buffer, growing the buffer as needed. -// The returned error is always nil, but is included to match bufio.Writer's +// The returned error is always nil, but is included to match [bufio.Writer]'s // WriteByte. If the buffer becomes too large, WriteByte will panic with -// ErrTooLarge. +// [ErrTooLarge]. func (b *Buffer) WriteByte(c byte) error { b.lastRead = opInvalid m, ok := b.tryGrowByReslice(1) @@ -294,8 +294,8 @@ func (b *Buffer) WriteByte(c byte) error { // WriteRune appends the UTF-8 encoding of Unicode code point r to the // buffer, returning its length and an error, which is always nil but is -// included to match bufio.Writer's WriteRune. The buffer is grown as needed; -// if it becomes too large, WriteRune will panic with ErrTooLarge. +// included to match [bufio.Writer]'s WriteRune. The buffer is grown as needed; +// if it becomes too large, WriteRune will panic with [ErrTooLarge]. func (b *Buffer) WriteRune(r rune) (n int, err error) { // Compare as uint32 to correctly handle negative runes. if uint32(r) < utf8.RuneSelf { @@ -334,7 +334,7 @@ func (b *Buffer) Read(p []byte) (n int, err error) { } // Next returns a slice containing the next n bytes from the buffer, -// advancing the buffer as if the bytes had been returned by Read. +// advancing the buffer as if the bytes had been returned by [Buffer.Read]. // If there are fewer than n bytes in the buffer, Next returns the entire buffer. // The slice is only valid until the next call to a read or write method. func (b *Buffer) Next(n int) []byte { @@ -388,10 +388,10 @@ func (b *Buffer) ReadRune() (r rune, size int, err error) { return r, n, nil } -// UnreadRune unreads the last rune returned by ReadRune. +// UnreadRune unreads the last rune returned by [Buffer.ReadRune]. // If the most recent read or write operation on the buffer was -// not a successful ReadRune, UnreadRune returns an error. (In this regard -// it is stricter than UnreadByte, which will unread the last byte +// not a successful [Buffer.ReadRune], UnreadRune returns an error. (In this regard +// it is stricter than [Buffer.UnreadByte], which will unread the last byte // from any read operation.) func (b *Buffer) UnreadRune() error { if b.lastRead <= opInvalid { @@ -460,23 +460,23 @@ func (b *Buffer) ReadString(delim byte) (line string, err error) { return string(slice), err } -// NewBuffer creates and initializes a new Buffer using buf as its -// initial contents. The new Buffer takes ownership of buf, and the +// NewBuffer creates and initializes a new [Buffer] using buf as its +// initial contents. The new [Buffer] takes ownership of buf, and the // caller should not use buf after this call. NewBuffer is intended to -// prepare a Buffer to read existing data. It can also be used to set +// prepare a [Buffer] to read existing data. It can also be used to set // the initial size of the internal buffer for writing. To do that, // buf should have the desired capacity but a length of zero. // -// In most cases, new(Buffer) (or just declaring a Buffer variable) is -// sufficient to initialize a Buffer. +// In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is +// sufficient to initialize a [Buffer]. func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} } -// NewBufferString creates and initializes a new Buffer using string s as its +// NewBufferString creates and initializes a new [Buffer] using string s as its // initial contents. It is intended to prepare a buffer to read an existing // string. // -// In most cases, new(Buffer) (or just declaring a Buffer variable) is -// sufficient to initialize a Buffer. +// In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is +// sufficient to initialize a [Buffer]. func NewBufferString(s string) *Buffer { return &Buffer{buf: []byte(s)} } diff --git a/src/bytes/reader.go b/src/bytes/reader.go index 81c22aa029..9ef49014ed 100644 --- a/src/bytes/reader.go +++ b/src/bytes/reader.go @@ -13,7 +13,7 @@ import ( // A Reader implements the io.Reader, io.ReaderAt, io.WriterTo, io.Seeker, // io.ByteScanner, and io.RuneScanner interfaces by reading from // a byte slice. -// Unlike a Buffer, a Reader is read-only and supports seeking. +// Unlike a [Buffer], a Reader is read-only and supports seeking. // The zero value for Reader operates like a Reader of an empty slice. type Reader struct { s []byte @@ -31,11 +31,11 @@ func (r *Reader) Len() int { } // Size returns the original length of the underlying byte slice. -// Size is the number of bytes available for reading via ReadAt. -// The result is unaffected by any method calls except Reset. +// Size is the number of bytes available for reading via [Reader.ReadAt]. +// The result is unaffected by any method calls except [Reader.Reset]. func (r *Reader) Size() int64 { return int64(len(r.s)) } -// Read implements the io.Reader interface. +// Read implements the [io.Reader] interface. func (r *Reader) Read(b []byte) (n int, err error) { if r.i >= int64(len(r.s)) { return 0, io.EOF @@ -46,7 +46,7 @@ func (r *Reader) Read(b []byte) (n int, err error) { return } -// ReadAt implements the io.ReaderAt interface. +// ReadAt implements the [io.ReaderAt] interface. func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) { // cannot modify state - see io.ReaderAt if off < 0 { @@ -62,7 +62,7 @@ func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) { return } -// ReadByte implements the io.ByteReader interface. +// ReadByte implements the [io.ByteReader] interface. func (r *Reader) ReadByte() (byte, error) { r.prevRune = -1 if r.i >= int64(len(r.s)) { @@ -73,7 +73,7 @@ func (r *Reader) ReadByte() (byte, error) { return b, nil } -// UnreadByte complements ReadByte in implementing the io.ByteScanner interface. +// UnreadByte complements [Reader.ReadByte] in implementing the [io.ByteScanner] interface. func (r *Reader) UnreadByte() error { if r.i <= 0 { return errors.New("bytes.Reader.UnreadByte: at beginning of slice") @@ -83,7 +83,7 @@ func (r *Reader) UnreadByte() error { return nil } -// ReadRune implements the io.RuneReader interface. +// ReadRune implements the [io.RuneReader] interface. func (r *Reader) ReadRune() (ch rune, size int, err error) { if r.i >= int64(len(r.s)) { r.prevRune = -1 @@ -99,7 +99,7 @@ func (r *Reader) ReadRune() (ch rune, size int, err error) { return } -// UnreadRune complements ReadRune in implementing the io.RuneScanner interface. +// UnreadRune complements [Reader.ReadRune] in implementing the [io.RuneScanner] interface. func (r *Reader) UnreadRune() error { if r.i <= 0 { return errors.New("bytes.Reader.UnreadRune: at beginning of slice") @@ -112,7 +112,7 @@ func (r *Reader) UnreadRune() error { return nil } -// Seek implements the io.Seeker interface. +// Seek implements the [io.Seeker] interface. func (r *Reader) Seek(offset int64, whence int) (int64, error) { r.prevRune = -1 var abs int64 @@ -133,7 +133,7 @@ func (r *Reader) Seek(offset int64, whence int) (int64, error) { return abs, nil } -// WriteTo implements the io.WriterTo interface. +// WriteTo implements the [io.WriterTo] interface. func (r *Reader) WriteTo(w io.Writer) (n int64, err error) { r.prevRune = -1 if r.i >= int64(len(r.s)) { @@ -152,8 +152,8 @@ func (r *Reader) WriteTo(w io.Writer) (n int64, err error) { return } -// Reset resets the Reader to be reading from b. +// Reset resets the [Reader.Reader] to be reading from b. func (r *Reader) Reset(b []byte) { *r = Reader{b, 0, -1} } -// NewReader returns a new Reader reading from b. +// NewReader returns a new [Reader.Reader] reading from b. func NewReader(b []byte) *Reader { return &Reader{b, 0, -1} } diff --git a/src/strings/builder.go b/src/strings/builder.go index 299ad51255..189dadb1e7 100644 --- a/src/strings/builder.go +++ b/src/strings/builder.go @@ -10,7 +10,7 @@ import ( "unsafe" ) -// A Builder is used to efficiently build a string using Write methods. +// A Builder is used to efficiently build a string using [Builder.Write] methods. // It minimizes memory copying. The zero value is ready to use. // Do not copy a non-zero Builder. type Builder struct { @@ -57,7 +57,7 @@ func (b *Builder) Len() int { return len(b.buf) } // already written. func (b *Builder) Cap() int { return cap(b.buf) } -// Reset resets the Builder to be empty. +// Reset resets the [Builder] to be empty. func (b *Builder) Reset() { b.addr = nil b.buf = nil diff --git a/src/strings/reader.go b/src/strings/reader.go index 04f31a1e8f..497ffb7a39 100644 --- a/src/strings/reader.go +++ b/src/strings/reader.go @@ -10,8 +10,8 @@ import ( "unicode/utf8" ) -// A Reader implements the io.Reader, io.ReaderAt, io.ByteReader, io.ByteScanner, -// io.RuneReader, io.RuneScanner, io.Seeker, and io.WriterTo interfaces by reading +// A Reader implements the [io.Reader], [io.ReaderAt], [io.ByteReader], [io.ByteScanner], +// [io.RuneReader], [io.RuneScanner], [io.Seeker], and [io.WriterTo] interfaces by reading // from a string. // The zero value for Reader operates like a Reader of an empty string. type Reader struct { @@ -30,12 +30,12 @@ func (r *Reader) Len() int { } // Size returns the original length of the underlying string. -// Size is the number of bytes available for reading via ReadAt. +// Size is the number of bytes available for reading via [Reader.ReadAt]. // The returned value is always the same and is not affected by calls // to any other method. func (r *Reader) Size() int64 { return int64(len(r.s)) } -// Read implements the io.Reader interface. +// Read implements the [io.Reader] interface. func (r *Reader) Read(b []byte) (n int, err error) { if r.i >= int64(len(r.s)) { return 0, io.EOF @@ -46,7 +46,7 @@ func (r *Reader) Read(b []byte) (n int, err error) { return } -// ReadAt implements the io.ReaderAt interface. +// ReadAt implements the [io.ReaderAt] interface. func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) { // cannot modify state - see io.ReaderAt if off < 0 { @@ -62,7 +62,7 @@ func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) { return } -// ReadByte implements the io.ByteReader interface. +// ReadByte implements the [io.ByteReader] interface. func (r *Reader) ReadByte() (byte, error) { r.prevRune = -1 if r.i >= int64(len(r.s)) { @@ -73,7 +73,7 @@ func (r *Reader) ReadByte() (byte, error) { return b, nil } -// UnreadByte implements the io.ByteScanner interface. +// UnreadByte implements the [io.ByteScanner] interface. func (r *Reader) UnreadByte() error { if r.i <= 0 { return errors.New("strings.Reader.UnreadByte: at beginning of string") @@ -83,7 +83,7 @@ func (r *Reader) UnreadByte() error { return nil } -// ReadRune implements the io.RuneReader interface. +// ReadRune implements the [io.RuneReader] interface. func (r *Reader) ReadRune() (ch rune, size int, err error) { if r.i >= int64(len(r.s)) { r.prevRune = -1 @@ -99,7 +99,7 @@ func (r *Reader) ReadRune() (ch rune, size int, err error) { return } -// UnreadRune implements the io.RuneScanner interface. +// UnreadRune implements the [io.RuneScanner] interface. func (r *Reader) UnreadRune() error { if r.i <= 0 { return errors.New("strings.Reader.UnreadRune: at beginning of string") @@ -112,7 +112,7 @@ func (r *Reader) UnreadRune() error { return nil } -// Seek implements the io.Seeker interface. +// Seek implements the [io.Seeker] interface. func (r *Reader) Seek(offset int64, whence int) (int64, error) { r.prevRune = -1 var abs int64 @@ -133,7 +133,7 @@ func (r *Reader) Seek(offset int64, whence int) (int64, error) { return abs, nil } -// WriteTo implements the io.WriterTo interface. +// WriteTo implements the [io.WriterTo] interface. func (r *Reader) WriteTo(w io.Writer) (n int64, err error) { r.prevRune = -1 if r.i >= int64(len(r.s)) { @@ -152,9 +152,9 @@ func (r *Reader) WriteTo(w io.Writer) (n int64, err error) { return } -// Reset resets the Reader to be reading from s. +// Reset resets the [Reader] to be reading from s. func (r *Reader) Reset(s string) { *r = Reader{s, 0, -1} } -// NewReader returns a new Reader reading from s. -// It is similar to bytes.NewBufferString but more efficient and non-writable. +// NewReader returns a new [Reader] reading from s. +// It is similar to [bytes.NewBufferString] but more efficient and non-writable. func NewReader(s string) *Reader { return &Reader{s, 0, -1} } diff --git a/src/strings/replace.go b/src/strings/replace.go index f504fb48df..3b17a55b91 100644 --- a/src/strings/replace.go +++ b/src/strings/replace.go @@ -23,7 +23,7 @@ type replacer interface { WriteString(w io.Writer, s string) (n int, err error) } -// NewReplacer returns a new Replacer from a list of old, new string +// NewReplacer returns a new [Replacer] from a list of old, new string // pairs. Replacements are performed in the order they appear in the // target string, without overlapping matches. The old string // comparisons are done in argument order. diff --git a/src/strings/strings.go b/src/strings/strings.go index ece7237c44..ce79bccf8c 100644 --- a/src/strings/strings.go +++ b/src/strings/strings.go @@ -272,7 +272,7 @@ func genSplit(s, sep string, sepSave, n int) []string { // n < 0: all substrings // // Edge cases for s and sep (for example, empty strings) are handled -// as described in the documentation for Split. +// as described in the documentation for [Split]. // // To split around the first instance of a separator, see Cut. func SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) } @@ -301,7 +301,7 @@ func SplitAfterN(s, sep string, n int) []string { // If sep is empty, Split splits after each UTF-8 sequence. If both s // and sep are empty, Split returns an empty slice. // -// It is equivalent to SplitN with a count of -1. +// It is equivalent to [SplitN] with a count of -1. // // To split around the first instance of a separator, see Cut. func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) } @@ -315,7 +315,7 @@ func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) } // If sep is empty, SplitAfter splits after each UTF-8 sequence. If // both s and sep are empty, SplitAfter returns an empty slice. // -// It is equivalent to SplitAfterN with a count of -1. +// It is equivalent to [SplitAfterN] with a count of -1. func SplitAfter(s, sep string) []string { return genSplit(s, sep, len(sep), -1) } @@ -904,7 +904,7 @@ func Trim(s, cutset string) string { // TrimLeft returns a slice of the string s with all leading // Unicode code points contained in cutset removed. // -// To remove a prefix, use TrimPrefix instead. +// To remove a prefix, use [TrimPrefix] instead. func TrimLeft(s, cutset string) string { if s == "" || cutset == "" { return s @@ -952,7 +952,7 @@ func trimLeftUnicode(s, cutset string) string { // TrimRight returns a slice of the string s, with all trailing // Unicode code points contained in cutset removed. // -// To remove a suffix, use TrimSuffix instead. +// To remove a suffix, use [TrimSuffix] instead. func TrimRight(s, cutset string) string { if s == "" || cutset == "" { return s -- 2.50.0