diff options
Diffstat (limited to 'compat/json')
| -rw-r--r-- | compat/json/README.md | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/compat/json/README.md b/compat/json/README.md new file mode 100644 index 0000000..ec8dbed --- /dev/null +++ b/compat/json/README.md @@ -0,0 +1,60 @@ +<!-- +Copyright (C) 2023 Luke Shumaker <lukeshu@lukeshu.com> + +SPDX-License-Identifier: GPL-2.0-or-later +--> + +# lowmemjson/compat/json + +`lowmemjson/compat/json` is a wrapper around [`lowmemjson`][] that is +a (mostly) drop-in replacement for the standard library's +[`encoding/json`][]. + +This package does not bother to duplicate `encoding/json`'s +documentation; you should instead refer to [`encoding/json`'s own +documentation][`encoding/json`]. + +## Incompatibilities + +### Tokens + +Because the `lowmemjson` parser is fundamentally different than the +`encoding/json` parser and does not have any notion of tokens, the +token API is not included in `lowmemjson/compat/json`: + + - There is no [`Delim`][] type. + - There is no [`Token`][] type. + - There is no [`Decoder.Token`][] method. + +### Types + +When possible, `lowmemjson/compat/json` uses type aliases for the +`encoding/json` types, but in several cases that is not possible +(`Encoder`, `Decoder`, `SyntaxError`, `MarshalError`). This means +that while `lowmemjson/compat/json` is source-compatible with +`encoding/json`, it may not interoperate with code that also uses +`encoding/json` and relies on those type identities. + +The errors returned by the various functions *are* the same errors as +returned by `encoding/json` (with the exception that `SyntaxError` and +`MarshalError` are not type aliases). + +### Deprecations + +Types that are deprecated in `encoding/json` are not mimiced here: + + - There is no [`InvalidUTF8Error`][] type, as it has been depricated + since Go 1.2. + - There is no [`UnmarshalFieldError`][] type, as it has been + depricated since Go 1.1. + +<!-- packages --> +[`lowmemjson`]: https://pkg.go.dev/git.lukeshu.com/go/lowmemjson +[`encoding/json`]: https://pkg.go.dev/encoding/json@go1.18 + +<!-- symbols --> +[`Delim`]: https://pkg.go.dev/encoding/json@go1.18#Delim +[`Token`]: https://pkg.go.dev/encoding/json@go1.18#Token +[`Decoder.Token`]: https://pkg.go.dev/encoding/json@go1.18#Decoder.Token +[`InvalidUTF8Error`]: https://pkg.go.dev/encoding/json@go1.18#InvalidUTF8Error +[`UnmarshalFieldError`]: https://pkg.go.dev/encoding/json@go1.18#UnmarshalFieldError |