@@ -72,98 +72,57 @@ var export = jsontext.Internal.Export(&internal.AllowInternalUse)
7272// - Otherwise, the value is encoded according to the value's type
7373// as described in detail below.
7474//
75- // Most Go types have a default JSON representation.
76- // Certain types support specialized formatting according to
77- // a format flag optionally specified in the Go struct tag
78- // for the struct field that contains the current value
79- // (see the “JSON Representation of Go structs” section for more details).
80- //
81- // The representation of each type is as follows:
75+ // Most Go types have a default JSON representation as follows:
8276//
8377// - A Go boolean is encoded as a JSON boolean (e.g., true or false).
84- // It does not support any custom format flags.
8578//
8679// - A Go string is encoded as a JSON string.
87- // It does not support any custom format flags.
8880//
8981// - A Go []byte or [N]byte is encoded as a JSON string containing
90- // the binary value encoded using RFC 4648.
91- // If the format is "base64" or unspecified, then this uses RFC 4648, section 4.
92- // If the format is "base64url", then this uses RFC 4648, section 5.
93- // If the format is "base32", then this uses RFC 4648, section 6.
94- // If the format is "base32hex", then this uses RFC 4648, section 7.
95- // If the format is "base16" or "hex", then this uses RFC 4648, section 8.
96- // If the format is "array", then the bytes value is encoded as a JSON array
97- // where each byte is recursively JSON-encoded as each JSON array element.
82+ // a binary value using Base 64 Encoding per RFC 4648, section 4.
9883//
9984// - A Go integer is encoded as a JSON number without fractions or exponents.
10085// If [StringifyNumbers] is specified or encoding a JSON object name,
10186// then the JSON number is encoded within a JSON string.
102- // It does not support any custom format flags.
10387//
10488// - A Go float is encoded as a JSON number.
10589// If [StringifyNumbers] is specified or encoding a JSON object name,
10690// then the JSON number is encoded within a JSON string.
107- // If the format is "nonfinite", then NaN, +Inf, and -Inf are encoded as
108- // the JSON strings "NaN", "Infinity", and "-Infinity", respectively.
109- // Otherwise, the presence of non-finite numbers results in a [SemanticError].
11091//
11192// - A Go map is encoded as a JSON object, where each Go map key and value
11293// is recursively encoded as a name and value pair in the JSON object.
11394// The Go map key must encode as a JSON string, otherwise this results
11495// in a [SemanticError]. The Go map is traversed in a non-deterministic order.
11596// For deterministic encoding, consider using the [Deterministic] option.
116- // If the format is "emitnull", then a nil map is encoded as a JSON null.
117- // If the format is "emitempty", then a nil map is encoded as an empty JSON object,
118- // regardless of whether [FormatNilMapAsNull] is specified.
119- // Otherwise by default, a nil map is encoded as an empty JSON object.
97+ // By default, a nil map is encoded as an empty JSON object,
98+ // unless the [FormatNilMapAsNull] option is specified.
12099//
121100// - A Go struct is encoded as a JSON object.
122101// See the “JSON Representation of Go structs” section
123102// in the package-level documentation for more details.
124103//
125104// - A Go slice is encoded as a JSON array, where each Go slice element
126105// is recursively JSON-encoded as the elements of the JSON array.
127- // If the format is "emitnull", then a nil slice is encoded as a JSON null.
128- // If the format is "emitempty", then a nil slice is encoded as an empty JSON array,
129- // regardless of whether [FormatNilSliceAsNull] is specified.
130- // Otherwise by default, a nil slice is encoded as an empty JSON array.
106+ // By default, a nil slice is encoded as an empty JSON array,
107+ // unless the [FormatNilSliceAsNull] option is specified.
131108//
132109// - A Go array is encoded as a JSON array, where each Go array element
133110// is recursively JSON-encoded as the elements of the JSON array.
134111// The JSON array length is always identical to the Go array length.
135- // It does not support any custom format flags.
136112//
137113// - A Go pointer is encoded as a JSON null if nil, otherwise it is
138114// the recursively JSON-encoded representation of the underlying value.
139- // Format flags are forwarded to the encoding of the underlying value.
140115//
141116// - A Go interface is encoded as a JSON null if nil, otherwise it is
142117// the recursively JSON-encoded representation of the underlying value.
143- // It does not support any custom format flags.
144118//
145119// - A Go [time.Time] is encoded as a JSON string containing the timestamp
146120// formatted in RFC 3339 with nanosecond precision.
147- // If the format matches one of the format constants declared
148- // in the time package (e.g., RFC1123), then that format is used.
149- // If the format is "unix", "unixmilli", "unixmicro", or "unixnano",
150- // then the timestamp is encoded as a possibly fractional JSON number
151- // of the number of seconds (or milliseconds, microseconds, or nanoseconds)
152- // since the Unix epoch, which is January 1st, 1970 at 00:00:00 UTC.
153- // To avoid a fractional component, round the timestamp to the relevant unit.
154- // Otherwise, the format is used as-is with [time.Time.Format] if non-empty.
155121//
156122// - A Go [time.Duration] currently has no default representation and
157- // requires an explicit format to be specified.
158- // If the format is "sec", "milli", "micro", or "nano",
159- // then the duration is encoded as a possibly fractional JSON number
160- // of the number of seconds (or milliseconds, microseconds, or nanoseconds).
161- // To avoid a fractional component, round the duration to the relevant unit.
162- // If the format is "units", it is encoded as a JSON string formatted using
163- // [time.Duration.String] (e.g., "1h30m" for 1 hour 30 minutes).
164- // If the format is "iso8601", it is encoded as a JSON string using the
165- // ISO 8601 standard for durations (e.g., "PT1H30M" for 1 hour 30 minutes)
166- // using only accurate units of hours, minutes, and seconds.
123+ // results in a [SemanticError], unless the [encoding/json.FormatDurationAsNano]
124+ // option is specified, in which case it is encoded as a JSON number
125+ // without fractions or exponents, representing the duration in nanoseconds.
167126//
168127// - All other Go types (e.g., complex numbers, channels, and functions)
169128// have no default representation and result in a [SemanticError].
@@ -287,10 +246,6 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
287246// as described in detail below.
288247//
289248// Most Go types have a default JSON representation.
290- // Certain types support specialized formatting according to
291- // a format flag optionally specified in the Go struct tag
292- // for the struct field that contains the current value
293- // (see the “JSON Representation of Go structs” section for more details).
294249// A JSON null may be decoded into every supported Go value where
295250// it is equivalent to storing the zero value of the Go value.
296251// If the input JSON kind is not handled by the current Go value type,
@@ -300,20 +255,11 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
300255// The representation of each type is as follows:
301256//
302257// - A Go boolean is decoded from a JSON boolean (e.g., true or false).
303- // It does not support any custom format flags.
304258//
305259// - A Go string is decoded from a JSON string.
306- // It does not support any custom format flags.
307- //
308- // - A Go []byte or [N]byte is decoded from a JSON string
309- // containing the binary value encoded using RFC 4648.
310- // If the format is "base64" or unspecified, then this uses RFC 4648, section 4.
311- // If the format is "base64url", then this uses RFC 4648, section 5.
312- // If the format is "base32", then this uses RFC 4648, section 6.
313- // If the format is "base32hex", then this uses RFC 4648, section 7.
314- // If the format is "base16" or "hex", then this uses RFC 4648, section 8.
315- // If the format is "array", then the Go slice or array is decoded from a
316- // JSON array where each JSON element is recursively decoded for each byte.
260+ //
261+ // - A Go []byte or [N]byte is decoded from a JSON string containing
262+ // a binary value using Base 64 Encoding per RFC 4648, section 4.
317263// When decoding into a non-nil []byte, the slice length is reset to zero
318264// and the decoded input is appended to it.
319265// When decoding into a [N]byte, the input must decode to exactly N bytes,
@@ -325,23 +271,18 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
325271// It fails with a [SemanticError] if the JSON number
326272// has a fractional or exponent component.
327273// It also fails if it overflows the representation of the Go integer type.
328- // It does not support any custom format flags.
329274//
330275// - A Go float is decoded from a JSON number.
331276// It must be decoded from a JSON string containing a JSON number
332277// if [StringifyNumbers] is specified or decoding a JSON object name.
333278// It fails if it overflows the representation of the Go float type.
334- // If the format is "nonfinite", then the JSON strings
335- // "NaN", "Infinity", and "-Infinity" are decoded as NaN, +Inf, and -Inf.
336- // Otherwise, the presence of such strings results in a [SemanticError].
337279//
338280// - A Go map is decoded from a JSON object,
339281// where each JSON object name and value pair is recursively decoded
340282// as the Go map key and value. Maps are not cleared.
341283// If the Go map is nil, then a new map is allocated to decode into.
342284// If the decoded key matches an existing Go map entry, the entry value
343285// is reused by decoding the JSON object value into it.
344- // The formats "emitnull" and "emitempty" have no effect when decoding.
345286//
346287// - A Go struct is decoded from a JSON object.
347288// See the “JSON Representation of Go structs” section
@@ -351,20 +292,17 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
351292// is recursively decoded and appended to the Go slice.
352293// Before appending into a Go slice, a new slice is allocated if it is nil,
353294// otherwise the slice length is reset to zero.
354- // The formats "emitnull" and "emitempty" have no effect when decoding.
355295//
356296// - A Go array is decoded from a JSON array, where each JSON array element
357297// is recursively decoded as each corresponding Go array element.
358298// Each Go array element is zeroed before decoding into it.
359299// It fails with a [SemanticError] if the JSON array does not contain
360300// the exact same number of elements as the Go array.
361- // It does not support any custom format flags.
362301//
363302// - A Go pointer is decoded based on the JSON kind and underlying Go type.
364303// If the input is a JSON null, then this stores a nil pointer.
365304// Otherwise, it allocates a new underlying value if the pointer is nil,
366305// and recursively JSON decodes into the underlying value.
367- // Format flags are forwarded to the decoding of the underlying type.
368306//
369307// - A Go interface is decoded based on the JSON kind and underlying Go type.
370308// If the input is a JSON null, then this stores a nil interface value.
@@ -376,28 +314,15 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
376314// For example, unmarshaling into a nil io.Reader fails since
377315// there is no concrete type to populate the interface value with.
378316// Otherwise an underlying value exists and it recursively decodes
379- // the JSON input into it. It does not support any custom format flags.
317+ // the JSON input into it.
380318//
381319// - A Go [time.Time] is decoded from a JSON string containing the time
382320// formatted in RFC 3339 with nanosecond precision.
383- // If the format matches one of the format constants declared in
384- // the time package (e.g., RFC1123), then that format is used for parsing.
385- // If the format is "unix", "unixmilli", "unixmicro", or "unixnano",
386- // then the timestamp is decoded from an optionally fractional JSON number
387- // of the number of seconds (or milliseconds, microseconds, or nanoseconds)
388- // since the Unix epoch, which is January 1st, 1970 at 00:00:00 UTC.
389- // Otherwise, the format is used as-is with [time.Time.Parse] if non-empty.
390321//
391322// - A Go [time.Duration] currently has no default representation and
392- // requires an explicit format to be specified.
393- // If the format is "sec", "milli", "micro", or "nano",
394- // then the duration is decoded from an optionally fractional JSON number
395- // of the number of seconds (or milliseconds, microseconds, or nanoseconds).
396- // If the format is "units", it is decoded from a JSON string parsed using
397- // [time.ParseDuration] (e.g., "1h30m" for 1 hour 30 minutes).
398- // If the format is "iso8601", it is decoded from a JSON string using the
399- // ISO 8601 standard for durations (e.g., "PT1H30M" for 1 hour 30 minutes)
400- // accepting only accurate units of hours, minutes, or seconds.
323+ // results in a [SemanticError], unless the [encoding/json.FormatDurationAsNano]
324+ // option is specified, in which case it is decoded as a JSON number
325+ // without fractions or exponents, representing the duration in nanoseconds.
401326//
402327// - All other Go types (e.g., complex numbers, channels, and functions)
403328// have no default representation and result in a [SemanticError].
0 commit comments