encoding/json/jsontext: rename Encoder.UnusedBuffer as Encoder.AvailableBuffer

This follows the precedent set by:

	bufio.Writer.AvailableBuffer
	bytes.Buffer.AvailableBuffer

both with methods that return a zero-length buffer that
is intended to only be used with a following Write call.

This keeps the older UnusedBuffer method around so that
at least one commit that has both methods for migration purposes.

Updates #71497

Change-Id: I3815f593e09f645280ae5ad9cbdd63a6c147123b
Reviewed-on: https://go-review.googlesource.com/c/go/+/683896
Reviewed-by: Damien Neil <dneil@google.com>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

src/encoding/json/jsontext/encode.go

@@ -74,8 +74,8 @@ type encodeBuffer struct {
 
 	// maxValue is the approximate maximum Value size passed to WriteValue.
 	maxValue int
-	// unusedCache is the buffer returned by the UnusedBuffer method.
+	// availBuffer is the buffer returned by the AvailableBuffer method.
-	unusedCache []byte
+	availBuffer []byte // always has zero length
 	// bufStats is statistics about buffer utilization.
 	// It is only used with pooled encoders in pools.go.
 	bufStats bufferStatistics
@@ -465,9 +465,9 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 		isVerbatim := safeASCII || !jsonwire.NeedEscape(b[pos+len(`"`):len(b)-len(`"`)])
 		if !isVerbatim {
 			var err error
-			b2 := append(e.unusedCache, b[pos+len(`"`):len(b)-len(`"`)]...)
+			b2 := append(e.availBuffer, b[pos+len(`"`):len(b)-len(`"`)]...)
 			b, err = jsonwire.AppendQuote(b[:pos], string(b2), &e.Flags)
-			e.unusedCache = b2[:0]
+			e.availBuffer = b2[:0]
 			if err != nil {
 				return wrapSyntacticError(e, err, pos, +1)
 			}
@@ -900,20 +900,25 @@ func (e *Encoder) OutputOffset() int64 {
 	return e.s.previousOffsetEnd()
 }
 
-// UnusedBuffer returns a zero-length buffer with a possible non-zero capacity.
+// Deprecated: Use [Encoder.AvailableBuffer] instead.
+func (e *Encoder) UnusedBuffer() []byte {
+	return e.AvailableBuffer()
+}
+
+// AvailableBuffer returns a zero-length buffer with a possible non-zero capacity.
 // This buffer is intended to be used to populate a [Value]
 // being passed to an immediately succeeding [Encoder.WriteValue] call.
 //
 // Example usage:
 //
-//	b := d.UnusedBuffer()
+//	b := d.AvailableBuffer()
 //	b = append(b, '"')
 //	b = appendString(b, v) // append the string formatting of v
 //	b = append(b, '"')
 //	... := d.WriteValue(b)
 //
 // It is the user's responsibility to ensure that the value is valid JSON.
-func (e *Encoder) UnusedBuffer() []byte {
+func (e *Encoder) AvailableBuffer() []byte {
 	// NOTE: We don't return e.buf[len(e.buf):cap(e.buf)] since WriteValue would
 	// need to take special care to avoid mangling the data while reformatting.
 	// WriteValue can't easily identify whether the input Value aliases e.buf
@@ -921,10 +926,10 @@ func (e *Encoder) UnusedBuffer() []byte {
 	// Should this ever alias e.buf, we need to consider how it operates with
 	// the specialized performance optimization for bytes.Buffer.
 	n := 1 << bits.Len(uint(e.s.maxValue|63)) // fast approximation for max length
-	if cap(e.s.unusedCache) < n {
+	if cap(e.s.availBuffer) < n {
-		e.s.unusedCache = make([]byte, 0, n)
+		e.s.availBuffer = make([]byte, 0, n)
 	}
-	return e.s.unusedCache
+	return e.s.availBuffer
 }
 
 // StackDepth returns the depth of the state machine for written JSON data.

src/encoding/json/v2/arshal_inlined.go

@@ -113,7 +113,7 @@ func marshalInlinedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *j
 		mk := newAddressableValue(m.Type().Key())
 		mv := newAddressableValue(m.Type().Elem())
 		marshalKey := func(mk addressableValue) error {
-			b, err := jsonwire.AppendQuote(enc.UnusedBuffer(), mk.String(), &mo.Flags)
+			b, err := jsonwire.AppendQuote(enc.AvailableBuffer(), mk.String(), &mo.Flags)
 			if err != nil {
 				return newMarshalErrorBefore(enc, m.Type().Key(), err)
 			}

src/encoding/json/v2_decode.go

@@ -199,7 +199,7 @@ func (n Number) MarshalJSONTo(enc *jsontext.Encoder) error {
 	}
 	n = cmp.Or(n, "0")
 	var num []byte
-	val := enc.UnusedBuffer()
+	val := enc.AvailableBuffer()
 	if stringify {
 		val = append(val, '"')
 		val = append(val, n...)