jsoniter

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2026 License: MIT Imports: 19 Imported by: 0

README

Sourcegraph GoDoc Build Status codecov rcard License Gitter chat

A high-performance 100% compatible drop-in replacement of "encoding/json"

Benchmark

benchmark

Source code: https://gitee.com/i2soft/json-iterator-benchmark/blob/master/src/gitee.com/i2soft/json-iterator-benchmark/benchmark_medium_payload_test.go

Raw Result (easyjson requires static code generation)

ns/op allocation bytes allocation times
std decode 35510 ns/op 1960 B/op 99 allocs/op
easyjson decode 8499 ns/op 160 B/op 4 allocs/op
jsoniter decode 5623 ns/op 160 B/op 3 allocs/op
std encode 2213 ns/op 712 B/op 5 allocs/op
easyjson encode 883 ns/op 576 B/op 3 allocs/op
jsoniter encode 837 ns/op 384 B/op 4 allocs/op

Always benchmark with your own workload. The result depends heavily on the data input.

Usage

100% compatibility with standard lib

Replace

import "encoding/json"
json.Marshal(&data)

with

import jsoniter "gitee.com/i2soft/json-iterator"

var json = jsoniter.ConfigCompatibleWithStandardLibrary
json.Marshal(&data)

Replace

import "encoding/json"
json.Unmarshal(input, &data)

with

import jsoniter "gitee.com/i2soft/json-iterator"

var json = jsoniter.ConfigCompatibleWithStandardLibrary
json.Unmarshal(input, &data)

More documentation

How to get

go get gitee.com/i2soft/json-iterator

Contribution Welcomed !

Contributors

Report issue or pull request, or email taowen@gmail.com, or Gitter chat

Documentation

Overview

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.

Index

Examples

Constants

This section is empty.

Variables

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

ConfigCompatibleWithStandardLibrary tries to be 100% compatible with standard library behavior

View Source 
var ConfigDefault = Config{
	EscapeHTML: true,
}.Froze()

ConfigDefault the default API

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

ConfigFastest marshals float with only 6 digits precision

Functions

func CastJsonNumber 

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

func Marshal 

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

func MarshalIndent 

func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)

MarshalIndent same as json.MarshalIndent. Prefix is not supported.

func MarshalToString 

func MarshalToString(v interface{}) (string, error)

MarshalToString convenient method to write as string instead of []byte

func RegisterExtension 

func RegisterExtension(extension Extension)

RegisterExtension register extension

func RegisterFieldDecoder 

func RegisterFieldDecoder(typ string, field string, decoder ValDecoder)

RegisterFieldDecoder register TypeDecoder for a struct field

func RegisterFieldDecoderFunc 

func RegisterFieldDecoderFunc(typ string, field string, fun DecoderFunc)

RegisterFieldDecoderFunc register TypeDecoder for a struct field with function

func RegisterFieldEncoder 

func RegisterFieldEncoder(typ string, field string, encoder ValEncoder)

RegisterFieldEncoder register TypeEncoder for a struct field

func RegisterFieldEncoderFunc 

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 

func RegisterTypeDecoder(typ string, decoder ValDecoder)

RegisterTypeDecoder register TypeDecoder for a typ

func RegisterTypeDecoderFunc 

func RegisterTypeDecoderFunc(typ string, fun DecoderFunc)

RegisterTypeDecoderFunc register TypeDecoder for a type with function

func RegisterTypeEncoder 

func RegisterTypeEncoder(typ string, encoder ValEncoder)

RegisterTypeEncoder register TypeEncoder for a type

func RegisterTypeEncoderFunc 

func RegisterTypeEncoderFunc(typ string, fun EncoderFunc, isEmptyFunc func(unsafe.Pointer) bool)

RegisterTypeEncoderFunc register TypeEncoder for a type with encode/isEmpty function

func Unmarshal 

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

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

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

func Valid 

func Valid(data []byte) bool

Valid reports whether data is a valid JSON encoding.

Types

type API 

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
}

API the public interface of this package. Primary Marshal and Unmarshal.

type Any 

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 

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

Get quick method to get value from deeply nested JSON structure

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

Output:
Crimson

func Wrap 

func Wrap(val interface{}) Any

Wrap turn a go object into Any interface

func WrapFloat64 

func WrapFloat64(val float64) Any

WrapFloat64 turn float64 into Any interface

func WrapInt32 

func WrapInt32(val int32) Any

WrapInt32 turn int32 into Any interface

func WrapInt64 

func WrapInt64(val int64) Any

WrapInt64 turn int64 into Any interface

func WrapString 

func WrapString(val string) Any

WrapString turn string into Any interface

func WrapUint32 

func WrapUint32(val uint32) Any

WrapUint32 turn uint32 into Any interface

func WrapUint64 

func WrapUint64(val uint64) Any

WrapUint64 turn uint64 into Any interface

type Binding 

type Binding struct {
	Field     reflect2.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 

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 (Config) Froze 

func (cfg Config) Froze() API

Froze forge API from config

type Decoder 

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)

func NewDecoder 

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 (*Decoder) Buffered 

func (adapter *Decoder) Buffered() io.Reader

Buffered remaining buffer

func (*Decoder) Decode 

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

Decode decode JSON into interface{}

func (*Decoder) DisallowUnknownFields 

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 (*Decoder) More 

func (adapter *Decoder) More() bool

More is there more?

func (*Decoder) UseNumber 

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 

type DecoderExtension map[reflect2.Type]ValDecoder

func (DecoderExtension) CreateDecoder 

func (extension DecoderExtension) CreateDecoder(typ reflect2.Type) ValDecoder

CreateDecoder get decoder from map

func (DecoderExtension) CreateEncoder 

func (extension DecoderExtension) CreateEncoder(typ reflect2.Type) ValEncoder

CreateEncoder No-op

func (DecoderExtension) CreateMapKeyDecoder 

func (extension DecoderExtension) CreateMapKeyDecoder(typ reflect2.Type) ValDecoder

CreateMapKeyDecoder No-op

func (DecoderExtension) CreateMapKeyEncoder 

func (extension DecoderExtension) CreateMapKeyEncoder(typ reflect2.Type) ValEncoder

CreateMapKeyEncoder No-op

func (DecoderExtension) DecorateDecoder 

func (extension DecoderExtension) DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder

DecorateDecoder No-op

func (DecoderExtension) DecorateEncoder 

func (extension DecoderExtension) DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder

DecorateEncoder No-op

func (DecoderExtension) UpdateStructDescriptor 

func (extension DecoderExtension) UpdateStructDescriptor(structDescriptor *StructDescriptor)

UpdateStructDescriptor No-op

type DecoderFunc 

type DecoderFunc func(ptr unsafe.Pointer, iter *Iterator)

DecoderFunc the function form of TypeDecoder

type DummyExtension 

type DummyExtension struct {
}

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

func (*DummyExtension) CreateDecoder 

func (extension *DummyExtension) CreateDecoder(typ reflect2.Type) ValDecoder

CreateDecoder No-op

func (*DummyExtension) CreateEncoder 

func (extension *DummyExtension) CreateEncoder(typ reflect2.Type) ValEncoder

CreateEncoder No-op

func (*DummyExtension) CreateMapKeyDecoder 

func (extension *DummyExtension) CreateMapKeyDecoder(typ reflect2.Type) ValDecoder

CreateMapKeyDecoder No-op

func (*DummyExtension) CreateMapKeyEncoder 

func (extension *DummyExtension) CreateMapKeyEncoder(typ reflect2.Type)