import "github.com/json-iterator/go"
Package jsoniter implements encoding and decoding of JSON as defined in RFC 4627 and provides interfaces with identical syntax of standard lib encoding/json. Converting from encoding/json to jsoniter is no more than replacing the package with jsoniter and variable type declarations (if any). jsoniter interfaces gives 100% compatibility with code using standard lib.
"JSON and Go" (https://golang.org/doc/articles/json_and_go.html) gives a description of how Marshal/Unmarshal operate between arbitrary or predefined json objects and bytes, and it applies to jsoniter.Marshal/Unmarshal as well.
Besides, jsoniter.Iterator provides a different set of interfaces iterating given bytes/string/reader and yielding parsed elements one by one. This set of interfaces reads input as required and gives better performance.
feature_adapter.go feature_any.go feature_any_array.go feature_any_bool.go feature_any_float.go feature_any_int32.go feature_any_int64.go feature_any_invalid.go feature_any_nil.go feature_any_number.go feature_any_object.go feature_any_string.go feature_any_uint32.go feature_any_uint64.go feature_config.go feature_iter.go feature_iter_array.go feature_iter_float.go feature_iter_int.go feature_iter_object.go feature_iter_skip.go feature_iter_skip_strict.go feature_iter_string.go feature_json_number.go feature_pool.go feature_reflect.go feature_reflect_array.go feature_reflect_extension.go feature_reflect_map.go feature_reflect_native.go feature_reflect_object.go feature_reflect_slice.go feature_reflect_struct_decoder.go feature_stream.go feature_stream_float.go feature_stream_int.go feature_stream_string.go jsoniter.go
var ConfigCompatibleWithStandardLibrary = Config{ EscapeHTML: true, SortMapKeys: true, ValidateJsonRawMessage: true, }.Froze()
ConfigCompatibleWithStandardLibrary tries to be 100% compatible with standard library behavior
ConfigDefault the default API
ConfigFastest marshals float with only 6 digits precision
Marshal adapts to json/encoding Marshal API
Marshal returns the JSON encoding of v, adapts to json/encoding Marshal API Refer to https://godoc.org/encoding/json#Marshal for more information
Code:
type ColorGroup struct {
ID int
Name string
Colors []string
}
group := ColorGroup{
ID: 1,
Name: "Reds",
Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
}
b, err := Marshal(group)
if err != nil {
fmt.Println("error:", err)
}
os.Stdout.Write(b)
Output:
{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}
MarshalIndent same as json.MarshalIndent. Prefix is not supported.
MarshalToString convenient method to write as string instead of []byte
RegisterExtension register extension
func RegisterFieldDecoder(typ string, field string, decoder ValDecoder)
RegisterFieldDecoder register TypeDecoder for a struct field
func RegisterFieldDecoderFunc(typ string, field string, fun DecoderFunc)
RegisterFieldDecoderFunc register TypeDecoder for a struct field with function
func RegisterFieldEncoder(typ string, field string, encoder ValEncoder)
RegisterFieldEncoder register TypeEncoder for a struct field
func RegisterFieldEncoderFunc(typ string, field string, fun EncoderFunc, isEmptyFunc func(unsafe.Pointer) bool)
RegisterFieldEncoderFunc register TypeEncoder for a struct field with encode/isEmpty function
func RegisterTypeDecoder(typ string, decoder ValDecoder)
RegisterTypeDecoder register TypeDecoder for a typ
func RegisterTypeDecoderFunc(typ string, fun DecoderFunc)
RegisterTypeDecoderFunc register TypeDecoder for a type with function
func RegisterTypeEncoder(typ string, encoder ValEncoder)
RegisterTypeEncoder register TypeEncoder for a type
RegisterTypeEncoderFunc register TypeEncoder for a type with encode/isEmpty function
Unmarshal adapts to json/encoding Unmarshal API
Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v. Refer to https://godoc.org/encoding/json#Unmarshal for more information
Code:
var jsonBlob = []byte(`[
{"Name": "Platypus", "Order": "Monotremata"},
{"Name": "Quoll", "Order": "Dasyuromorphia"}
]`)
type Animal struct {
Name string
Order string
}
var animals []Animal
err := Unmarshal(jsonBlob, &animals)
if err != nil {
fmt.Println("error:", err)
}
fmt.Printf("%+v", animals)
Output:
[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
UnmarshalFromString convenient method to read from string instead of []byte
Valid reports whether data is a valid JSON encoding.
func WriteToStream(val interface{}, stream *Stream, encoder ValEncoder)WriteToStream the default implementation for TypeEncoder method EncodeInterface
type API interface {
IteratorPool
StreamPool
MarshalToString(v interface{}) (string, error)
Marshal(v interface{}) ([]byte, error)
MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
UnmarshalFromString(str string, v interface{}) error
Unmarshal(data []byte, v interface{}) error
Get(data []byte, path ...interface{}) Any
NewEncoder(writer io.Writer) *Encoder
NewDecoder(reader io.Reader) *Decoder
Valid(data []byte) bool
}API the public interface of this package. Primary Marshal and Unmarshal.
type Any interface {
LastError() error
ValueType() ValueType
MustBeValid() Any
ToBool() bool
ToInt() int
ToInt32() int32
ToInt64() int64
ToUint() uint
ToUint32() uint32
ToUint64() uint64
ToFloat32() float32
ToFloat64() float64
ToString() string
ToVal(val interface{})
Get(path ...interface{}) Any
// TODO: add Set
Size() int
Keys() []string
GetInterface() interface{}
WriteTo(stream *Stream)
}Any generic object representation. The lazy json implementation holds []byte and parse lazily.
Get quick method to get value from deeply nested JSON structure
Code:
val := []byte(`{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}`)
fmt.Printf(Get(val, "Colors", 0).ToString())
Output:
Crimson
Wrap turn a go object into Any interface
WrapFloat64 turn float64 into Any interface
WrapInt32 turn int32 into Any interface
WrapInt64 turn int64 into Any interface
WrapString turn string into Any interface
WrapUint32 turn uint32 into Any interface
WrapUint64 turn uint64 into Any interface
type Binding struct {
Field *reflect.StructField
FromNames []string
ToNames []string
Encoder ValEncoder
Decoder ValDecoder
// contains filtered or unexported fields
}Binding describe how should we encode/decode the struct field
type Config struct {
IndentionStep int
MarshalFloatWith6Digits bool
EscapeHTML bool
SortMapKeys bool
UseNumber bool
TagKey string
ValidateJsonRawMessage bool
}Config customize how the API should behave. The API is created from Config by Froze.
Froze forge API from config
type Decoder struct {
// contains filtered or unexported fields
}Decoder reads and decodes JSON values from an input stream. Decoder provides identical APIs with json/stream Decoder (Token() and UseNumber() are in progress)
NewDecoder adapts to json/stream NewDecoder API.
NewDecoder returns a new decoder that reads from r.
Instead of a json/encoding Decoder, an Decoder is returned Refer to https://godoc.org/encoding/json#NewDecoder for more information
Buffered remaining buffer
Decode decode JSON into interface{}
More is there more?
UseNumber for number JSON element, use float64 or json.NumberValue (alias of string)
DecoderFunc the function form of TypeDecoder
type DummyExtension struct {
}DummyExtension embed this type get dummy implementation for all methods of Extension
func (extension *DummyExtension) CreateDecoder(typ reflect.Type) ValDecoder
CreateDecoder No-op
func (extension *DummyExtension) CreateEncoder(typ reflect.Type) ValEncoder
CreateEncoder No-op
func (extension *DummyExtension) DecorateDecoder(typ reflect.Type, decoder ValDecoder) ValDecoder
DecorateDecoder No-op
func (extension *DummyExtension) DecorateEncoder(typ reflect.Type, encoder ValEncoder) ValEncoder
DecorateEncoder No-op
func (extension *DummyExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)
UpdateStructDescriptor No-op
type Encoder struct {
// contains filtered or unexported fields
}Encoder same as json.Encoder
NewEncoder same as json.NewEncoder
Encode encode interface{} as JSON to io.Writer
SetEscapeHTML escape html by default, set to false to disable
SetIndent set the indention. Prefix is not supported
EncoderFunc the function form of TypeEncoder
type Extension interface {
UpdateStructDescriptor(structDescriptor *StructDescriptor)
CreateDecoder(typ reflect.Type) ValDecoder
CreateEncoder(typ reflect.Type) ValEncoder
DecorateDecoder(typ reflect.Type, decoder ValDecoder) ValDecoder
DecorateEncoder(typ reflect.Type, encoder ValEncoder) ValEncoder
}Extension the one for all SPI. Customize encoding/decoding by specifying alternate encoder/decoder. Can also rename fields by UpdateStructDescriptor.
Iterator is a io.Reader like object, with JSON specific read functions. Error is not returned as return value, but stored as Error member on this iterator instance.
NewIterator creates an empty Iterator instance
Parse creates an Iterator instance from io.Reader
ParseBytes creates an Iterator instance from byte array
ParseString creates an Iterator instance from string
CurrentBuffer gets current buffer as string for debugging purpose
func (iter *Iterator) Pool() IteratorPool
Pool returns a pool can provide more iterator with same configuration
Read read the next JSON element as generic interface{}.
ReadAny read next JSON element as an Any object. It is a better json.RawMessage.
ReadArray read array element, tells if the array has more element to read.
ReadArrayCB read array with callback
ReadBigFloat read big.Float
ReadBigInt read big.Int
ReadBool reads a json object as BoolValue
ReadFloat32 read float32
ReadFloat64 read float64
ReadInt read int
ReadInt16 read int16
ReadInt32 read int32
ReadInt64 read int64
ReadInt8 read int8
ReadMapCB read map with callback, the key can be any string
ReadNil reads a json object as nil and returns whether it's a nil or not
ReadObject read one field from object. If object ended, returns empty string. Otherwise, returns the field name.
ReadObjectCB read object with callback, the key is ascii only and field name not copied
ReadString read string from iterator
ReadStringAsSlice read string from iterator without copying into string form. The []byte can not be kept, as it will change after next iterator call.
ReadUint read uint
ReadUint16 read uint16
ReadUint32 read uint32
ReadUint64 read uint64
ReadUint8 read uint8
ReadVal copy the underlying JSON into go interface, same as json.Unmarshal
ReportError record a error in iterator instance with current position.
Reset reuse iterator instance by specifying another reader
ResetBytes reuse iterator instance by specifying another byte array as input
Skip skips a json object and positions to relatively the next json object
SkipAndReturnBytes skip next JSON element, and return its content as []byte. The []byte can be kept, it is a copy of data.
WhatIsNext gets ValueType of relatively next json element
type IteratorPool interface {
BorrowIterator(data []byte) *Iterator
ReturnIterator(iter *Iterator)
}IteratorPool a thread safe pool of iterators with same configuration
Float64 returns the number as a float64.
Int64 returns the number as an int64.
String returns the literal text of the number.
RawMessage to make replace json with jsoniter
Stream is a io.Writer like object, with JSON specific write functions. Error is not returned as return value, but stored as Error member on this stream instance.
NewStream create new stream instance. cfg can be jsoniter.ConfigDefault. out can be nil if write to internal buffer. bufSize is the initial size for the internal buffer in bytes.
Available returns how many bytes are unused in the buffer.
Buffer if writer is nil, use this method to take the result
Buffered returns the number of bytes that have been written into the current buffer.
Flush writes any buffered data to the underlying io.Writer.
func (stream *Stream) Pool() StreamPool
Pool returns a pool can provide more stream with same configuration
Reset reuse this stream instance by assign a new writer
Write writes the contents of p into the buffer. It returns the number of bytes written. If nn < len(p), it also returns an error explaining why the write is short.
WriteArrayEnd write ] with possible indention
WriteArrayStart write [ with possible indention
WriteBool write true or false into stream
WriteEmptyArray write []
WriteEmptyObject write {}
WriteFalse write false to stream
WriteFloat32 write float32 to stream
WriteFloat32Lossy write float32 to stream with ONLY 6 digits precision although much much faster
WriteFloat64 write float64 to stream
WriteFloat64Lossy write float64 to stream with ONLY 6 digits precision although much much faster
WriteInt write int to stream
WriteInt16 write int16 to stream
WriteInt32 write int32 to stream
WriteInt64 write int64 to stream
WriteInt8 write int8 to stream
WriteMore write , with possible indention
WriteNil write null to stream
WriteObjectEnd write } with possible indention
WriteObjectField write "field": with possible indention
WriteObjectStart write { with possible indention
WriteRaw write string out without quotes, just like []byte
WriteString write string to stream without html escape
WriteStringWithHTMLEscaped write string to stream with html special characters escaped
WriteTrue write true to stream
WriteUint write uint to stream
WriteUint16 write uint16 to stream
WriteUint32 write uint32 to stream
WriteUint64 write uint64 to stream
WriteUint8 write uint8 to stream
WriteVal copy the go interface into underlying JSON, same as json.Marshal
StreamPool a thread safe pool of streams with same configuration
type StructDescriptor struct {
Type reflect.Type
Fields []*Binding
// contains filtered or unexported fields
}StructDescriptor describe how should we encode/decode the struct
func (structDescriptor *StructDescriptor) GetField(fieldName string) *Binding
GetField get one field from the descriptor by its name. Can not use map here to keep field orders.
ValDecoder is an internal type registered to cache as needed. Don't confuse jsoniter.ValDecoder with json.Decoder. For json.Decoder's adapter, refer to jsoniter.AdapterDecoder(todo link).
Reflection on type to create decoders, which is then cached Reflection on value is avoided as we can, as the reflect.Value itself will allocate, with following exceptions 1. create instance of new value, for example *int will need a int to be allocated 2. append to slice, if the existing cap is not enough, allocate will be done using Reflect.New 3. assignment to map, both key and value will be reflect.Value For a simple struct binding, it will be reflect.Value free and allocation free
type ValEncoder interface {
IsEmpty(ptr unsafe.Pointer) bool
Encode(ptr unsafe.Pointer, stream *Stream)
EncodeInterface(val interface{}, stream *Stream)
}ValEncoder is an internal type registered to cache as needed. Don't confuse jsoniter.ValEncoder with json.Encoder. For json.Encoder's adapter, refer to jsoniter.AdapterEncoder(todo godoc link).
ValueType the type for JSON element
const (
// InvalidValue invalid JSON element
InvalidValue ValueType = iota
// StringValue JSON element "string"
StringValue
// NumberValue JSON element 100 or 0.10
NumberValue
// NilValue JSON element null
NilValue
// BoolValue JSON element true or false
BoolValue
// ArrayValue JSON element []
ArrayValue
// ObjectValue JSON element {}
ObjectValue
)| Path | Synopsis |
|---|---|
| extra | |
| output_tests | |
| output_tests/caseless_unmarshal | |
| output_tests/partial_unmarshal |
Package jsoniter imports 19 packages (graph) and is imported by 23 packages. Updated 2017-10-10. Refresh now. Tools for package owners.