github.com/neilotoole/jsoncolor@v0.7.2-0.20231115150201-1637fae69be1/SEGMENTIO_README.md (about)

     1  # encoding/json [![GoDoc](https://godoc.org/github.com/segmentio/encoding/json?status.svg)](https://godoc.org/github.com/segmentio/encoding/json)
     2  
     3  Go package offering a replacement implementation of the standard library's
     4  [`encoding/json`](https://golang.org/pkg/encoding/json/) package, with much
     5  better performance.
     6  
     7  ## Usage
     8  
     9  The exported API of this package mirrors the standard library's
    10  [`encoding/json`](https://golang.org/pkg/encoding/json/) package, the only
    11  change needed to take advantage of the performance improvements is the import
    12  path of the `json` package, from:
    13  ```go
    14  import (
    15      "encoding/json"
    16  )
    17  ```
    18  to
    19  ```go
    20  import (
    21      "github.com/segmentio/encoding/json"
    22  )
    23  ```
    24  
    25  One way to gain higher encoding throughput is to disable HTML escaping.
    26  It allows the string encoding to use a much more efficient code path which
    27  does not require parsing UTF-8 runes most of the time.
    28  
    29  ## Performance Improvements
    30  
    31  The internal implementation uses a fair amount of unsafe operations (untyped
    32  code, pointer arithmetic, etc...) to avoid using reflection as much as possible,
    33  which is often the reason why serialization code has a large CPU and memory
    34  footprint.
    35  
    36  The package aims for zero unnecessary dynamic memory allocations and hot code
    37  paths that are mostly free from calls into the reflect package.
    38  
    39  ## Compatibility with encoding/json
    40  
    41  This package aims to be a drop-in replacement, therefore it is tested to behave
    42  exactly like the standard library's package. However, there are still a few
    43  missing features that have not been ported yet:
    44  
    45  - Streaming decoder, currently the `Decoder` implementation offered by the
    46  package does not support progressively reading values from a JSON array (unlike
    47  the standard library). In our experience this is a very rare use-case, if you
    48  need it you're better off sticking to the standard library, or spend a bit of
    49  time implementing it in here ;)
    50  
    51  Note that none of those features should result in performance degradations if
    52  they were implemented in the package, and we welcome contributions!
    53  
    54  ## Trade-offs
    55  
    56  As one would expect, we had to make a couple of trade-offs to achieve greater
    57  performance than the standard library, but there were also features that we
    58  did not want to give away.
    59  
    60  Other open-source packages offering a reduced CPU and memory footprint usually
    61  do so by designing a different API, or require code generation (therefore adding
    62  complexity to the build process). These were not acceptable conditions for us,
    63  as we were not willing to trade off developer productivity for better runtime
    64  performance. To achieve this, we chose to exactly replicate the standard
    65  library interfaces and behavior, which meant the package implementation was the
    66  only area that we were able to work with. The internals of this package make
    67  heavy use of unsafe pointer arithmetics and other performance optimizations,
    68  and therefore are not as approachable as typical Go programs. Basically, we put
    69  a bigger burden on maintainers to achieve better runtime cost without
    70  sacrificing developer productivity.
    71  
    72  For these reasons, we also don't believe that this code should be ported upstream
    73  to the standard `encoding/json` package. The standard library has to remain
    74  readable and approachable to maximize stability and maintainability, and make
    75  projects like this one possible because a high quality reference implementation
    76  already exists.