README
¶
goejs
Miniature Go library for properly encoding numbers and strings to JSON and back again.
Description
Want to quickly serialize Go UTF-8 strings into JSON using all of the relevant RFC documents? Then this library is for you.
How about round-trip encoding float values to and from JSON, including support for NaN, -Inf, and +Inf? This library also supports that.
While the defacto JSON website only mentions a few rules for serializing strings into JSON, there have been several errata that have been reported, and various RFC documents that seek to clarify some aspects of encoding values using JSON.
References
- https://tools.ietf.org/html/rfc4627
- https://tools.ietf.org/html/rfc7158
- https://tools.ietf.org/html/rfc7159
Usage
Documentation is available via
.
When encoding to JSON this library appends to a pre-existing slice of bytes, using the runtime to append to this slice, so it can minimize allocations if the byte slice capacity is already large enough to accomodate the encoded form of the string.
func ExampleFloatEncode() {
encoded := goejs.AppendEncodedJSONFromFloat([]byte("prefix: "), math.NaN())
fmt.Printf("%s", encoded)
// Output: prefix: null
}
func ExampleStringEncode() {
encoded := goejs.EncodedJSONFromString([]byte("prefix:"), "⌘ a")
fmt.Printf("%s", encoded)
// Output: prefix:"\u0001\u2318 a"
}
When decoding from JSON this library consumes bytes from an existing byte slice and not only returns the decoded string but also a byte slice of the remaining bytes, pointed at the original byte slice's backing array.
func ExampleFloatDecode() {
decoded, remainder, err := goejs.DecodedFloatFromJSON([]byte("null some extra bytes after final quote"))
if err != nil {
fmt.Println(err)
}
if actual, expected := string(remainder), " some extra bytes after final quote"; actual != expected {
fmt.Printf("Remainder Actual: %#q; Expected: %#q\n", actual, expected)
}
fmt.Printf("%v", decoded)
// Output: NaN
}
func ExampleStringDecode() {
decoded, remainder, err := goejs.DecodedStringFromJSON([]byte("\"\\u0001\\u2318 a\" some extra bytes after final quote"))
if err != nil {
fmt.Println(err)
}
if actual, expected := string(remainder), " some extra bytes after final quote"; actual != expected {
fmt.Printf("Remainder Actual: %#q; Expected: %#q\n", actual, expected)
}
fmt.Printf("%#q", decoded)
// Output: "\x01⌘ a"
}
Documentation
¶
Index ¶
- func AppendEncodedJSONFromFloat(buf []byte, f64 float64) []byte
- func AppendEncodedJSONFromInt(buf []byte, i int64) []byte
- func AppendEncodedJSONFromString(buf []byte, someString string) []byte
- func DecodedFloatFromJSON(buf []byte) (float64, []byte, error)
- func DecodedIntFromJSON(buf []byte) (int64, []byte, error)
- func DecodedStringFromJSON(buf []byte) (string, []byte, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendEncodedJSONFromFloat ¶ added in v0.0.3
AppendEncodedJSONFromFloat appends the JSON encoded form of the value to the provided byte slice. Because some legal IEEE 754 floating point values have no JSON equivalents, this library encodes several floating point numbers into the corresponding encoded form, as used by several other JSON encoding libraries, as shown in the table below.
JSON serialization:
NaN: null -Inf: -1e999 +Inf: 1e999
func AppendEncodedJSONFromInt ¶ added in v0.0.3
AppendEncodedJSONFromInt appends the JSON encoded form of the value to the provided byte slice. While this function merely wraps a standard library function, it is provided for API symmetry.
func AppendEncodedJSONFromString ¶ added in v0.0.3
AppendEncodedJSONFromString appends the JSON encoding of the provided string to the provided byte slice, and returns the modified byte slice.
func ExampleEncode() {
encoded := goejs.AppendEncodedJSONFromString([]byte("prefix:"), "�⌘ a")
fmt.Printf("%s", encoded)
// Output: prefix:"\u0001\u2318 a"
}
func DecodedFloatFromJSON ¶ added in v0.0.3
DecodedFloatFromJSON consumes bytes from the provided byte slice to decode a floating point number. Because some legal IEEE 754 floating point values have no JSON equivalents, this library decodes the following encoded forms, as used by several other JSON encoding libraries, into floating point numbers as shown in the table below.
JSON serialization:
NaN: null -Inf: -1e999 +Inf: 1e999
func DecodedIntFromJSON ¶ added in v0.0.3
DecodedIntFromJSON consumes bytes from the provided byte slice to decode an integer number.
func DecodedStringFromJSON ¶
DecodedStringFromJSON decodes a string from JSON, returning the decoded string and the remainder byte slice of the original buffer. On error, the returned byte slice points to the first byte that caused the error indicated.
func ExampleDecode() {
decoded, remainder, err := goejs.DecodedStringFromJSON([]byte("\"\\u0001\\u2318 a\" some extra bytes after final quote"))
if err != nil {
fmt.Println(err)
}
if actual, expected := string(remainder), " some extra bytes after final quote"; actual != expected {
fmt.Printf("Remainder Actual: %#q; Expected: %#q\n", actual, expected)
}
fmt.Printf("%#q", decoded)
// Output: "\x01⌘ a"
}
Types ¶
This section is empty.
Source Files