json

README

json

Compatibility

This package provides a drop-in replacement of encoding/json. Any incompatible behavior with encoding/json is considered a bug.

To get better performance, you can build your application with tag unsafejson to use go-json, which is a fully compatible drop-in replacement of encoding/json but with high performance.

Performance

By default, this package uses encoding/json from the standard library. It gives the best compatibility but not best performance.

You can build your application with tag unsafejson to switch to goccy/go-json, which has much better performance than encoding/json and many other third-party JSON libraries.

goccy/go-json is announced and tested as 100% drop-in replacement of encoding/json, but if you encounter some incompatible behavior unfortunately, you may remove the unsafejson build tag to quickly switch to encoding/json, and please submit an issue to goccy/go-json.

For marshalling map data where key ordering does not matter, you may use the shortcut function MarshalMapUnordered, which disables map key ordering to get even better performance (this is only available with unsafejson tag, not the standard library implementation).

Utilities

String operation avoiding unnecessary memory allocation:

1. MarshalToString(v interface{}) (string, error)
2. UnmarshalFromString(str string, v interface{}) error

Encoder and Decoder with method chaining capabilities:

1. NewEncoder(w).SetEscapeHTML(false).SetIndent("", " ").Encode(v)
2. NewDecoder(r).UseNumber().DisallowUnknownFields().Decode(v)

Disable HTMLEscape to get output more friendly to read for human:

1. MarshalNoHTMLEscape(v interface{}, prefix, indent string) ([]byte, error)

Handy shortcuts to load and dump JSON data from/to file:

1. Load(path string, v interface{}) error
2. Dump(path string, v interface{}, prefix, indent string) error

Benchmark

See https://github.com/goccy/go-json#benchmarks.

Other JSON libraries

1. https://github.com/tidwall/gjson
   GJSON is a Go package that provides a fast and simple way to get values from a json document. It has features such as one line retrieval, dot notation paths, iteration, and parsing json lines.

2. https://github.com/bytedance/sonic
   Sonic is a blazingly fast JSON serializing & deserializing library, accelerated by JIT and SIMD. It is not a 100% drop-in replacement of encoding/json, but it performs best for various benchmarking cases, you may use it in super hot code path (but you probably want to firstly review your design which use JSON in that hot path).

3. https://github.com/jxskiss/extjson
   extjson extends the JSON syntax, it allows extended features such as trailing comma in object and array, adding comment, including another JSON file, referencing to other values.

Documentation

Index

• func Compact(dst *bytes.Buffer, src []byte) error
• func Dump(path string, v interface{}, prefix, indent string) error
• func HTMLEscape(dst *bytes.Buffer, src []byte)
• func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
• func Load(path string, v interface{}) error
• func Marshal(v interface{}) ([]byte, error)
• func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
• func MarshalNoHTMLEscape(v interface{}, prefix, indent string) ([]byte, error)
• func MarshalNoMapOrdering(v interface{}) ([]byte, error)
• func MarshalToString(v interface{}) (string, error)
• func Unmarshal(data []byte, v interface{}) error
• func UnmarshalFromString(data string, v interface{}) error
• func Valid(data []byte) bool
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) DisallowUnknownFields() *Decoder
  • func (dec *Decoder) UseNumber() *Decoder
• type Delim
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) DisableMapOrdering() *Encoder
  • func (enc *Encoder) Encode(v interface{}) error
  • func (enc *Encoder) SetEscapeHTML(on bool) *Encoder
  • func (enc *Encoder) SetIndent(prefix, indent string) *Encoder
• type InvalidUTF8Error
• type InvalidUnmarshalError
• type Marshaler
• type MarshalerError
• type Number
• type RawMessage
• type SyntaxError
• type Token
• type UnmarshalFieldError
• type UnmarshalTypeError
• type Unmarshaler
• type UnsupportedTypeError
• type UnsupportedValueError

Functions

func Compact

func Compact(dst *bytes.Buffer, src []byte) error

func Dump

func Dump(path string, v interface{}, prefix, indent string) error

Dump writes v to the named file at path using JSON encoding. It disables HTMLEscape. Optionally indent can be applied to the output, empty prefix and indent disables indentation. The output is friendly to read by humans.

