README
¶
json iterator (jsoniter)
faster than DOM, more usable than SAX/StAX
Why json iterator?
1. It is faster
jsoniter can work as drop in replacement for json.Unmarshal, reflection-api is not only supported, but recommended.
for performance numbers, see https://github.com/json-iterator/go-benchmark
The reflection-api is very fast, on the same scale of hand written ones.
2. io.Reader as input
jsoniter does not read the whole json into memory, it parse the document in a streaming way. There are too many json parser only take []byte as input, this one does not require so.
3. Pull style api
jsoniter can be used like drop-in replacement of json.Unmarshal, for example
type StructOfTag struct {
field1 string `json:"field-1"`
field2 string `json:"-"`
field3 int `json:",string"`
}
struct_ := StructOfTag{}
jsoniter.Unmarshal(`{"field-1": "hello", "field2": "", "field3": "100"}`, &struct_)
But it allows you to go down one level lower, to control the parsing process using pull style api (like StAX, if you know what I mean). Here is just a demo of what you can do
iter := jsoniter.ParseString(`[1,2,3]`)
for iter.ReadArray() {
iter.ReadUint64()
}
4. Customization
Of course, you can use the low level pull api to do anything you like. But most of the time, reflection based api is fast enough. How to control the parsing process when we are using the reflection api? json.Unmarshaller is not flexible enough. Jsoniter provides much better customizability.
func Test_customize_type_decoder(t *testing.T) {
RegisterTypeDecoder("time.Time", func(ptr unsafe.Pointer, iter *Iterator) {
t, err := time.ParseInLocation("2006-01-02 15:04:05", iter.ReadString(), time.UTC)
if err != nil {
iter.Error = err
return
}
*((*time.Time)(ptr)) = t
})
defer ClearDecoders()
val := time.Time{}
err := Unmarshal([]byte(`"2016-12-05 08:43:28"`), &val)
if err != nil {
t.Fatal(err)
}
year, month, day := val.Date()
if year != 2016 || month != 12 || day != 5 {
t.Fatal(val)
}
}
there is no way to add json.Unmarshaller to time.Time as the type is not defined by you (type alias time.Time is not fun to use). Using jsoniter, we can.
type Tom struct {
field1 string
}
func Test_customize_field_decoder(t *testing.T) {
RegisterFieldDecoder("jsoniter.Tom", "field1", func(ptr unsafe.Pointer, iter *Iterator) {
*((*string)(ptr)) = strconv.Itoa(iter.ReadInt())
})
defer ClearDecoders()
tom := Tom{}
err := Unmarshal([]byte(`{"field1": 100}`), &tom)
if err != nil {
t.Fatal(err)
}
}
It is very common the input json has certain fields massed up. We want string, but it is int, etc. The old way is to define a struct of exact type like the json. Then we convert from one struct to a new struct. It is just too much work. Using jsoniter you can tweak the field conversion.
5. Minimum work to parse, use whatever fits the job
I invented this wheel because I find it is tedious to parse json which does not match the object model you want to use.
Parse to map[string]interface{} is not only ugly but also slow. Parse to struct is not flexible enough to fix
some field type mismatch or structure mismatch.
If use low level tokenizer/lexer to work at the token level, it is too much work, not to mention there is very few parser out there allow you to work on this level.
jsoniter pull-api is designed to be easy to use, so that you can map your data structure directly to parsing code. It is still tedious I am not going to lie to you, but easier than pure tokenizer. The real power is, you can mix the pull-api with reflection-api. For example:
\\ given [1, {"a": "b"}]
iter.ReadArray()
iter.ReadInt()
iter.ReadArray()
iter.Read(&struct_) // reflection-api
Also by using type or field callback, we can switch from reflection-api back to pull-api. The seamless mix of both styles enabled a unique new way to parse our data.
My advice is always use the reflection-api first. Unless you find pull-api can do a better job in certain area.
Why not json iterator?
jsoniter does not plan to support map[string]interface{}, period.
Documentation
¶
Index ¶
- Constants
- Variables
- func ClearDecoders()
- func RegisterFieldDecoder(type_ string, field string, func_ DecoderFunc)
- func RegisterTypeDecoder(type_ string, func_ DecoderFunc)
- func Unmarshal(data []byte, v interface{}) error
- type Decoder
- type DecoderFunc
- type Iterator
- func (iter *Iterator) CurrentBuffer() string
- func (iter *Iterator) Read(obj interface{})
- func (iter *Iterator) ReadArray() (ret bool)
- func (iter *Iterator) ReadArrayCB(cb func())
- func (iter *Iterator) ReadBool() (ret bool)
- func (iter *Iterator) ReadFloat32() (ret float32)
- func (iter *Iterator) ReadFloat64() (ret float64)
- func (iter *Iterator) ReadInt() (ret int)
- func (iter *Iterator) ReadInt16() (ret int16)
- func (iter *Iterator) ReadInt32() (ret int32)
- func (iter *Iterator) ReadInt64() (ret int64)
- func (iter *Iterator) ReadInt8() (ret int8)
- func (iter *Iterator) ReadNull() (ret bool)
- func (iter *Iterator) ReadObject() (ret string)
- func (iter *Iterator) ReadObjectCB(cb func(string))
- func (iter *Iterator) ReadString() (ret string)
- func (iter *Iterator) ReadStringAsBytes() (ret []byte)
- func (iter *Iterator) ReadUint() (ret uint)
- func (iter *Iterator) ReadUint16() (ret uint16)
- func (iter *Iterator) ReadUint32() (ret uint32)
- func (iter *Iterator) ReadUint64() (ret uint64)
- func (iter *Iterator) ReadUint8() (ret uint8)
- func (iter *Iterator) ReportError(operation string, msg string)
- func (iter *Iterator) Reuse(input []byte) *Iterator
- func (iter *Iterator) Skip()
Constants ¶
const ( MaxRune = '\U0010FFFF' // Maximum valid Unicode code point. RuneError = '\uFFFD' // the "error" Rune or "Unicode replacement character" )
Variables ¶
var DECODERS unsafe.Pointer
Functions ¶
func ClearDecoders ¶
func ClearDecoders()
func RegisterFieldDecoder ¶
func RegisterFieldDecoder(type_ string, field string, func_ DecoderFunc)
func RegisterTypeDecoder ¶
func RegisterTypeDecoder(type_ string, func_ DecoderFunc)
Types ¶
type DecoderFunc ¶
type Iterator ¶
type Iterator struct {
Error error
// contains filtered or unexported fields
}
func ParseBytes ¶
func ParseString ¶
func (*Iterator) CurrentBuffer ¶
func (*Iterator) ReadArrayCB ¶
func (iter *Iterator) ReadArrayCB(cb func())
Source Files