1 // Copyright 2010 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.
5 // Represents JSON data structure using native Go types: booleans, floats,
6 // strings, arrays, and maps.
23 // Unmarshal parses the JSON-encoded data and stores the result
24 // in the value pointed to by v.
26 // Unmarshal uses the inverse of the encodings that
27 // Marshal uses, allocating maps, slices, and pointers as necessary,
28 // with the following additional rules:
30 // To unmarshal JSON into a pointer, Unmarshal first handles the case of
31 // the JSON being the JSON literal null. In that case, Unmarshal sets
32 // the pointer to nil. Otherwise, Unmarshal unmarshals the JSON into
33 // the value pointed at by the pointer. If the pointer is nil, Unmarshal
34 // allocates a new value for it to point to.
36 // To unmarshal JSON into a struct, Unmarshal matches incoming object
37 // keys to the keys used by Marshal (either the struct field name or its tag),
38 // preferring an exact match but also accepting a case-insensitive match.
40 // To unmarshal JSON into an interface value, Unmarshal unmarshals
41 // the JSON into the concrete value contained in the interface value.
42 // If the interface value is nil, that is, has no concrete value stored in it,
43 // Unmarshal stores one of these in the interface value:
45 // bool, for JSON booleans
46 // float64, for JSON numbers
47 // string, for JSON strings
48 // []interface{}, for JSON arrays
49 // map[string]interface{}, for JSON objects
52 // If a JSON value is not appropriate for a given target type,
53 // or if a JSON number overflows the target type, Unmarshal
54 // skips that field and completes the unmarshalling as best it can.
55 // If no more serious errors are encountered, Unmarshal returns
56 // an UnmarshalTypeError describing the earliest such error.
58 // When unmarshaling quoted strings, invalid UTF-8 or
59 // invalid UTF-16 surrogate pairs are not treated as an error.
60 // Instead, they are replaced by the Unicode replacement
63 func Unmarshal(data
[]byte, v
interface{}) error
{
64 // Check for well-formedness.
65 // Avoids filling out half a data structure
66 // before discovering a JSON syntax error.
68 err
:= checkValid(data
, &d
.scan
)
77 // Unmarshaler is the interface implemented by objects
78 // that can unmarshal a JSON description of themselves.
79 // The input can be assumed to be a valid encoding of
80 // a JSON value. UnmarshalJSON must copy the JSON data
81 // if it wishes to retain the data after returning.
82 type Unmarshaler
interface {
83 UnmarshalJSON([]byte) error
86 // An UnmarshalTypeError describes a JSON value that was
87 // not appropriate for a value of a specific Go type.
88 type UnmarshalTypeError
struct {
89 Value
string // description of JSON value - "bool", "array", "number -5"
90 Type reflect
.Type
// type of Go value it could not be assigned to
93 func (e
*UnmarshalTypeError
) Error() string {
94 return "json: cannot unmarshal " + e
.Value
+ " into Go value of type " + e
.Type
.String()
97 // An UnmarshalFieldError describes a JSON object key that
98 // led to an unexported (and therefore unwritable) struct field.
99 // (No longer used; kept for compatibility.)
100 type UnmarshalFieldError
struct {
103 Field reflect
.StructField
106 func (e
*UnmarshalFieldError
) Error() string {
107 return "json: cannot unmarshal object key " + strconv
.Quote(e
.Key
) + " into unexported field " + e
.Field
.Name
+ " of type " + e
.Type
.String()
110 // An InvalidUnmarshalError describes an invalid argument passed to Unmarshal.
111 // (The argument to Unmarshal must be a non-nil pointer.)
112 type InvalidUnmarshalError
struct {
116 func (e
*InvalidUnmarshalError
) Error() string {
118 return "json: Unmarshal(nil)"
121 if e
.Type
.Kind() != reflect
.Ptr
{
122 return "json: Unmarshal(non-pointer " + e
.Type
.String() + ")"
124 return "json: Unmarshal(nil " + e
.Type
.String() + ")"
127 func (d
*decodeState
) unmarshal(v
interface{}) (err error
) {
129 if r
:= recover(); r
!= nil {
130 if _
, ok
:= r
.(runtime
.Error
); ok
{
137 rv
:= reflect
.ValueOf(v
)
138 if rv
.Kind() != reflect
.Ptr || rv
.IsNil() {
139 return &InvalidUnmarshalError
{reflect
.TypeOf(v
)}
143 // We decode rv not rv.Elem because the Unmarshaler interface
144 // test must be applied at the top level of the value.
149 // A Number represents a JSON number literal.
152 // String returns the literal text of the number.
153 func (n Number
) String() string { return string(n
) }
155 // Float64 returns the number as a float64.
156 func (n Number
) Float64() (float64, error
) {
157 return strconv
.ParseFloat(string(n
), 64)
160 // Int64 returns the number as an int64.
161 func (n Number
) Int64() (int64, error
) {
162 return strconv
.ParseInt(string(n
), 10, 64)
165 // decodeState represents the state while decoding a JSON value.
166 type decodeState
struct {
168 off
int // read offset in data
170 nextscan scanner
// for calls to nextValue
172 tempstr
string // scratch space to avoid some allocations
176 // errPhase is used for errors that should not happen unless
177 // there is a bug in the JSON decoder or something is editing
178 // the data slice while the decoder executes.
179 var errPhase
= errors
.New("JSON decoder out of sync - data changing underfoot?")
181 func (d
*decodeState
) init(data
[]byte) *decodeState
{
188 // error aborts the decoding by panicking with err.
189 func (d
*decodeState
) error(err error
) {
193 // saveError saves the first err it is called with,
194 // for reporting at the end of the unmarshal.
195 func (d
*decodeState
) saveError(err error
) {
196 if d
.savedError
== nil {
201 // next cuts off and returns the next full JSON value in d.data[d.off:].
202 // The next value is known to be an object or array, not a literal.
203 func (d
*decodeState
) next() []byte {
205 item
, rest
, err
:= nextValue(d
.data
[d
.off
:], &d
.nextscan
)
209 d
.off
= len(d
.data
) - len(rest
)
211 // Our scanner has seen the opening brace/bracket
212 // and thinks we're still in the middle of the object.
213 // invent a closing brace/bracket to get it out.
215 d
.scan
.step(&d
.scan
, '}')
217 d
.scan
.step(&d
.scan
, ']')
223 // scanWhile processes bytes in d.data[d.off:] until it
224 // receives a scan code not equal to op.
225 // It updates d.off and returns the new scan code.
226 func (d
*decodeState
) scanWhile(op
int) int {
229 if d
.off
>= len(d
.data
) {
231 d
.off
= len(d
.data
) + 1 // mark processed EOF with len+1
233 c
:= int(d
.data
[d
.off
])
235 newOp
= d
.scan
.step(&d
.scan
, c
)
244 // value decodes a JSON value from d.data[d.off:] into the value.
245 // it updates d.off to point past the decoded value.
246 func (d
*decodeState
) value(v reflect
.Value
) {
248 _
, rest
, err
:= nextValue(d
.data
[d
.off
:], &d
.nextscan
)
252 d
.off
= len(d
.data
) - len(rest
)
254 // d.scan thinks we're still at the beginning of the item.
255 // Feed in an empty string - the shortest, simplest value -
256 // so that it knows we got to the end of the value.
260 d
.scan
.step
= stateBeginValue
262 d
.scan
.step(&d
.scan
, '"')
263 d
.scan
.step(&d
.scan
, '"')
265 n
:= len(d
.scan
.parseState
)
266 if n
> 0 && d
.scan
.parseState
[n
-1] == parseObjectKey
{
267 // d.scan thinks we just read an object key; finish the object
268 d
.scan
.step(&d
.scan
, ':')
269 d
.scan
.step(&d
.scan
, '"')
270 d
.scan
.step(&d
.scan
, '"')
271 d
.scan
.step(&d
.scan
, '}')
277 switch op
:= d
.scanWhile(scanSkipSpace
); op
{
284 case scanBeginObject
:
287 case scanBeginLiteral
:
292 // indirect walks down v allocating pointers as needed,
293 // until it gets to a non-pointer.
294 // if it encounters an Unmarshaler, indirect stops and returns that.
295 // if decodingNull is true, indirect stops at the last pointer so it can be set to nil.
296 func (d
*decodeState
) indirect(v reflect
.Value
, decodingNull
bool) (Unmarshaler
, reflect
.Value
) {
297 // If v is a named type and is addressable,
298 // start with its address, so that if the type has pointer methods,
300 if v
.Kind() != reflect
.Ptr
&& v
.Type().Name() != "" && v
.CanAddr() {
304 // Load value from interface, but only if the result will be
305 // usefully addressable.
306 if v
.Kind() == reflect
.Interface
&& !v
.IsNil() {
308 if e
.Kind() == reflect
.Ptr
&& !e
.IsNil() && (!decodingNull || e
.Elem().Kind() == reflect
.Ptr
) {
314 if v
.Kind() != reflect
.Ptr
{
318 if v
.Elem().Kind() != reflect
.Ptr
&& decodingNull
&& v
.CanSet() {
322 v
.Set(reflect
.New(v
.Type().Elem()))
324 if v
.Type().NumMethod() > 0 {
325 if unmarshaler
, ok
:= v
.Interface().(Unmarshaler
); ok
{
326 return unmarshaler
, reflect
.Value
{}
334 // array consumes an array from d.data[d.off-1:], decoding into the value v.
335 // the first byte of the array ('[') has been read already.
336 func (d
*decodeState
) array(v reflect
.Value
) {
337 // Check for unmarshaler.
338 unmarshaler
, pv
:= d
.indirect(v
, false)
339 if unmarshaler
!= nil {
341 err
:= unmarshaler
.UnmarshalJSON(d
.next())
349 // Check type of target.
351 case reflect
.Interface
:
352 if v
.NumMethod() == 0 {
353 // Decoding into nil interface? Switch to non-reflect code.
354 v
.Set(reflect
.ValueOf(d
.arrayInterface()))
357 // Otherwise it's invalid.
360 d
.saveError(&UnmarshalTypeError
{"array", v
.Type()})
371 // Look ahead for ] - can only happen on first iteration.
372 op
:= d
.scanWhile(scanSkipSpace
)
373 if op
== scanEndArray
{
377 // Back up so d.value can have the byte we just read.
381 // Get element of array, growing if necessary.
382 if v
.Kind() == reflect
.Slice
{
383 // Grow slice if necessary
385 newcap
:= v
.Cap() + v
.Cap()/2
389 newv
:= reflect
.MakeSlice(v
.Type(), v
.Len(), newcap
)
390 reflect
.Copy(newv
, v
)
399 // Decode into element.
402 // Ran out of fixed array: skip.
403 d
.value(reflect
.Value
{})
407 // Next token must be , or ].
408 op
= d
.scanWhile(scanSkipSpace
)
409 if op
== scanEndArray
{
412 if op
!= scanArrayValue
{
418 if v
.Kind() == reflect
.Array
{
419 // Array. Zero the rest.
420 z
:= reflect
.Zero(v
.Type().Elem())
421 for ; i
< v
.Len(); i
++ {
428 if i
== 0 && v
.Kind() == reflect
.Slice
{
429 v
.Set(reflect
.MakeSlice(v
.Type(), 0, 0))
433 // object consumes an object from d.data[d.off-1:], decoding into the value v.
434 // the first byte of the object ('{') has been read already.
435 func (d
*decodeState
) object(v reflect
.Value
) {
436 // Check for unmarshaler.
437 unmarshaler
, pv
:= d
.indirect(v
, false)
438 if unmarshaler
!= nil {
440 err
:= unmarshaler
.UnmarshalJSON(d
.next())
448 // Decoding into nil interface? Switch to non-reflect code.
449 if v
.Kind() == reflect
.Interface
&& v
.NumMethod() == 0 {
450 v
.Set(reflect
.ValueOf(d
.objectInterface()))
454 // Check type of target: struct or map[string]T
457 // map must have string kind
459 if t
.Key().Kind() != reflect
.String
{
460 d
.saveError(&UnmarshalTypeError
{"object", v
.Type()})
464 v
.Set(reflect
.MakeMap(t
))
469 d
.saveError(&UnmarshalTypeError
{"object", v
.Type()})
471 d
.next() // skip over { } in input
475 var mapElem reflect
.Value
478 // Read opening " of string key or closing }.
479 op
:= d
.scanWhile(scanSkipSpace
)
480 if op
== scanEndObject
{
481 // closing } - can only happen on first iteration.
484 if op
!= scanBeginLiteral
{
490 op
= d
.scanWhile(scanContinue
)
491 item
:= d
.data
[start
: d
.off
-1]
492 key
, ok
:= unquote(item
)
497 // Figure out field corresponding to key.
498 var subv reflect
.Value
499 destring
:= false // whether the value is wrapped in a string to be decoded first
501 if v
.Kind() == reflect
.Map
{
502 elemType
:= v
.Type().Elem()
503 if !mapElem
.IsValid() {
504 mapElem
= reflect
.New(elemType
).Elem()
506 mapElem
.Set(reflect
.Zero(elemType
))
511 fields
:= cachedTypeFields(v
.Type())
512 for i
:= range fields
{
518 if f
== nil && strings
.EqualFold(ff
.name
, key
) {
525 for _
, i
:= range f
.index
{
526 if subv
.Kind() == reflect
.Ptr
{
528 subv
.Set(reflect
.New(subv
.Type().Elem()))
537 // Read : before value.
538 if op
== scanSkipSpace
{
539 op
= d
.scanWhile(scanSkipSpace
)
541 if op
!= scanObjectKey
{
547 d
.value(reflect
.ValueOf(&d
.tempstr
))
548 d
.literalStore([]byte(d
.tempstr
), subv
, true)
553 // Write value back to map;
554 // if using struct, subv points into struct already.
555 if v
.Kind() == reflect
.Map
{
556 kv
:= reflect
.ValueOf(key
).Convert(v
.Type().Key())
557 v
.SetMapIndex(kv
, subv
)
560 // Next token must be , or }.
561 op
= d
.scanWhile(scanSkipSpace
)
562 if op
== scanEndObject
{
565 if op
!= scanObjectValue
{
571 // literal consumes a literal from d.data[d.off-1:], decoding into the value v.
572 // The first byte of the literal has been read already
573 // (that's how the caller knows it's a literal).
574 func (d
*decodeState
) literal(v reflect
.Value
) {
575 // All bytes inside literal return scanContinue op code.
577 op
:= d
.scanWhile(scanContinue
)
579 // Scan read one byte too far; back up.
583 d
.literalStore(d
.data
[start
:d
.off
], v
, false)
586 // convertNumber converts the number literal s to a float64 or a Number
587 // depending on the setting of d.useNumber.
588 func (d
*decodeState
) convertNumber(s
string) (interface{}, error
) {
590 return Number(s
), nil
592 f
, err
:= strconv
.ParseFloat(s
, 64)
594 return nil, &UnmarshalTypeError
{"number " + s
, reflect
.TypeOf(0.0)}
599 var numberType
= reflect
.TypeOf(Number(""))
601 // literalStore decodes a literal stored in item into v.
603 // fromQuoted indicates whether this literal came from unwrapping a
604 // string from the ",string" struct tag option. this is used only to
605 // produce more helpful error messages.
606 func (d
*decodeState
) literalStore(item
[]byte, v reflect
.Value
, fromQuoted
bool) {
607 // Check for unmarshaler.
610 d
.saveError(fmt
.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item
, v
.Type()))
613 wantptr
:= item
[0] == 'n' // null
614 unmarshaler
, pv
:= d
.indirect(v
, wantptr
)
615 if unmarshaler
!= nil {
616 err
:= unmarshaler
.UnmarshalJSON(item
)
624 switch c
:= item
[0]; c
{
627 case reflect
.Interface
, reflect
.Ptr
, reflect
.Map
, reflect
.Slice
:
628 v
.Set(reflect
.Zero(v
.Type()))
629 // otherwise, ignore null for primitives/string
631 case 't', 'f': // true, false
636 d
.saveError(fmt
.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item
, v
.Type()))
638 d
.saveError(&UnmarshalTypeError
{"bool", v
.Type()})
642 case reflect
.Interface
:
643 if v
.NumMethod() == 0 {
644 v
.Set(reflect
.ValueOf(value
))
646 d
.saveError(&UnmarshalTypeError
{"bool", v
.Type()})
651 s
, ok
:= unquoteBytes(item
)
654 d
.error(fmt
.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item
, v
.Type()))
661 d
.saveError(&UnmarshalTypeError
{"string", v
.Type()})
663 if v
.Type() != byteSliceType
{
664 d
.saveError(&UnmarshalTypeError
{"string", v
.Type()})
667 b
:= make([]byte, base64
.StdEncoding
.DecodedLen(len(s
)))
668 n
, err
:= base64
.StdEncoding
.Decode(b
, s
)
673 v
.Set(reflect
.ValueOf(b
[0:n
]))
675 v
.SetString(string(s
))
676 case reflect
.Interface
:
677 if v
.NumMethod() == 0 {
678 v
.Set(reflect
.ValueOf(string(s
)))
680 d
.saveError(&UnmarshalTypeError
{"string", v
.Type()})
685 if c
!= '-' && (c
< '0' || c
> '9') {
687 d
.error(fmt
.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item
, v
.Type()))
695 if v
.Kind() == reflect
.String
&& v
.Type() == numberType
{
700 d
.error(fmt
.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item
, v
.Type()))
702 d
.error(&UnmarshalTypeError
{"number", v
.Type()})
704 case reflect
.Interface
:
705 n
, err
:= d
.convertNumber(s
)
710 if v
.NumMethod() != 0 {
711 d
.saveError(&UnmarshalTypeError
{"number", v
.Type()})
714 v
.Set(reflect
.ValueOf(n
))
716 case reflect
.Int
, reflect
.Int8
, reflect
.Int16
, reflect
.Int32
, reflect
.Int64
:
717 n
, err
:= strconv
.ParseInt(s
, 10, 64)
718 if err
!= nil || v
.OverflowInt(n
) {
719 d
.saveError(&UnmarshalTypeError
{"number " + s
, v
.Type()})
724 case reflect
.Uint
, reflect
.Uint8
, reflect
.Uint16
, reflect
.Uint32
, reflect
.Uint64
, reflect
.Uintptr
:
725 n
, err
:= strconv
.ParseUint(s
, 10, 64)
726 if err
!= nil || v
.OverflowUint(n
) {
727 d
.saveError(&UnmarshalTypeError
{"number " + s
, v
.Type()})
732 case reflect
.Float32
, reflect
.Float64
:
733 n
, err
:= strconv
.ParseFloat(s
, v
.Type().Bits())
734 if err
!= nil || v
.OverflowFloat(n
) {
735 d
.saveError(&UnmarshalTypeError
{"number " + s
, v
.Type()})
743 // The xxxInterface routines build up a value to be stored
744 // in an empty interface. They are not strictly necessary,
745 // but they avoid the weight of reflection in this common case.
747 // valueInterface is like value but returns interface{}
748 func (d
*decodeState
) valueInterface() interface{} {
749 switch d
.scanWhile(scanSkipSpace
) {
754 return d
.arrayInterface()
755 case scanBeginObject
:
756 return d
.objectInterface()
757 case scanBeginLiteral
:
758 return d
.literalInterface()
762 // arrayInterface is like array but returns []interface{}.
763 func (d
*decodeState
) arrayInterface() []interface{} {
764 var v
= make([]interface{}, 0)
766 // Look ahead for ] - can only happen on first iteration.
767 op
:= d
.scanWhile(scanSkipSpace
)
768 if op
== scanEndArray
{
772 // Back up so d.value can have the byte we just read.
776 v
= append(v
, d
.valueInterface())
778 // Next token must be , or ].
779 op
= d
.scanWhile(scanSkipSpace
)
780 if op
== scanEndArray
{
783 if op
!= scanArrayValue
{
790 // objectInterface is like object but returns map[string]interface{}.
791 func (d
*decodeState
) objectInterface() map[string]interface{} {
792 m
:= make(map[string]interface{})
794 // Read opening " of string key or closing }.
795 op
:= d
.scanWhile(scanSkipSpace
)
796 if op
== scanEndObject
{
797 // closing } - can only happen on first iteration.
800 if op
!= scanBeginLiteral
{
806 op
= d
.scanWhile(scanContinue
)
807 item
:= d
.data
[start
: d
.off
-1]
808 key
, ok
:= unquote(item
)
813 // Read : before value.
814 if op
== scanSkipSpace
{
815 op
= d
.scanWhile(scanSkipSpace
)
817 if op
!= scanObjectKey
{
822 m
[key
] = d
.valueInterface()
824 // Next token must be , or }.
825 op
= d
.scanWhile(scanSkipSpace
)
826 if op
== scanEndObject
{
829 if op
!= scanObjectValue
{
836 // literalInterface is like literal but returns an interface value.
837 func (d
*decodeState
) literalInterface() interface{} {
838 // All bytes inside literal return scanContinue op code.
840 op
:= d
.scanWhile(scanContinue
)
842 // Scan read one byte too far; back up.
845 item
:= d
.data
[start
:d
.off
]
847 switch c
:= item
[0]; c
{
851 case 't', 'f': // true, false
855 s
, ok
:= unquote(item
)
862 if c
!= '-' && (c
< '0' || c
> '9') {
865 n
, err
:= d
.convertNumber(string(item
))
873 // getu4 decodes \uXXXX from the beginning of s, returning the hex value,
875 func getu4(s
[]byte) rune
{
876 if len(s
) < 6 || s
[0] != '\\' || s
[1] != 'u' {
879 r
, err
:= strconv
.ParseUint(string(s
[2:6]), 16, 64)
886 // unquote converts a quoted JSON string literal s into an actual string t.
887 // The rules are different than for Go, so cannot use strconv.Unquote.
888 func unquote(s
[]byte) (t
string, ok
bool) {
889 s
, ok
= unquoteBytes(s
)
894 func unquoteBytes(s
[]byte) (t
[]byte, ok
bool) {
895 if len(s
) < 2 || s
[0] != '"' || s
[len(s
)-1] != '"' {
900 // Check for unusual characters. If there are none,
901 // then no unquoting is needed, so return a slice of the
906 if c
== '\\' || c
== '"' || c
< ' ' {
909 if c
< utf8
.RuneSelf
{
913 rr
, size
:= utf8
.DecodeRune(s
[r
:])
914 if rr
== utf8
.RuneError
&& size
== 1 {
923 b
:= make([]byte, len(s
)+2*utf8
.UTFMax
)
926 // Out of room? Can only happen if s is full of
927 // malformed UTF-8 and we're replacing each
928 // byte with RuneError.
929 if w
>= len(b
)-2*utf8
.UTFMax
{
930 nb
:= make([]byte, (len(b
)+utf8
.UTFMax
)*2)
943 case '"', '\\', '/', '\'':
974 if utf16
.IsSurrogate(rr
) {
976 if dec
:= utf16
.DecodeRune(rr
, rr1
); dec
!= unicode
.ReplacementChar
{
977 // A valid pair; consume.
979 w
+= utf8
.EncodeRune(b
[w
:], dec
)
982 // Invalid surrogate; fall back to replacement rune.
983 rr
= unicode
.ReplacementChar
985 w
+= utf8
.EncodeRune(b
[w
:], rr
)
988 // Quote, control characters are invalid.
989 case c
== '"', c
< ' ':
993 case c
< utf8
.RuneSelf
:
998 // Coerce to well-formed UTF-8.
1000 rr
, size
:= utf8
.DecodeRune(s
[r
:])
1002 w
+= utf8
.EncodeRune(b
[w
:], rr
)