goejs

README

goejs

Miniature Go library for properly encoding 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.

While the defacto JSON website only mentions a few rules for serializing strings into JSON, there have been many RFC documents that seek to clarify some aspects.

References

Usage

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 large enough to accomodate the encoded form of the string.

func ExampleEncode() {
	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 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("%v", decoded)
	// Output: 
⌘ a
}

Documentation

Index

• func DecodedStringFromJSON(buf []byte) (string, []byte, error)
• func EncodedJSONFromString(buf []byte, someString string) []byte

Functions

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("%v", decoded)
    // Output: �⌘ a
}

func EncodedJSONFromString

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

EncodedJSONFromString appends the JSON encoding of the provided string to the provided byte slice, and returns the modified byte slice.

func ExampleEncode() {
    encoded := goejs.EncodedJSONFromString([]byte("prefix:"), "�⌘ a")
    fmt.Printf("%s", encoded)
    // Output: prefix:"\u0001\u2318 a"
}