From ffee5c8516f3f55f82ed5bb8f0a4f340d485fa92 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 25 Jan 2023 21:05:17 -0700 Subject: Write documentation --- compat/json/README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 compat/json/README.md (limited to 'compat/json') 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 @@ + + +# 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. + + +[`lowmemjson`]: https://pkg.go.dev/git.lukeshu.com/go/lowmemjson +[`encoding/json`]: https://pkg.go.dev/encoding/json@go1.18 + + +[`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 -- cgit v1.2.3-54-g00ecf