github.com/jxskiss/gopkg@v0.17.3/json/README.md (about)

     1  # json
     2  
     3  ## Compatibility
     4  
     5  This package provides a drop-in replacement of `encoding/json`.
     6  Any incompatible behavior with `encoding/json` is considered a bug.
     7  
     8  To get better performance, you can build your application with tag `gojson`
     9  to use [go-json], which is a fully compatible drop-in replacement
    10  of `encoding/json` but with high performance.
    11  
    12  [go-json]: https://github.com/goccy/go-json
    13  
    14  ## Performance
    15  
    16  By default, this package uses `encoding/json` from the standard library.
    17  It gives the best compatibility but not best performance.
    18  
    19  You can build your application with tag `gojson` to switch to `goccy/go-json`,
    20  which has much better performance than `encoding/json` and many other
    21  third-party JSON libraries.
    22  
    23  `goccy/go-json` is announced and tested as 100% drop-in replacement of `encoding/json`,
    24  but if you encounter some incompatible behavior unfortunately, you may remove the `gojson`
    25  build tag to quickly switch to `encoding/json`, and please
    26  [submit an issue](https://github.com/goccy/go-json/issues) to `goccy/go-json`.
    27  
    28  For marshalling map data where key ordering does not matter, you may use the shortcut
    29  function `MarshalMapUnordered`, which disables map key ordering to get even better performance
    30  (this is only available with `gojson` tag, not the standard library implementation).
    31  
    32  ## Extension
    33  
    34  ### Utilities
    35  
    36  String operation avoiding unnecessary memory allocation:
    37  
    38  1. `MarshalToString(v interface{}) (string, error)`
    39  1. `UnmarshalFromString(str string, v interface{}) error`
    40  
    41  Encoder and Decoder with method chaining capabilities:
    42  
    43  1. `NewEncoder(w).SetEscapeHTML(false).SetIndent("", "  ").Encode(v)`
    44  2. `NewDecoder(r).UseNumber().DisallowUnknownFields().Decode(v)`
    45  
    46  Disable HTMLEscape to get output more friendly to read for human:
    47  
    48  1. `MarshalNoHTMLEscape(v interface{}, indentPrefix, indent string) ([]byte, error)`
    49  
    50  Handy shortcuts to load and dump JSON data from/to file:
    51  
    52  1. `Load(path string, v interface{}) error`
    53  1. `Dump(path string, v interface{}, indentPrefix, indent string) error`
    54  
    55  ### Extended syntax
    56  
    57  `UnmarshalExt`, `LoadExt` extends the JSON syntax with following features:
    58  
    59  1. trailing comma of Object and Array
    60  1. traditional, end of line, or pragma comments
    61  1. simple identifier as object key without quotes
    62  1. Python boolean constants
    63  1. Python None as null
    64  1. Python style single quote string
    65  1. import other JSON files (with max depth limited)
    66  
    67  It helps in many scenes, such as:
    68  
    69  1. working with data generated by python program
    70  1. configuration with comments
    71  1. managing many json files with duplicate contents
    72  1. testing driven by JSON files
    73  
    74  ## Benchmark
    75  
    76  See https://github.com/goccy/go-json#benchmarks.
    77  
    78  ## Other JSON libraries
    79  
    80  1. https://github.com/tidwall/gjson <br>
    81     GJSON is a Go package that provides a fast and simple way to get values from a json document.
    82     It has features such as one line retrieval, dot notation paths, iteration, and parsing json lines.
    83   
    84  2. https://github.com/bytedance/sonic <br>
    85     Sonic is a blazingly fast JSON serializing & deserializing library, accelerated by JIT and SIMD.
    86     It is not a 100% drop-in replacement of `encoding/json`, but it performs best for various
    87     benchmarking cases, you may use it in super hot code path (but you probably want to firstly
    88     review your design which use JSON in that hot path).