// Writer is the interface that wraps the basic Write method.
//
// Write writes len(p) bytes from p to the underlying data stream.
// It returns the number of bytes written from p (0 <= n <= len(p))
// and any error encountered that caused the write to stop early.
// Write must return a non-nil error if it returns n < len(p).
// Write must not modify the slice data, even temporarily.
//
// Implementations must not retain p.
type Writer interface {
	Write(p []byte) (n int, err error)
}

// 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.
func (b *Buffer) Write(p []byte) (n int, err error) {
	// 最後の読み込み操作の状態を設定する、Unread系の動作に必要らしい
	b.lastRead = opInvalid
	// キャパシティが足りているか確認して足りていない場合はokがfalseを返す
	// mは書き込まれるインデックスを返す
	m, ok := b.tryGrowByReslice(len(p))
	if !ok {
		// キャパシティが足らない場合は、キャパシティを変更する
		m = b.grow(len(p))
	}
	// bのmから最後までにpをコピーする 
	return copy(b.buf[m:], p), nil
}

// tryGrowByReslice is a inlineable version of grow for the fast-case where the
// internal buffer only needs to be resliced.
// It returns the index where bytes should be written and whether it succeeded.
func (b *Buffer) tryGrowByReslice(n int) (int, bool) {
	// nが空いているキャパシティに入りきる場合はバッファの内容を最初からl+nまでにする（n分だけ0で埋めてlenを伸ばす）
	if l := len(b.buf); n <= cap(b.buf)-l {
		b.buf = b.buf[:l+n]
		return l, true
	}
	return 0, false
}

const maxInt = int(^uint(0) >> 1)

// Len returns the number of bytes of the unread portion of the buffer;
// b.Len() == len(b.Bytes()).
func (b *Buffer) Len() int { return len(b.buf) - b.off }

// makeSlice allocates a slice of size n. If the allocation fails, it panics
// with ErrTooLarge.
func makeSlice(n int) []byte {
	// If the make fails, give a known error.
	defer func() {
		if recover() != nil {
			panic(ErrTooLarge)
		}
	}()
	return make([]byte, n)
}

// grow grows the buffer to guarantee space for n more bytes.
// It returns the index where bytes should be written.
// If the buffer can't grow it will panic with ErrTooLarge.
func (b *Buffer) grow(n int) int {
	m := b.Len()
	// バッファに未読がなく、オフセットが0以外の場合はリセットする
	// If buffer is empty, reset to recover space.
	if m == 0 && b.off != 0 {
		b.Reset()
	}
	// nが残りのキャパシティに入りきる場合はバッファのlenを伸ばす
	// Writeメソッドからgrow関数が呼び出された場合はWriteメソッド側で先にチェックされている
	// Try to grow by means of a reslice.
	if i, ok := b.tryGrowByReslice(n); ok {
		return i
	}
	// バッファがnilで、nがsmallBufferSize以下の場合は、smallBufferSizeでバッファを作成する
	if b.buf == nil && n <= smallBufferSize {
		b.buf = make([]byte, n, smallBufferSize)
		return 0
	}
	c := cap(b.buf)
	// nがキャパシティの半分から未読のバイト数を引いたもの以下の場合
	// バッファに現在のオフセットから最後までをコピーする
	if n <= c/2-m {
		// We can slide things down instead of allocating a new
		// slice. We only need m+n <= c to slide, but
		// we instead let capacity get twice as large so we
		// don't spend all our time copying.
		// ここで読み込み済みのバイトは消える
		copy(b.buf, b.buf[b.off:])
	// キャパシティが、Intの最大値からキャパシティとnを引いたものより大きい場合はエラー
	} else if c > maxInt-c-n {
		panic(ErrTooLarge)
	// キャパシティが小さい場合は、現在のキャパシティの2倍にnを加えたサイズのスライスをバッファにしてコピーする
	} else {
		// Not enough space anywhere, we need to allocate.
		buf := makeSlice(2*c + n)
		// ここで読み込み済みのバイトは消える
		copy(buf, b.buf[b.off:])
		b.buf = buf
	}
	// Restore b.off and len(b.buf).
	b.off = 0
	// バッファの要素数を未読バイトとnの合計に設定する
	b.buf = b.buf[:m+n]
	return m
}

0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 => 0

ビットを反転

1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 => 18446744073709551615

最初のビットをシフトして「0」にする

0111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 => 9223372036854775807

c=12（キャパシティ）
l=9（要素数、実際に入っているバイト数）
m=2（未読のバイト数）

oooo oooo oooo
---- ---x x

oooo oooo oooo
xx

c=12（キャパシティ）
l=9（要素数、実際に入っているバイト数）
m=7（未読のバイト数）

oooo oooo oooo
--xx xxxx x