jsoniter package - github.com/json-iterator/go - Go Packages (original) (raw)

Package jsoniter implements encoding and decoding of JSON as defined inRFC 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.

This section is empty.

View Source

var ConfigCompatibleWithStandardLibrary = Config{ EscapeHTML: true, SortMapKeys: true, ValidateJsonRawMessage: true, }.Froze()

ConfigCompatibleWithStandardLibrary tries to be 100% compatible with standard library behavior

ConfigDefault the default API

View Source

var ConfigFastest = Config{ EscapeHTML: false, MarshalFloatWith6Digits: true, ObjectFieldMustBeSimpleString: true, }.Froze()

ConfigFastest marshals float with only 6 digits precision

func CastJsonNumber(val interface{}) (string, bool)

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

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

func RegisterExtension(extension Extension)

RegisterExtension register extension

RegisterFieldDecoder register TypeDecoder for a struct field

RegisterFieldDecoderFunc register TypeDecoder for a struct field with function

RegisterFieldEncoder register TypeEncoder for a struct field

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

func Unmarshal(data []byte, v interface{}) error

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

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}]

func UnmarshalFromString(str string, v interface{}) error

UnmarshalFromString is a convenient method to read from string instead of []byte

Valid reports whether data is a valid JSON encoding.

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 Size() int Keys() []string GetInterface() interface{} WriteTo(stream *Stream) }

Any generic object representation. The lazy json implementation holds []byte and parse lazily.

func Get(data []byte, path ...interface{}) Any

Get quick method to get value from deeply nested JSON structure

