github.com/jxskiss/gopkg/v2@v2.14.9-0.20240514120614-899f3e7952b4/perf/json/README.md (about)

     1  # json
     2  
     3  Package json provides a on-the-fly change-able API for JSON serialization.
     4  
     5  ## Compatibility
     6  
     7  By default, it uses [jsoniter] `ConfigCompatibleWithStandardLibrary` in underlying,
     8  but the underlying implementation can be changed on-the-fly, e.g.
     9  use the standard library or use a custom jsoniter config,
    10  or switch to a [bytedance/sonic] implementation.
    11  You may see [_examples/perf/json/bytedance_sonic]()
    12  for an example to use bytedance/sonic as the underlying implementation.
    13  
    14  When encoding data using `interface{}` as map keys (e.g. `map[any]any`),
    15  both the standard library and sonic will fail, user should use jsoniter.
    16  
    17  [bytedance/sonic]: https://github.com/bytedance/sonic
    18  
    19  [jsoniter]: https://github.com/json-iterator/go
    20  
    21  ## Performance
    22  
    23  By default, this package uses `jsoniter.ConfigCompatibleWithStandardLibrary` API.
    24  It gives better performance than `encoding/json` and good compatibility with it.
    25  
    26  User may use `ChangeImpl` to switch to a different underlying implementation.
    27  
    28  For best performance, user may use `MarshalFastest` when the underlying
    29  implementation is jsoniter or sonic. The result is not compatible with std
    30  `encoding/json` in some ways, especially that map keys are not sorted.
    31  
    32  ### Benchmark
    33  
    34  See https://github.com/json-iterator/go#benchmark.
    35  
    36  ## Utilities
    37  
    38  String operation avoiding unnecessary memory allocation:
    39  
    40  1. `MarshalToString(v any) (string, error)`
    41  2. `UnmarshalFromString(str string, v any) error`
    42  
    43  Encoder and Decoder with method chaining capabilities:
    44  
    45  1. `NewEncoder(w).SetEscapeHTML(false).SetIndent(prefix, indent).Encode(v)`
    46  2. `NewDecoder(r).UseNumber().DisallowUnknownFields().Decode(v)`
    47  
    48  Disable HTMLEscape to get output more friendly to read for human:
    49  
    50  1. `MarshalNoHTMLEscape(v any, prefix, indent string) ([]byte, error)`
    51  
    52  Handy shortcuts to load and dump JSON data from/to a file:
    53  
    54  1. `Load(path string, v any) error`
    55  2. `Dump(path string, v any, prefix, indent string) error`
    56  3. `Fdump(w io.Writer, v any, prefix, indent string) error`
    57  
    58  Generates human-friendly result (with lower performance):
    59  
    60  1. `HumanFriendly.Marshal(v any) ([]byte, error)`
    61  2. `HumanFriendly.MarshalToString(v any) (string, error)`
    62  3. `HumanFriendly.MarshalIndent(v any, prefix, indent string) ([]byte, error)`
    63  4. `HumanFriendly.MarshalIndentString(v any, prefix, indent string) (string, error)`
    64  5. `HumanFriendly.NewEncoder(w io.Writer) *Encoder`
    65  
    66  ## Other JSON libraries
    67  
    68  1. https://github.com/tidwall/gjson <br>
    69     GJSON is a Go package that provides a fast and simple way to get values from a json document.
    70     It has features such as one line retrieval, dot notation paths, iteration, and parsing json lines.
    71  
    72  2. https://github.com/bytedance/sonic <br>
    73     Sonic is a blazingly fast JSON serializing & deserializing library, accelerated by JIT and SIMD.
    74     It is not a 100% drop-in replacement of `encoding/json`, but it performs best for various
    75     benchmarking cases.
    76  
    77  3. https://github.com/goccy/go-json <br>
    78     Fast JSON encoder/decoder announced to be fully compatible with encoding/json for Go.