ConfigCompatibleWithStandardLibrary tries to be 100% compatible with standard library behavior
var ConfigCompatibleWithStandardLibrary = Config{ EscapeHTML: true, SortMapKeys: true, ValidateJsonRawMessage: true, }.Froze()
ConfigDefault the default API
var ConfigDefault = Config{ EscapeHTML: true, }.Froze()
ConfigFastest marshals float with only 6 digits precision
var ConfigFastest = Config{ EscapeHTML: false, MarshalFloatWith6Digits: true, ObjectFieldMustBeSimpleString: true, }.Froze()
func CastJsonNumber(val interface{}) (string, bool)
func Marshal(v interface{}) ([]byte, error)
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
▹ Example
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
MarshalIndent same as json.MarshalIndent. Prefix is not supported.
func MarshalToString(v interface{}) (string, error)
MarshalToString convenient method to write as string instead of []byte
func RegisterExtension(extension Extension)
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
func RegisterTypeEncoderFunc(typ string, fun EncoderFunc, isEmptyFunc func(unsafe.Pointer) bool)
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
▹ Example
func UnmarshalFromString(str string, v interface{}) error
UnmarshalFromString is a convenient method to read from string instead of []byte
func Valid(data []byte) bool
Valid reports whether data is a valid JSON encoding.
API the public interface of this package. Primary Marshal and Unmarshal.
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
RegisterExtension(extension Extension)
DecoderOf(typ reflect2.Type) ValDecoder
EncoderOf(typ reflect2.Type) ValEncoder
}
Any generic object representation. The lazy json implementation holds []byte and parse lazily.
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)
}
func Get(data []byte, path ...interface{}) Any
Get quick method to get value from deeply nested JSON structure
▹ Example
func Wrap(val interface{}) Any
Wrap turn a go object into Any interface
func WrapFloat64(val float64) Any
WrapFloat64 turn float64 into Any interface
func WrapInt32(val int32) Any
WrapInt32 turn int32 into Any interface
func WrapInt64(val int64) Any
WrapInt64 turn int64 into Any interface
func WrapString(val string) Any
WrapString turn string into Any interface
func WrapUint32(val uint32) Any
WrapUint32 turn uint32 into Any interface
func WrapUint64(val uint64) Any
WrapUint64 turn uint64 into Any interface
Binding describe how should we encode/decode the struct field
type Binding struct {
Field reflect2.StructField
FromNames []string
ToNames []string
Encoder ValEncoder
Decoder ValDecoder
// contains filtered or unexported fields
}
Config customize how the API should behave. The API is created from Config by Froze.
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
}
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)
type Decoder struct {
// contains filtered or unexported fields
}
func NewDecoder(reader io.Reader) *Decoder
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
func (adapter *Decoder) Buffered() io.Reader
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.
type DecoderExtension map[reflect2.Type]ValDecoder
func (extension DecoderExtension) CreateDecoder(typ reflect2.Type) ValDecoder
CreateDecoder get decoder from map
func (extension DecoderExtension) CreateEncoder(typ reflect2.Type) ValEncoder
CreateEncoder No-op
func (extension DecoderExtension) CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
CreateMapKeyDecoder No-op
func (extension DecoderExtension) CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
CreateMapKeyEncoder No-op
func (extension DecoderExtension) DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
DecorateDecoder No-op
func (extension DecoderExtension) DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
DecorateEncoder No-op
func (extension DecoderExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)
UpdateStructDescriptor No-op
DecoderFunc the function form of TypeDecoder
type DecoderFunc func(ptr unsafe.Pointer, iter *Iterator)
DummyExtension embed this type get dummy implementation for all methods of Extension
type DummyExtension struct {
}
func (extension *DummyExtension) CreateDecoder(typ reflect2.Type) ValDecoder
CreateDecoder No-op
func (extension *DummyExtension) CreateEncoder(typ reflect2.Type) ValEncoder
CreateEncoder No-op
func (extension *DummyExtension) CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
CreateMapKeyDecoder No-op
func (extension *DummyExtension) CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
CreateMapKeyEncoder No-op
func (extension *DummyExtension) DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
DecorateDecoder No-op
func (extension *DummyExtension) DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
DecorateEncoder No-op
func (extension *DummyExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)
UpdateStructDescriptor No-op
Encoder same as json.Encoder
type Encoder struct {
// contains filtered or unexported fields
}
func NewEncoder(writer io.Writer) *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
type EncoderExtension map[reflect2.Type]ValEncoder
func (extension EncoderExtension) CreateDecoder(typ reflect2.Type) ValDecoder
CreateDecoder No-op
func (extension EncoderExtension) CreateEncoder(typ reflect2.Type) ValEncoder
CreateEncoder get encoder from map
func (extension EncoderExtension) CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
CreateMapKeyDecoder No-op
func (extension EncoderExtension) CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
CreateMapKeyEncoder No-op
func (extension EncoderExtension) DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
DecorateDecoder No-op
func (extension EncoderExtension) DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
DecorateEncoder No-op
func (extension EncoderExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)
UpdateStructDescriptor No-op
EncoderFunc the function form of TypeEncoder
type EncoderFunc func(ptr unsafe.Pointer, stream *Stream)
Extension the one for all SPI. Customize encoding/decoding by specifying alternate encoder/decoder. Can also rename fields by UpdateStructDescriptor.
type Extension interface {
UpdateStructDescriptor(structDescriptor *StructDescriptor)
CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
CreateDecoder(typ reflect2.Type) ValDecoder
CreateEncoder(typ reflect2.Type) ValEncoder
DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
}
type IsEmbeddedPtrNil interface {
IsEmbeddedPtrNil(ptr unsafe.Pointer) bool
}
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.
type Iterator struct {
Error error
Attachment interface{} // open for customized decoder
// contains filtered or unexported fields
}
func NewIterator(cfg API) *Iterator
NewIterator creates an empty Iterator instance
func Parse(cfg API, reader io.Reader, bufSize int) *Iterator
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
func (iter *Iterator) ReadMapCB(callback func(*Iterator, string) bool) bool
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
func (iter *Iterator) ReadNumber() (ret json.Number)
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.
func (iter *Iterator) ReadObjectCB(callback func(*Iterator, string) bool) bool
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) ReadUint64() uint64
ReadUint64 read uint64
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
func (iter *Iterator) ReportError(operation string, msg string)
ReportError record a error in iterator instance with current position.
func (iter *Iterator) Reset(reader io.Reader) *Iterator
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 (iter *Iterator) SkipAndAppendBytes(buf []byte) []byte
SkipAndAppendBytes skips next JSON element and appends its content to buffer, returning the result.
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
IteratorPool a thread safe pool of iterators with same configuration
type IteratorPool interface {
BorrowIterator(data []byte) *Iterator
ReturnIterator(iter *Iterator)
}
type Number string
func (n Number) Float64() (float64, error)
Float64 returns the number as a float64.
func (n Number) Int64() (int64, error)
Int64 returns the number as an int64.
func (n Number) String() string
String returns the literal text of the number.
type OptionalDecoder struct {
ValueType reflect2.Type
ValueDecoder ValDecoder
}
func (decoder *OptionalDecoder) Decode(ptr unsafe.Pointer, iter *Iterator)
type OptionalEncoder struct {
ValueEncoder ValEncoder
}
func (encoder *OptionalEncoder) Encode(ptr unsafe.Pointer, stream *Stream)
func (encoder *OptionalEncoder) IsEmpty(ptr unsafe.Pointer) bool
RawMessage to make replace json with jsoniter
type RawMessage []byte
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.
type Stream struct {
Error error
Attachment interface{} // open for customized encoder
// contains filtered or unexported fields
}
func NewStream(cfg API, out io.Writer, bufSize int) *Stream
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
func (stream *Stream) Reset(out io.Writer)
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
func (stream *Stream) Write(p []byte) (nn int, err error)
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
StreamPool a thread safe pool of streams with same configuration
type StreamPool interface {
BorrowStream(writer io.Writer) *Stream
ReturnStream(stream *Stream)
}
StructDescriptor describe how should we encode/decode the struct
type StructDescriptor struct {
Type reflect2.Type
Fields []*Binding
}
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 ValDecoder interface {
Decode(ptr unsafe.Pointer, iter *Iterator)
}
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).
type ValEncoder interface {
IsEmpty(ptr unsafe.Pointer) bool
Encode(ptr unsafe.Pointer, stream *Stream)
}
ValueType the type for JSON element
type ValueType int
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
)