goejs

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)

Functions

func AppendEncodedJSONFromFloat

func AppendEncodedJSONFromFloat(buf []byte, f64 float64) []byte

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

func AppendEncodedJSONFromInt(buf []byte, i int64) []byte

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

func AppendEncodedJSONFromString(buf []byte, someString string) []byte

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

func DecodedFloatFromJSON(buf []byte) (float64, []byte, error)

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

func DecodedIntFromJSON(buf []byte) (int64, []byte, error)

DecodedIntFromJSON consumes bytes from the provided byte slice to decode an integer number.

func DecodedStringFromJSON

func DecodedStringFromJSON(buf []byte) (string, []byte, error)

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"
}