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>

diff --git a/src/encoding/json/jsontext/encode.go b/src/encoding/json/jsontext/encode.go
index 4853a11059ee9f0b82a694d67d3feda44ab94f39..1e0861e9f0ebf3583288a094fd1302382aea1a20 100644 (file)
--- a/src/encoding/json/jsontext/encode.go
+++ b/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.
-       unusedCache []byte
+       // availBuffer is the buffer returned by the AvailableBuffer method.
+       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 {
-               e.s.unusedCache = make([]byte, 0, n)
+       if cap(e.s.availBuffer) < 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.

diff --git a/src/encoding/json/v2/arshal_inlined.go b/src/encoding/json/v2/arshal_inlined.go
index 0b5782fdccc8363749760c50db5c711ee3da7359..6299cc4a428ae17a61bff45ca779cfbfc2f2f9d1 100644 (file)
--- a/src/encoding/json/v2/arshal_inlined.go
+++ b/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)
                        }

diff --git a/src/encoding/json/v2_decode.go b/src/encoding/json/v2_decode.go
index 4b9e8509395d340a0eb4d55452f8e19cbacb4b56..c82ee903c33c112f0e972d91560742e1e0f54f15 100644 (file)
--- a/src/encoding/json/v2_decode.go
+++ b/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...)