git.lukeshu.com/go/lowmemjson@v0.3.9-0.20230723050957-72f6d13f6fb2/compat/json/README.md (about)

     1  <!--
     2  Copyright (C) 2023  Luke Shumaker <lukeshu@lukeshu.com>
     3  
     4  SPDX-License-Identifier: GPL-2.0-or-later
     5  -->
     6  
     7  # lowmemjson/compat/json
     8  
     9  `lowmemjson/compat/json` is a wrapper around [`lowmemjson`][] that is
    10  a (mostly) drop-in replacement for the standard library's
    11  [`encoding/json`][].
    12  
    13  This package does not bother to duplicate `encoding/json`'s
    14  documentation; you should instead refer to [`encoding/json`'s own
    15  documentation][`encoding/json`].
    16  
    17  ## Incompatibilities
    18  
    19  ### Tokens
    20  
    21  Because the `lowmemjson` parser is fundamentally different than the
    22  `encoding/json` parser and does not have any notion of tokens, the
    23  token API is not included in `lowmemjson/compat/json`:
    24  
    25   - There is no [`Delim`][] type.
    26   - There is no [`Token`][] type.
    27   - There is no [`Decoder.Token`][] method.
    28  
    29  ### Types
    30  
    31  When possible, `lowmemjson/compat/json` uses type aliases for the
    32  `encoding/json` types, but in several cases that is not possible
    33  (`Encoder`, `Decoder`, `SyntaxError`, `MarshalError`).  This means
    34  that while `lowmemjson/compat/json` is source-compatible with
    35  `encoding/json`, it may not interoperate with code that also uses
    36  `encoding/json` and relies on those type identities.
    37  
    38  The errors returned by the various functions *are* the same errors as
    39  returned by `encoding/json` (with the exception that `SyntaxError` and
    40  `MarshalError` are not type aliases).
    41  
    42  ### Deprecations
    43  
    44  Types that are deprecated in `encoding/json` are not mimiced here:
    45  
    46   - There is no [`InvalidUTF8Error`][] type, as it has been depricated
    47     since Go 1.2.
    48   - There is no [`UnmarshalFieldError`][] type, as it has been
    49     depricated since Go 1.1.
    50  
    51  <!-- packages -->
    52  [`lowmemjson`]: https://pkg.go.dev/git.lukeshu.com/go/lowmemjson
    53  [`encoding/json`]: https://pkg.go.dev/encoding/json@go1.20
    54  
    55  <!-- symbols -->
    56  [`Delim`]: https://pkg.go.dev/encoding/json@go1.20#Delim
    57  [`Token`]: https://pkg.go.dev/encoding/json@go1.20#Token
    58  [`Decoder.Token`]: https://pkg.go.dev/encoding/json@go1.20#Decoder.Token
    59  [`InvalidUTF8Error`]: https://pkg.go.dev/encoding/json@go1.20#InvalidUTF8Error
    60  [`UnmarshalFieldError`]: https://pkg.go.dev/encoding/json@go1.20#UnmarshalFieldError