arshal.go 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581
  1. // Copyright 2020 The Go Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style
  3. // license that can be found in the LICENSE file.
  4. package json
  5. import (
  6. "bytes"
  7. "io"
  8. "reflect"
  9. "slices"
  10. "strings"
  11. "sync"
  12. "github.com/go-json-experiment/json/internal"
  13. "github.com/go-json-experiment/json/internal/jsonflags"
  14. "github.com/go-json-experiment/json/internal/jsonopts"
  15. "github.com/go-json-experiment/json/jsontext"
  16. )
  17. // export exposes internal functionality of the "jsontext" package.
  18. var export = jsontext.Internal.Export(&internal.AllowInternalUse)
  19. // mayReuseOpt reuses coderOpts if joining opts with the coderOpts
  20. // would produce the equivalent set of options.
  21. func mayReuseOpt(coderOpts *jsonopts.Struct, opts []Options) *jsonopts.Struct {
  22. switch len(opts) {
  23. // In the common case, the caller plumbs down options from the caller's caller,
  24. // which is usually the [jsonopts.Struct] constructed by the top-level arshal call.
  25. case 1:
  26. o, _ := opts[0].(*jsonopts.Struct)
  27. if o == coderOpts {
  28. return coderOpts
  29. }
  30. // If the caller provides no options, then just reuse the coder's options,
  31. // which should only contain encoding/decoding related flags.
  32. case 0:
  33. // TODO: This is buggy if coderOpts ever contains non-coder options.
  34. return coderOpts
  35. }
  36. return nil
  37. }
  38. var structOptionsPool = &sync.Pool{New: func() any { return new(jsonopts.Struct) }}
  39. func getStructOptions() *jsonopts.Struct {
  40. return structOptionsPool.Get().(*jsonopts.Struct)
  41. }
  42. func putStructOptions(o *jsonopts.Struct) {
  43. *o = jsonopts.Struct{}
  44. structOptionsPool.Put(o)
  45. }
  46. // Marshal serializes a Go value as a []byte according to the provided
  47. // marshal and encode options (while ignoring unmarshal or decode options).
  48. // It does not terminate the output with a newline.
  49. //
  50. // Type-specific marshal functions and methods take precedence
  51. // over the default representation of a value.
  52. // Functions or methods that operate on *T are only called when encoding
  53. // a value of type T (by taking its address) or a non-nil value of *T.
  54. // Marshal ensures that a value is always addressable
  55. // (by boxing it on the heap if necessary) so that
  56. // these functions and methods can be consistently called. For performance,
  57. // it is recommended that Marshal be passed a non-nil pointer to the value.
  58. //
  59. // The input value is encoded as JSON according the following rules:
  60. //
  61. // - If any type-specific functions in a [WithMarshalers] option match
  62. // the value type, then those functions are called to encode the value.
  63. // If all applicable functions return [SkipFunc],
  64. // then the value is encoded according to subsequent rules.
  65. //
  66. // - If the value type implements [MarshalerTo],
  67. // then the MarshalJSONTo method is called to encode the value.
  68. //
  69. // - If the value type implements [Marshaler],
  70. // then the MarshalJSON method is called to encode the value.
  71. //
  72. // - If the value type implements [encoding.TextMarshaler],
  73. // then the MarshalText method is called to encode the value and
  74. // subsequently encode its result as a JSON string.
  75. //
  76. // - Otherwise, the value is encoded according to the value's type
  77. // as described in detail below.
  78. //
  79. // Most Go types have a default JSON representation.
  80. // Certain types support specialized formatting according to
  81. // a format flag optionally specified in the Go struct tag
  82. // for the struct field that contains the current value
  83. // (see the “JSON Representation of Go structs” section for more details).
  84. //
  85. // The representation of each type is as follows:
  86. //
  87. // - A Go boolean is encoded as a JSON boolean (e.g., true or false).
  88. // It does not support any custom format flags.
  89. //
  90. // - A Go string is encoded as a JSON string.
  91. // It does not support any custom format flags.
  92. //
  93. // - A Go []byte or [N]byte is encoded as a JSON string containing
  94. // the binary value encoded using RFC 4648.
  95. // If the format is "base64" or unspecified, then this uses RFC 4648, section 4.
  96. // If the format is "base64url", then this uses RFC 4648, section 5.
  97. // If the format is "base32", then this uses RFC 4648, section 6.
  98. // If the format is "base32hex", then this uses RFC 4648, section 7.
  99. // If the format is "base16" or "hex", then this uses RFC 4648, section 8.
  100. // If the format is "array", then the bytes value is encoded as a JSON array
  101. // where each byte is recursively JSON-encoded as each JSON array element.
  102. //
  103. // - A Go integer is encoded as a JSON number without fractions or exponents.
  104. // If [StringifyNumbers] is specified or encoding a JSON object name,
  105. // then the JSON number is encoded within a JSON string.
  106. // It does not support any custom format flags.
  107. //
  108. // - A Go float is encoded as a JSON number.
  109. // If [StringifyNumbers] is specified or encoding a JSON object name,
  110. // then the JSON number is encoded within a JSON string.
  111. // If the format is "nonfinite", then NaN, +Inf, and -Inf are encoded as
  112. // the JSON strings "NaN", "Infinity", and "-Infinity", respectively.
  113. // Otherwise, the presence of non-finite numbers results in a [SemanticError].
  114. //
  115. // - A Go map is encoded as a JSON object, where each Go map key and value
  116. // is recursively encoded as a name and value pair in the JSON object.
  117. // The Go map key must encode as a JSON string, otherwise this results
  118. // in a [SemanticError]. The Go map is traversed in a non-deterministic order.
  119. // For deterministic encoding, consider using the [Deterministic] option.
  120. // If the format is "emitnull", then a nil map is encoded as a JSON null.
  121. // If the format is "emitempty", then a nil map is encoded as an empty JSON object,
  122. // regardless of whether [FormatNilMapAsNull] is specified.
  123. // Otherwise by default, a nil map is encoded as an empty JSON object.
  124. //
  125. // - A Go struct is encoded as a JSON object.
  126. // See the “JSON Representation of Go structs” section
  127. // in the package-level documentation for more details.
  128. //
  129. // - A Go slice is encoded as a JSON array, where each Go slice element
  130. // is recursively JSON-encoded as the elements of the JSON array.
  131. // If the format is "emitnull", then a nil slice is encoded as a JSON null.
  132. // If the format is "emitempty", then a nil slice is encoded as an empty JSON array,
  133. // regardless of whether [FormatNilSliceAsNull] is specified.
  134. // Otherwise by default, a nil slice is encoded as an empty JSON array.
  135. //
  136. // - A Go array is encoded as a JSON array, where each Go array element
  137. // is recursively JSON-encoded as the elements of the JSON array.
  138. // The JSON array length is always identical to the Go array length.
  139. // It does not support any custom format flags.
  140. //
  141. // - A Go pointer is encoded as a JSON null if nil, otherwise it is
  142. // the recursively JSON-encoded representation of the underlying value.
  143. // Format flags are forwarded to the encoding of the underlying value.
  144. //
  145. // - A Go interface is encoded as a JSON null if nil, otherwise it is
  146. // the recursively JSON-encoded representation of the underlying value.
  147. // It does not support any custom format flags.
  148. //
  149. // - A Go [time.Time] is encoded as a JSON string containing the timestamp
  150. // formatted in RFC 3339 with nanosecond precision.
  151. // If the format matches one of the format constants declared
  152. // in the time package (e.g., RFC1123), then that format is used.
  153. // If the format is "unix", "unixmilli", "unixmicro", or "unixnano",
  154. // then the timestamp is encoded as a JSON number of the number of seconds
  155. // (or milliseconds, microseconds, or nanoseconds) since the Unix epoch,
  156. // which is January 1st, 1970 at 00:00:00 UTC.
  157. // Otherwise, the format is used as-is with [time.Time.Format] if non-empty.
  158. //
  159. // - A Go [time.Duration] is encoded as a JSON string containing the duration
  160. // formatted according to [time.Duration.String].
  161. // If the format is "sec", "milli", "micro", or "nano",
  162. // then the duration is encoded as a JSON number of the number of seconds
  163. // (or milliseconds, microseconds, or nanoseconds) in the duration.
  164. // If the format is "base60", it is encoded as a JSON string
  165. // using the "H:MM:SS.SSSSSSSSS" representation.
  166. // If the format is "units", it uses [time.Duration.String].
  167. //
  168. // - All other Go types (e.g., complex numbers, channels, and functions)
  169. // have no default representation and result in a [SemanticError].
  170. //
  171. // JSON cannot represent cyclic data structures and Marshal does not handle them.
  172. // Passing cyclic structures will result in an error.
  173. func Marshal(in any, opts ...Options) (out []byte, err error) {
  174. enc := export.GetBufferedEncoder(opts...)
  175. defer export.PutBufferedEncoder(enc)
  176. xe := export.Encoder(enc)
  177. xe.Flags.Set(jsonflags.OmitTopLevelNewline | 1)
  178. err = marshalEncode(enc, in, &xe.Struct)
  179. if err != nil && xe.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  180. return nil, internal.TransformMarshalError(in, err)
  181. }
  182. return bytes.Clone(xe.Buf), err
  183. }
  184. // MarshalWrite serializes a Go value into an [io.Writer] according to the provided
  185. // marshal and encode options (while ignoring unmarshal or decode options).
  186. // It does not terminate the output with a newline.
  187. // See [Marshal] for details about the conversion of a Go value into JSON.
  188. func MarshalWrite(out io.Writer, in any, opts ...Options) (err error) {
  189. enc := export.GetStreamingEncoder(out, opts...)
  190. defer export.PutStreamingEncoder(enc)
  191. xe := export.Encoder(enc)
  192. xe.Flags.Set(jsonflags.OmitTopLevelNewline | 1)
  193. err = marshalEncode(enc, in, &xe.Struct)
  194. if err != nil && xe.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  195. return internal.TransformMarshalError(in, err)
  196. }
  197. return err
  198. }
  199. // MarshalEncode serializes a Go value into an [jsontext.Encoder] according to
  200. // the provided marshal options (while ignoring unmarshal, encode, or decode options).
  201. // Unlike [Marshal] and [MarshalWrite], encode options are ignored because
  202. // they must have already been specified on the provided [jsontext.Encoder].
  203. // See [Marshal] for details about the conversion of a Go value into JSON.
  204. func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) (err error) {
  205. xe := export.Encoder(out)
  206. mo := mayReuseOpt(&xe.Struct, opts)
  207. if mo == nil {
  208. mo = getStructOptions()
  209. defer putStructOptions(mo)
  210. mo.Join(opts...)
  211. mo.CopyCoderOptions(&xe.Struct)
  212. }
  213. err = marshalEncode(out, in, mo)
  214. if err != nil && mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  215. return internal.TransformMarshalError(in, err)
  216. }
  217. return err
  218. }
  219. func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err error) {
  220. v := reflect.ValueOf(in)
  221. if !v.IsValid() || (v.Kind() == reflect.Pointer && v.IsNil()) {
  222. return out.WriteToken(jsontext.Null)
  223. }
  224. // Shallow copy non-pointer values to obtain an addressable value.
  225. // It is beneficial to performance to always pass pointers to avoid this.
  226. forceAddr := v.Kind() != reflect.Pointer
  227. if forceAddr {
  228. v2 := reflect.New(v.Type())
  229. v2.Elem().Set(v)
  230. v = v2
  231. }
  232. va := addressableValue{v.Elem(), forceAddr} // dereferenced pointer is always addressable
  233. t := va.Type()
  234. // Lookup and call the marshal function for this type.
  235. marshal := lookupArshaler(t).marshal
  236. if mo.Marshalers != nil {
  237. marshal, _ = mo.Marshalers.(*Marshalers).lookup(marshal, t)
  238. }
  239. if err := marshal(out, va, mo); err != nil {
  240. if !mo.Flags.Get(jsonflags.AllowDuplicateNames) {
  241. export.Encoder(out).Tokens.InvalidateDisabledNamespaces()
  242. }
  243. return err
  244. }
  245. return nil
  246. }
  247. // Unmarshal decodes a []byte input into a Go value according to the provided
  248. // unmarshal and decode options (while ignoring marshal or encode options).
  249. // The input must be a single JSON value with optional whitespace interspersed.
  250. // The output must be a non-nil pointer.
  251. //
  252. // Type-specific unmarshal functions and methods take precedence
  253. // over the default representation of a value.
  254. // Functions or methods that operate on *T are only called when decoding
  255. // a value of type T (by taking its address) or a non-nil value of *T.
  256. // Unmarshal ensures that a value is always addressable
  257. // (by boxing it on the heap if necessary) so that
  258. // these functions and methods can be consistently called.
  259. //
  260. // The input is decoded into the output according the following rules:
  261. //
  262. // - If any type-specific functions in a [WithUnmarshalers] option match
  263. // the value type, then those functions are called to decode the JSON
  264. // value. If all applicable functions return [SkipFunc],
  265. // then the input is decoded according to subsequent rules.
  266. //
  267. // - If the value type implements [UnmarshalerFrom],
  268. // then the UnmarshalJSONFrom method is called to decode the JSON value.
  269. //
  270. // - If the value type implements [Unmarshaler],
  271. // then the UnmarshalJSON method is called to decode the JSON value.
  272. //
  273. // - If the value type implements [encoding.TextUnmarshaler],
  274. // then the input is decoded as a JSON string and
  275. // the UnmarshalText method is called with the decoded string value.
  276. // This fails with a [SemanticError] if the input is not a JSON string.
  277. //
  278. // - Otherwise, the JSON value is decoded according to the value's type
  279. // as described in detail below.
  280. //
  281. // Most Go types have a default JSON representation.
  282. // Certain types support specialized formatting according to
  283. // a format flag optionally specified in the Go struct tag
  284. // for the struct field that contains the current value
  285. // (see the “JSON Representation of Go structs” section for more details).
  286. // A JSON null may be decoded into every supported Go value where
  287. // it is equivalent to storing the zero value of the Go value.
  288. // If the input JSON kind is not handled by the current Go value type,
  289. // then this fails with a [SemanticError]. Unless otherwise specified,
  290. // the decoded value replaces any pre-existing value.
  291. //
  292. // The representation of each type is as follows:
  293. //
  294. // - A Go boolean is decoded from a JSON boolean (e.g., true or false).
  295. // It does not support any custom format flags.
  296. //
  297. // - A Go string is decoded from a JSON string.
  298. // It does not support any custom format flags.
  299. //
  300. // - A Go []byte or [N]byte is decoded from a JSON string
  301. // containing the binary value encoded using RFC 4648.
  302. // If the format is "base64" or unspecified, then this uses RFC 4648, section 4.
  303. // If the format is "base64url", then this uses RFC 4648, section 5.
  304. // If the format is "base32", then this uses RFC 4648, section 6.
  305. // If the format is "base32hex", then this uses RFC 4648, section 7.
  306. // If the format is "base16" or "hex", then this uses RFC 4648, section 8.
  307. // If the format is "array", then the Go slice or array is decoded from a
  308. // JSON array where each JSON element is recursively decoded for each byte.
  309. // When decoding into a non-nil []byte, the slice length is reset to zero
  310. // and the decoded input is appended to it.
  311. // When decoding into a [N]byte, the input must decode to exactly N bytes,
  312. // otherwise it fails with a [SemanticError].
  313. //
  314. // - A Go integer is decoded from a JSON number.
  315. // It must be decoded from a JSON string containing a JSON number
  316. // if [StringifyNumbers] is specified or decoding a JSON object name.
  317. // It fails with a [SemanticError] if the JSON number
  318. // has a fractional or exponent component.
  319. // It also fails if it overflows the representation of the Go integer type.
  320. // It does not support any custom format flags.
  321. //
  322. // - A Go float is decoded from a JSON number.
  323. // It must be decoded from a JSON string containing a JSON number
  324. // if [StringifyNumbers] is specified or decoding a JSON object name.
  325. // It fails if it overflows the representation of the Go float type.
  326. // If the format is "nonfinite", then the JSON strings
  327. // "NaN", "Infinity", and "-Infinity" are decoded as NaN, +Inf, and -Inf.
  328. // Otherwise, the presence of such strings results in a [SemanticError].
  329. //
  330. // - A Go map is decoded from a JSON object,
  331. // where each JSON object name and value pair is recursively decoded
  332. // as the Go map key and value. Maps are not cleared.
  333. // If the Go map is nil, then a new map is allocated to decode into.
  334. // If the decoded key matches an existing Go map entry, the entry value
  335. // is reused by decoding the JSON object value into it.
  336. // The formats "emitnull" and "emitempty" have no effect when decoding.
  337. //
  338. // - A Go struct is decoded from a JSON object.
  339. // See the “JSON Representation of Go structs” section
  340. // in the package-level documentation for more details.
  341. //
  342. // - A Go slice is decoded from a JSON array, where each JSON element
  343. // is recursively decoded and appended to the Go slice.
  344. // Before appending into a Go slice, a new slice is allocated if it is nil,
  345. // otherwise the slice length is reset to zero.
  346. // The formats "emitnull" and "emitempty" have no effect when decoding.
  347. //
  348. // - A Go array is decoded from a JSON array, where each JSON array element
  349. // is recursively decoded as each corresponding Go array element.
  350. // Each Go array element is zeroed before decoding into it.
  351. // It fails with a [SemanticError] if the JSON array does not contain
  352. // the exact same number of elements as the Go array.
  353. // It does not support any custom format flags.
  354. //
  355. // - A Go pointer is decoded based on the JSON kind and underlying Go type.
  356. // If the input is a JSON null, then this stores a nil pointer.
  357. // Otherwise, it allocates a new underlying value if the pointer is nil,
  358. // and recursively JSON decodes into the underlying value.
  359. // Format flags are forwarded to the decoding of the underlying type.
  360. //
  361. // - A Go interface is decoded based on the JSON kind and underlying Go type.
  362. // If the input is a JSON null, then this stores a nil interface value.
  363. // Otherwise, a nil interface value of an empty interface type is initialized
  364. // with a zero Go bool, string, float64, map[string]any, or []any if the
  365. // input is a JSON boolean, string, number, object, or array, respectively.
  366. // If the interface value is still nil, then this fails with a [SemanticError]
  367. // since decoding could not determine an appropriate Go type to decode into.
  368. // For example, unmarshaling into a nil io.Reader fails since
  369. // there is no concrete type to populate the interface value with.
  370. // Otherwise an underlying value exists and it recursively decodes
  371. // the JSON input into it. It does not support any custom format flags.
  372. //
  373. // - A Go [time.Time] is decoded from a JSON string containing the time
  374. // formatted in RFC 3339 with nanosecond precision.
  375. // If the format matches one of the format constants declared in
  376. // the time package (e.g., RFC1123), then that format is used for parsing.
  377. // If the format is "unix", "unixmilli", "unixmicro", or "unixnano",
  378. // then the timestamp is decoded from a JSON number of the number of seconds
  379. // (or milliseconds, microseconds, or nanoseconds) since the Unix epoch,
  380. // which is January 1st, 1970 at 00:00:00 UTC.
  381. // Otherwise, the format is used as-is with [time.Time.Parse] if non-empty.
  382. //
  383. // - A Go [time.Duration] is decoded from a JSON string by
  384. // passing the decoded string to [time.ParseDuration].
  385. // If the format is "sec", "milli", "micro", or "nano",
  386. // then the duration is decoded from a JSON number of the number of seconds
  387. // (or milliseconds, microseconds, or nanoseconds) in the duration.
  388. // If the format is "base60", it is decoded from a JSON string
  389. // using the "H:MM:SS.SSSSSSSSS" representation.
  390. // If the format is "units", it uses [time.ParseDuration].
  391. //
  392. // - All other Go types (e.g., complex numbers, channels, and functions)
  393. // have no default representation and result in a [SemanticError].
  394. //
  395. // In general, unmarshaling follows merge semantics (similar to RFC 7396)
  396. // where the decoded Go value replaces the destination value
  397. // for any JSON kind other than an object.
  398. // For JSON objects, the input object is merged into the destination value
  399. // where matching object members recursively apply merge semantics.
  400. func Unmarshal(in []byte, out any, opts ...Options) (err error) {
  401. dec := export.GetBufferedDecoder(in, opts...)
  402. defer export.PutBufferedDecoder(dec)
  403. xd := export.Decoder(dec)
  404. err = unmarshalFull(dec, out, &xd.Struct)
  405. if err != nil && xd.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  406. return internal.TransformUnmarshalError(out, err)
  407. }
  408. return err
  409. }
  410. // UnmarshalRead deserializes a Go value from an [io.Reader] according to the
  411. // provided unmarshal and decode options (while ignoring marshal or encode options).
  412. // The input must be a single JSON value with optional whitespace interspersed.
  413. // It consumes the entirety of [io.Reader] until [io.EOF] is encountered,
  414. // without reporting an error for EOF. The output must be a non-nil pointer.
  415. // See [Unmarshal] for details about the conversion of JSON into a Go value.
  416. func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error) {
  417. dec := export.GetStreamingDecoder(in, opts...)
  418. defer export.PutStreamingDecoder(dec)
  419. xd := export.Decoder(dec)
  420. err = unmarshalFull(dec, out, &xd.Struct)
  421. if err != nil && xd.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  422. return internal.TransformUnmarshalError(out, err)
  423. }
  424. return err
  425. }
  426. func unmarshalFull(in *jsontext.Decoder, out any, uo *jsonopts.Struct) error {
  427. switch err := unmarshalDecode(in, out, uo); err {
  428. case nil:
  429. return export.Decoder(in).CheckEOF()
  430. case io.EOF:
  431. return io.ErrUnexpectedEOF
  432. default:
  433. return err
  434. }
  435. }
  436. // UnmarshalDecode deserializes a Go value from a [jsontext.Decoder] according to
  437. // the provided unmarshal options (while ignoring marshal, encode, or decode options).
  438. // Unlike [Unmarshal] and [UnmarshalRead], decode options are ignored because
  439. // they must have already been specified on the provided [jsontext.Decoder].
  440. // The input may be a stream of one or more JSON values,
  441. // where this only unmarshals the next JSON value in the stream.
  442. // The output must be a non-nil pointer.
  443. // See [Unmarshal] for details about the conversion of JSON into a Go value.
  444. func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) (err error) {
  445. xd := export.Decoder(in)
  446. uo := mayReuseOpt(&xd.Struct, opts)
  447. if uo == nil {
  448. uo = getStructOptions()
  449. defer putStructOptions(uo)
  450. uo.Join(opts...)
  451. uo.CopyCoderOptions(&xd.Struct)
  452. }
  453. err = unmarshalDecode(in, out, uo)
  454. if err != nil && uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  455. return internal.TransformUnmarshalError(out, err)
  456. }
  457. return err
  458. }
  459. func unmarshalDecode(in *jsontext.Decoder, out any, uo *jsonopts.Struct) (err error) {
  460. v := reflect.ValueOf(out)
  461. if v.Kind() != reflect.Pointer || v.IsNil() {
  462. return &SemanticError{action: "unmarshal", GoType: reflect.TypeOf(out), Err: internal.ErrNonNilReference}
  463. }
  464. va := addressableValue{v.Elem(), false} // dereferenced pointer is always addressable
  465. t := va.Type()
  466. // In legacy semantics, the entirety of the next JSON value
  467. // was validated before attempting to unmarshal it.
  468. if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  469. if err := export.Decoder(in).CheckNextValue(); err != nil {
  470. return err
  471. }
  472. }
  473. // Lookup and call the unmarshal function for this type.
  474. unmarshal := lookupArshaler(t).unmarshal
  475. if uo.Unmarshalers != nil {
  476. unmarshal, _ = uo.Unmarshalers.(*Unmarshalers).lookup(unmarshal, t)
  477. }
  478. if err := unmarshal(in, va, uo); err != nil {
  479. if !uo.Flags.Get(jsonflags.AllowDuplicateNames) {
  480. export.Decoder(in).Tokens.InvalidateDisabledNamespaces()
  481. }
  482. return err
  483. }
  484. return nil
  485. }
  486. // addressableValue is a reflect.Value that is guaranteed to be addressable
  487. // such that calling the Addr and Set methods do not panic.
  488. //
  489. // There is no compile magic that enforces this property,
  490. // but rather the need to construct this type makes it easier to examine each
  491. // construction site to ensure that this property is upheld.
  492. type addressableValue struct {
  493. reflect.Value
  494. // forcedAddr reports whether this value is addressable
  495. // only through the use of [newAddressableValue].
  496. // This is only used for [jsonflags.CallMethodsWithLegacySemantics].
  497. forcedAddr bool
  498. }
  499. // newAddressableValue constructs a new addressable value of type t.
  500. func newAddressableValue(t reflect.Type) addressableValue {
  501. return addressableValue{reflect.New(t).Elem(), true}
  502. }
  503. // All marshal and unmarshal behavior is implemented using these signatures.
  504. // The *jsonopts.Struct argument is guaranteed to identical to or at least
  505. // a strict super-set of the options in Encoder.Struct or Decoder.Struct.
  506. // It is identical for Marshal, Unmarshal, MarshalWrite, and UnmarshalRead.
  507. // It is a super-set for MarshalEncode and UnmarshalDecode.
  508. type (
  509. marshaler = func(*jsontext.Encoder, addressableValue, *jsonopts.Struct) error
  510. unmarshaler = func(*jsontext.Decoder, addressableValue, *jsonopts.Struct) error
  511. )
  512. type arshaler struct {
  513. marshal marshaler
  514. unmarshal unmarshaler
  515. nonDefault bool
  516. }
  517. var lookupArshalerCache sync.Map // map[reflect.Type]*arshaler
  518. func lookupArshaler(t reflect.Type) *arshaler {
  519. if v, ok := lookupArshalerCache.Load(t); ok {
  520. return v.(*arshaler)
  521. }
  522. fncs := makeDefaultArshaler(t)
  523. fncs = makeMethodArshaler(fncs, t)
  524. fncs = makeTimeArshaler(fncs, t)
  525. // Use the last stored so that duplicate arshalers can be garbage collected.
  526. v, _ := lookupArshalerCache.LoadOrStore(t, fncs)
  527. return v.(*arshaler)
  528. }
  529. var stringsPools = &sync.Pool{New: func() any { return new(stringSlice) }}
  530. type stringSlice []string
  531. // getStrings returns a non-nil pointer to a slice with length n.
  532. func getStrings(n int) *stringSlice {
  533. s := stringsPools.Get().(*stringSlice)
  534. if cap(*s) < n {
  535. *s = make([]string, n)
  536. }
  537. *s = (*s)[:n]
  538. return s
  539. }
  540. func putStrings(s *stringSlice) {
  541. if cap(*s) > 1<<10 {
  542. *s = nil // avoid pinning arbitrarily large amounts of memory
  543. }
  544. stringsPools.Put(s)
  545. }
  546. func (ss *stringSlice) Sort() {
  547. slices.SortFunc(*ss, func(x, y string) int { return strings.Compare(x, y) })
  548. }