json

package
v2.15.2 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2024 License: MIT Imports: 7 Imported by: 1

README

json

Package json provides a on-the-fly change-able API for JSON serialization.

Compatibility

By default, it uses jsoniter ConfigCompatibleWithStandardLibrary in underlying, but the underlying implementation can be changed on-the-fly, e.g. use the standard library or use a custom jsoniter config, or switch to a bytedance/sonic implementation. You may see _examples/perf/json/bytedance_sonic for an example to use bytedance/sonic as the underlying implementation.

When encoding data using interface{} as map keys (e.g. map[any]any), both the standard library and sonic will fail, user should use jsoniter.

Performance

By default, this package uses jsoniter.ConfigCompatibleWithStandardLibrary API. It gives better performance than encoding/json and good compatibility with it.

User may use ChangeImpl to switch to a different underlying implementation.

For best performance, user may use MarshalFastest when the underlying implementation is jsoniter or sonic. The result is not compatible with std encoding/json in some ways, especially that map keys are not sorted.

Benchmark

See https://github.com/json-iterator/go#benchmark.

Utilities

String operation avoiding unnecessary memory allocation:

  1. MarshalToString(v any) (string, error)
  2. UnmarshalFromString(str string, v any) error

Encoder and Decoder with method chaining capabilities:

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

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

  1. MarshalNoHTMLEscape(v any, prefix, indent string) ([]byte, error)

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

  1. Load(path string, v any) error
  2. Dump(path string, v any, prefix, indent string) error
  3. Fdump(w io.Writer, v any, prefix, indent string) error

Generates human-friendly result (with lower performance):

  1. HumanFriendly.Marshal(v any) ([]byte, error)
  2. HumanFriendly.MarshalToString(v any) (string, error)
  3. HumanFriendly.MarshalIndent(v any, prefix, indent string) ([]byte, error)
  4. HumanFriendly.MarshalIndentString(v any, prefix, indent string) (string, error)
  5. HumanFriendly.NewEncoder(w io.Writer) *Encoder

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.

  3. https://github.com/goccy/go-json
    Fast JSON encoder/decoder announced to be fully compatible with encoding/json for Go.

Documentation

Overview

Package json provides a on-the-fly change-able API for JSON serialization.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultJSONIteratorImpl = NewJSONIteratorImpl(
	jsoniter.ConfigCompatibleWithStandardLibrary, true)

DefaultJSONIteratorImpl uses jsoniter.ConfigCompatibleWithStandardLibrary as the underlying implementation.

View Source 
var HumanFriendly = struct {
	Marshal             func(v any) ([]byte, error)
	MarshalToString     func(v any) (string, error)
	MarshalIndent       func(v any, prefix, indent string) ([]byte, error)
	MarshalIndentString func(v any, prefix, indent string) (string, error)
	NewEncoder          func(w io.Writer) *Encoder
}{
	Marshal:             hFriendlyMarshal,
	MarshalToString:     hFriendlyMarshalToString,
	MarshalIndent:       hFriendlyMarshalIndent,
	MarshalIndentString: hFriendlyMarshalIndentString,
	NewEncoder:          newHumanFriendlyEncoder,
}

HumanFriendly is a config which generates data that is more friendly for human reading. Also, this config can encode data with `interface{}` as map keys, in contrast, the standard library fails in this case.

Functions

func ChangeImpl added in v2.13.0 

func ChangeImpl(impl Implementation)

ChangeImpl changes the underlying JSON implementation on-the-fly at runtime.

You may see github.com/jxskiss/gopkg/_examples/perf/json/bytedance_sonic for an example to use github.com/bytedance/sonic as the underlying implementation.

func Compact 

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

Compact appends to dst the JSON-encoded src with insignificant space characters elided.

func Dump 

func Dump(path string, v any, 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 Fdump added in v2.8.5 

func Fdump(w io.Writer, v any, prefix, indent string) error

Fdump writes v to the given io.Writer 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)

HTMLEscape appends to dst the JSON-encoded src with <, >, &, U+2028 and U+2029 characters inside string literals changed to \u003c, \u003e, \u0026, \u2028, \u2029 so that the JSON will be safe to embed inside HTML <script> tags. For historical reasons, web browsers don't honor standard HTML escaping within <script> tags, so an alternative JSON encoding must be used.

func Indent 

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

Indent appends to dst an indented form of the JSON-encoded src. See encoding/json.Indent for detailed document.

func Load 

func Load(path string, v any) 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 any) ([]byte, error)

Marshal returns the JSON encoding of v.

See encoding/json.Marshal for detailed document.

func MarshalFastest added in v2.10.0 

func MarshalFastest(v any) ([]byte, error)

MarshalFastest uses the fastest config if the underlying implementation supports it, e.g. jsoniter and sonic. The result may be incompatible with std encoding/json in some ways, especially that map keys may be not sorted.

func MarshalIndent 

func MarshalIndent(v any, 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 any, 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 MarshalToString 

func MarshalToString(v any) (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 any) 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 any) 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

Valid reports whether data is a valid JSON encoding.

Types

type Decoder 

type Decoder struct {
	UnderlyingDecoder
}

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 Encoder 

type Encoder struct {
	UnderlyingEncoder
}

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) 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 Implementation added in v2.13.0 

type Implementation interface {
	Marshal(v any) ([]byte, error)
	MarshalIndent(v any, prefix, indent string) ([]byte, error)
	Unmarshal(data []byte, v any) error
	Valid(data []byte) bool

	MarshalToString(v any) (string, error)
	UnmarshalFromString(data string, v any) error

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

	MarshalFastest(v any) ([]byte, error)
	MarshalNoHTMLEscape(v any, prefix, indent string) ([]byte, error)

	NewEncoder(w io.Writer) UnderlyingEncoder
	NewDecoder(r io.Reader) UnderlyingDecoder
}

Implementation is the interface of an underlying JSON implementation. User can change the underlying implementation on-the-fly at runtime. 

var StdImpl Implementation = stdImpl{}

StdImpl uses package "encoding/json" in the standard library as the underlying implementation.

func NewJSONIteratorImpl added in v2.13.0 

func NewJSONIteratorImpl(api jsoniter.API, useConfigFastest bool) Implementation

NewJSONIteratorImpl returns an implementation which uses api as the underlying config. If useConfigFastest is true, it uses jsoniter.ConfigFastest for method MarshalFastest, else it uses api.Marshal.

type Marshaler 

type Marshaler = json.Marshaler

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

type RawMessage 

type RawMessage = json.RawMessage

RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding.

type UnderlyingDecoder added in v2.13.0 

type UnderlyingDecoder interface {
	Decode(val interface{}) error
	Buffered() io.Reader
	DisallowUnknownFields()
	More() bool
	UseNumber()
}

type UnderlyingEncoder added in v2.13.0 

type UnderlyingEncoder interface {
	Encode(val interface{}) error
	SetEscapeHTML(on bool)
	SetIndent(prefix, indent string)
}

type Unmarshaler 

type Unmarshaler = json.Unmarshaler

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.