val := []byte({"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}) fmt.Printf(Get(val, "Colors", 0).ToString())

Output:

Crimson

func Wrap(val interface{}) Any

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

Binding describe how should we encode/decode the struct field

type Config struct { IndentionStep int MarshalFloatWith6Digits bool EscapeHTML bool SortMapKeys bool UseNumber bool DisallowUnknownFields bool TagKey string OnlyTaggedField bool ValidateJsonRawMessage bool ObjectFieldMustBeSimpleString bool CaseSensitive bool }

Config customize how the API should behave. The API is created from Config by Froze.

func (cfg Config) Froze() API

Froze forge API from config

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

func (adapter *Decoder) Decode(obj interface{}) error

Decode decode JSON into interface{}

func (adapter *Decoder) DisallowUnknownFields()

DisallowUnknownFields causes the Decoder to return an error when the destination is a struct and the input contains object keys which do not match any non-ignored, exported fields in the destination.

func (adapter *Decoder) More() bool

More is there more?

func (adapter *Decoder) UseNumber()

UseNumber causes the Decoder to unmarshal a number into an interface{} as a Number instead of as a float64.

CreateDecoder get decoder from map

CreateMapKeyDecoder No-op

CreateMapKeyEncoder No-op

func (extension DecoderExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)

UpdateStructDescriptor No-op

DecoderFunc the function form of TypeDecoder

type DummyExtension struct { }

DummyExtension embed this type get dummy implementation for all methods of Extension

CreateMapKeyDecoder No-op

CreateMapKeyEncoder No-op

func (extension *DummyExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)

UpdateStructDescriptor No-op

Encoder same as json.Encoder

NewEncoder same as json.NewEncoder

func (adapter *Encoder) Encode(val interface{}) error

Encode encode interface{} as JSON to io.Writer

func (adapter *Encoder) SetEscapeHTML(escapeHTML bool)

SetEscapeHTML escape html by default, set to false to disable

func (adapter *Encoder) SetIndent(prefix, indent string)

SetIndent set the indention. Prefix is not supported

CreateEncoder get encoder from map

CreateMapKeyDecoder No-op

CreateMapKeyEncoder No-op

func (extension EncoderExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)

UpdateStructDescriptor No-op

EncoderFunc the function form of TypeEncoder

Extension the one for all SPI. Customize encoding/decoding by specifying alternate encoder/decoder. Can also rename fields by UpdateStructDescriptor.

type Iterator struct { Error error Attachment interface{}

}

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.

func NewIterator(cfg API) *Iterator

NewIterator creates an empty Iterator instance

Parse creates an Iterator instance from io.Reader

func ParseBytes(cfg API, input []byte) *Iterator

ParseBytes creates an Iterator instance from byte array

func ParseString(cfg API, input string) *Iterator

ParseString creates an Iterator instance from string

func (iter *Iterator) CurrentBuffer() 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

func (iter *Iterator) Read() interface{}

Read read the next JSON element as generic interface{}.

func (iter *Iterator) ReadAny() Any

ReadAny read next JSON element as an Any object. It is a better json.RawMessage.

func (iter *Iterator) ReadArray() (ret bool)

ReadArray read array element, tells if the array has more element to read.

func (iter Iterator) ReadArrayCB(callback func(Iterator) bool) (ret bool)

ReadArrayCB read array with callback

func (iter *Iterator) ReadBigFloat() (ret *big.Float)

ReadBigFloat read big.Float

func (iter *Iterator) ReadBigInt() (ret *big.Int)

ReadBigInt read big.Int

func (iter *Iterator) ReadBool() (ret bool)

ReadBool reads a json object as BoolValue

func (iter *Iterator) ReadFloat32() (ret float32)

ReadFloat32 read float32

func (iter *Iterator) ReadFloat64() (ret float64)

ReadFloat64 read float64

func (iter *Iterator) ReadInt() int

ReadInt read int

func (iter *Iterator) ReadInt16() (ret int16)

ReadInt16 read int16

func (iter *Iterator) ReadInt32() (ret int32)

ReadInt32 read int32

func (iter *Iterator) ReadInt64() (ret int64)

ReadInt64 read int64

func (iter *Iterator) ReadInt8() (ret int8)

ReadInt8 read int8

ReadMapCB read map with callback, the key can be any string

func (iter *Iterator) ReadNil() (ret bool)

ReadNil reads a json object as nil and returns whether it's a nil or not

ReadNumber read json.Number

func (iter *Iterator) ReadObject() (ret string)

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

func (iter *Iterator) ReadString() (ret string)

ReadString read string from iterator

func (iter *Iterator) ReadStringAsSlice() (ret []byte)

ReadStringAsSlice read string from iterator without copying into string form. The []byte can not be kept, as it will change after next iterator call.

func (iter *Iterator) ReadUint() uint

ReadUint read uint

func (iter *Iterator) ReadUint16() (ret uint16)

ReadUint16 read uint16

func (iter *Iterator) ReadUint32() (ret uint32)

ReadUint32 read uint32

func (iter *Iterator) ReadUint8() (ret uint8)

ReadUint8 read uint8

func (iter *Iterator) ReadVal(obj interface{})

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

func (iter *Iterator) ResetBytes(input []byte) *Iterator

ResetBytes reuse iterator instance by specifying another byte array as input

func (iter *Iterator) Skip()

Skip skips a json object and positions to relatively the next json object

func (*Iterator) SkipAndAppendBytes added in v1.1.7

func (iter *Iterator) SkipAndAppendBytes(buf []byte) []byte

SkipAndAppendBytes skips next JSON element and appends its content to buffer, returning the result.

func (*Iterator) SkipAndReturnBytes

func (iter *Iterator) SkipAndReturnBytes() []byte

SkipAndReturnBytes skip next JSON element, and return its content as []byte. The []byte can be kept, it is a copy of data.

func (iter *Iterator) WhatIsNext() ValueType

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.

type OptionalDecoder struct { ValueType reflect2.Type ValueDecoder ValDecoder }

type OptionalEncoder struct { ValueEncoder ValEncoder }

RawMessage to make replace json with jsoniter

type Stream struct { Error error

Attachment interface{}

}

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.

func (stream *Stream) Available() int

Available returns how many bytes are unused in the buffer.

func (stream *Stream) Buffer() []byte

Buffer if writer is nil, use this method to take the result

func (stream *Stream) Buffered() int

Buffered returns the number of bytes that have been written into the current buffer.

func (stream *Stream) Flush() error

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

func (stream *Stream) SetBuffer(buf []byte)

SetBuffer allows to append to the internal buffer directly

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.

func (stream *Stream) WriteArrayEnd()

WriteArrayEnd write ] with possible indention

func (stream *Stream) WriteArrayStart()

WriteArrayStart write [ with possible indention

func (stream *Stream) WriteBool(val bool)

WriteBool write true or false into stream

func (stream *Stream) WriteEmptyArray()

WriteEmptyArray write []

func (stream *Stream) WriteEmptyObject()

WriteEmptyObject write {}

func (stream *Stream) WriteFalse()

WriteFalse write false to stream

func (stream *Stream) WriteFloat32(val float32)

WriteFloat32 write float32 to stream

func (stream *Stream) WriteFloat32Lossy(val float32)

WriteFloat32Lossy write float32 to stream with ONLY 6 digits precision although much much faster

func (stream *Stream) WriteFloat64(val float64)

WriteFloat64 write float64 to stream

func (stream *Stream) WriteFloat64Lossy(val float64)

WriteFloat64Lossy write float64 to stream with ONLY 6 digits precision although much much faster

func (stream *Stream) WriteInt(val int)

WriteInt write int to stream

func (stream *Stream) WriteInt16(nval int16)

WriteInt16 write int16 to stream

func (stream *Stream) WriteInt32(nval int32)

WriteInt32 write int32 to stream

func (stream *Stream) WriteInt64(nval int64)

WriteInt64 write int64 to stream

func (stream *Stream) WriteInt8(nval int8)

WriteInt8 write int8 to stream

func (stream *Stream) WriteMore()

WriteMore write , with possible indention

func (stream *Stream) WriteNil()

WriteNil write null to stream

func (stream *Stream) WriteObjectEnd()

WriteObjectEnd write } with possible indention

func (stream *Stream) WriteObjectField(field string)

WriteObjectField write "field": with possible indention

func (stream *Stream) WriteObjectStart()

WriteObjectStart write { with possible indention

func (stream *Stream) WriteRaw(s string)

WriteRaw write string out without quotes, just like []byte

func (stream *Stream) WriteString(s string)

WriteString write string to stream without html escape

func (stream *Stream) WriteStringWithHTMLEscaped(s string)

WriteStringWithHTMLEscaped write string to stream with html special characters escaped

func (stream *Stream) WriteTrue()

WriteTrue write true to stream

func (stream *Stream) WriteUint(val uint)

WriteUint write uint to stream

func (stream *Stream) WriteUint16(val uint16)

WriteUint16 write uint16 to stream

func (stream *Stream) WriteUint32(val uint32)

WriteUint32 write uint32 to stream

func (stream *Stream) WriteUint64(val uint64)

WriteUint64 write uint64 to stream

func (stream *Stream) WriteUint8(val uint8)

WriteUint8 write uint8 to stream

func (stream *Stream) WriteVal(val interface{})

WriteVal copy the go interface into underlying JSON, same as json.Marshal

type StreamPool interface { BorrowStream(writer io.Writer) *Stream ReturnStream(stream *Stream) }

StreamPool a thread safe pool of streams with same configuration

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

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 [ValueType](#ValueType) = [iota](/builtin#iota)

StringValue

NumberValue

NilValue

BoolValue

ArrayValue

ObjectValue

)