func HTMLEscape

func HTMLEscape(dst *bytes.Buffer, src []byte)

func Indent

func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error

func Load

func Load(path string, v interface{}) error

Load reads JSON-encoded data from the named file at path and stores the result in the value pointed to by v.

func Marshal

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

Marshal returns the JSON encoding of v.

See encoding/json.Marshal for detailed document.

func MarshalIndent

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

MarshalIndent is like Marshal but applies Indent to format the output.

See encoding/json.MarshalIndent for detailed document.

func MarshalNoHTMLEscape

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

MarshalNoHTMLEscape is like Marshal but does not escape HTML characters. Optionally indent can be applied to the output, empty prefix and indent disables indentation. The output is more friendly to read for log messages.

func MarshalNoMapOrdering

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

MarshalNoMapOrdering is like Marshal but does not sort map keys. It's useful to optimize performance where map key ordering is not needed.

It has effect only when build with tag "jsoniter", "gojson" or "unsafejson", else it is an alias name of Marshal.

func MarshalToString

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

MarshalToString returns the JSON encoding of v as string.

See encoding/json.Marshal for detailed document.

func Unmarshal

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

Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v.

See encoding/json.Unmarshal for detailed document.

func UnmarshalFromString

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

UnmarshalFromString parses the JSON-encoded string data and stores the result in the value pointed to by v.

See encoding/json.Unmarshal for detailed document.

func Valid

func Valid(data []byte) bool

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder is a wrapper of encoding/json.Decoder. It provides same methods as encoding/json.Decoder but with method chaining capabilities.

See encoding/json.Decoder for detailed document.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new Decoder that reads from r.

func (*Decoder) DisallowUnknownFields

func (dec *Decoder) DisallowUnknownFields() *Decoder

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

func (dec *Decoder) UseNumber() *Decoder

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

type Delim

type Delim = json.Delim

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is a wrapper of encoding/json.Encoder. It provides same methods as encoding/json.Encoder but with method chaining capabilities.

See encoding/json.Encoder for detailed document.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder that writes to w.

func (*Encoder) DisableMapOrdering

func (enc *Encoder) DisableMapOrdering() *Encoder

DisableMapOrdering instructs the encoder to not sort map keys.

This option has effect only when build with tag "jsoniter", "gojson" or "unsafejson", else calling it is a no-op.

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode writes the JSON encoding of v to the stream, followed by a newline character.

See the documentation for Marshal for details about the conversion of Go values to JSON.

func (*Encoder) SetEscapeHTML

func (enc *Encoder) SetEscapeHTML(on bool) *Encoder

SetEscapeHTML specifies whether problematic HTML characters should be escaped inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML.

In non-HTML settings where the escaping interferes with the readability of the output, SetEscapeHTML(false) disables this behavior.

func (*Encoder) SetIndent

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

SetIndent instructs the encoder to format each subsequent encoded value as if indented by the package-level function Indent(dst, src, prefix, indent). Calling SetIndent("", "") disables indentation.

type InvalidUTF8Error

type InvalidUTF8Error = json.InvalidUTF8Error

type InvalidUnmarshalError

type InvalidUnmarshalError = json.InvalidUnmarshalError

type Marshaler

type Marshaler = json.Marshaler

Marshaler is an alias name of encoding/json.Marshaler. See encoding/json.Marshaler for detailed document.

type MarshalerError

type MarshalerError = json.MarshalerError

type Number

type Number = json.Number

type RawMessage

type RawMessage = json.RawMessage

type SyntaxError

type SyntaxError = json.SyntaxError

type Token

type Token = json.Token

type UnmarshalFieldError

type UnmarshalFieldError = json.UnmarshalFieldError

type UnmarshalTypeError

type UnmarshalTypeError = json.UnmarshalTypeError

type Unmarshaler

type Unmarshaler = json.Unmarshaler

Unmarshaler is an alias name of encoding/json.Unmarshaler. See encoding/json.Unmarshaler for detailed document.

type UnsupportedTypeError

type UnsupportedTypeError = json.UnsupportedTypeError

type UnsupportedValueError

type UnsupportedValueError = json.UnsupportedValueError