sjson

README

set a json value quickly

SJSON is a Go package that provides a very fast and simple way to set a value in a json document. The purpose for this library is to provide efficient json updating for the SummitDB project. For quickly retrieving json values check out GJSON.

For a command line interface check out JSONed.

Getting Started

Installing

To start using SJSON, install Go and run go get:

$ go get -u github.com/tidwall/sjson

This will retrieve the library.

Set a value

Set sets the value for the specified path. A path is in dot syntax, such as "name.last" or "age". This function expects that the json is well-formed and validated. Invalid json will not panic, but it may return back unexpected results. Invalid paths may return an error.

package main

import "github.com/tidwall/sjson"

const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`

func main() {
	value, _ := sjson.Set(json, "name.last", "Anderson")
	println(value)
}

This will print:

{"name":{"first":"Janet","last":"Anderson"},"age":47}

Path syntax

A path is a series of keys separated by a dot. The dot and colon characters can be escaped with ''.

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
	{"first": "James", "last": "Murphy"},
	{"first": "Roger", "last": "Craig"}
  ]
}

"name.last"          >> "Anderson"
"age"                >> 37
"children.1"         >> "Alex"
"friends.1.last"     >> "Craig"

The -1 key can be used to append a value to an existing array:

"children.-1"  >> appends a new value to the end of the children array

Normally number keys are used to modify arrays, but it's possible to force a numeric object key by using the colon character:

{
  "users":{
    "2313":{"name":"Sara"},
    "7839":{"name":"Andy"}
  }
}

A colon path would look like:

"users.:2313.name"    >> "Sara"

Supported types

Pretty much any type is supported:

sjson.Set(`{"key":true}`, "key", nil)
sjson.Set(`{"key":true}`, "key", false)
sjson.Set(`{"key":true}`, "key", 1)
sjson.Set(`{"key":true}`, "key", 10.5)
sjson.Set(`{"key":true}`, "key", "hello")
sjson.Set(`{"key":true}`, "key", map[string]interface{}{"hello":"world"})

When a type is not recognized, SJSON will fallback to the encoding/json Marshaller.

Examples

Set a value from empty document:

value, _ := sjson.Set("", "name", "Tom")
println(value)

// Output:
// {"name":"Tom"}

Set a nested value from empty document:

value, _ := sjson.Set("", "name.last", "Anderson")
println(value)

// Output:
// {"name":{"last":"Anderson"}}

Set a new value:

value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.first", "Sara")
println(value)

// Output:
// {"name":{"first":"Sara","last":"Anderson"}}

Update an existing value:

value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.last", "Smith")
println(value)

// Output:
// {"name":{"last":"Smith"}}

Set a new array value:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.2", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]

Append an array value by using the -1 key in a path:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.-1", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]

Append an array value that is past the end:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.4", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol",null,null,"Sara"]

Delete a value:

value, _ := sjson.Delete(`{"name":{"first":"Sara","last":"Anderson"}}`, "name.first")
println(value)

// Output:
// {"name":{"last":"Anderson"}}

Delete an array value:

value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.1")
println(value)

// Output:
// {"friends":["Andy"]}

Delete the last array value:

value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.-1")
println(value)

// Output:
// {"friends":["Andy"]}

Performance

Benchmarks of SJSON alongside encoding/json, ffjson, EasyJSON, and Gabs

Benchmark_SJSON-8                  	 3000000	       805 ns/op	    1077 B/op	       3 allocs/op
Benchmark_SJSON_ReplaceInPlace-8   	 3000000	       449 ns/op	       0 B/op	       0 allocs/op
Benchmark_JSON_Map-8               	  300000	     21236 ns/op	    6392 B/op	     150 allocs/op
Benchmark_JSON_Struct-8            	  300000	     14691 ns/op	    1789 B/op	      24 allocs/op
Benchmark_Gabs-8                   	  300000	     21311 ns/op	    6752 B/op	     150 allocs/op
Benchmark_FFJSON-8                 	  300000	     17673 ns/op	    3589 B/op	      47 allocs/op
Benchmark_EasyJSON-8               	 1500000	      3119 ns/op	    1061 B/op	      13 allocs/op

JSON document used:

{
  "widget": {
    "debug": "on",
    "window": {
      "title": "Sample Konfabulator Widget",
      "name": "main_window",
      "width": 500,
      "height": 500
    },
    "image": { 
      "src": "Images/Sun.png",
      "hOffset": 250,
      "vOffset": 250,
      "alignment": "center"
    },
    "text": {
      "data": "Click Here",
      "size": 36,
      "style": "bold",
      "vOffset": 100,
      "alignment": "center",
      "onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
    }
  }
}    

Each operation was rotated though one of the following search paths:

widget.window.name
widget.image.hOffset
widget.text.onMouseUp

These benchmarks were run on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7.

Contact

Josh Baker @tidwall

License

SJSON source code is available under the MIT License.

Documentation

Overview

Package sjson provides setting json values.

Index

• func Delete(json, path string) (string, error)
• func DeleteBytes(json []byte, path string) ([]byte, error)
• func Set(json, path string, value interface{}) (string, error)
• func SetBytes(json []byte, path string, value interface{}) ([]byte, error)
• func SetBytesOptions(json []byte, path string, value interface{}, opts *Options) ([]byte, error)
• func SetOptions(json, path string, value interface{}, opts *Options) (string, error)
• func SetRaw(json, path, value string) (string, error)
• func SetRawBytes(json []byte, path string, value []byte) ([]byte, error)
• func SetRawBytesOptions(json []byte, path string, value []byte, opts *Options) ([]byte, error)
• func SetRawOptions(json, path, value string, opts *Options) (string, error)
• type Options

Functions

func Delete

func Delete(json, path string) (string, error)

Delete deletes a value from json for the specified path.

func DeleteBytes

func DeleteBytes(json []byte, path string) ([]byte, error)

DeleteBytes deletes a value from json for the specified path.

func Set

func Set(json, path string, value interface{}) (string, error)

Set sets a json value for the specified path. A path is in dot syntax, such as "name.last" or "age". This function expects that the json is well-formed, and does not validate. Invalid json will not panic, but it may return back unexpected results. An error is returned if the path is not valid.

A path is a series of keys separated by a dot.

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "friends": [
    {"first": "James", "last": "Murphy"},
    {"first": "Roger", "last": "Craig"}
  ]
}
"name.last"          >> "Anderson"
"age"                >> 37
"children.1"         >> "Alex"

func SetBytes

func SetBytes(json []byte, path string, value interface{}) ([]byte, error)

SetBytes sets a json value for the specified path. If working with bytes, this method preferred over Set(string(data), path, value)

func SetBytesOptions

func SetBytesOptions(json []byte, path string, value interface{},
	opts *Options) ([]byte, error)

SetBytesOptions sets a json value for the specified path with options. If working with bytes, this method preferred over SetOptions(string(data), path, value)

func SetOptions

func SetOptions(json, path string, value interface{},
	opts *Options) (string, error)

SetOptions sets a json value for the specified path with options. A path is in dot syntax, such as "name.last" or "age". This function expects that the json is well-formed, and does not validate. Invalid json will not panic, but it may return back unexpected results. An error is returned if the path is not valid.

func SetRaw

func SetRaw(json, path, value string) (string, error)

SetRaw sets a raw json value for the specified path. This function works the same as Set except that the value is set as a raw block of json. This allows for setting premarshalled json objects.

func SetRawBytes

func SetRawBytes(json []byte, path string, value []byte) ([]byte, error)

SetRawBytes sets a raw json value for the specified path. If working with bytes, this method preferred over SetRaw(string(data), path, value)

func SetRawBytesOptions

func SetRawBytesOptions(json []byte, path string, value []byte,
	opts *Options) ([]byte, error)

SetRawBytesOptions sets a raw json value for the specified path with options. If working with bytes, this method preferred over SetRawOptions(string(data), path, value, opts)

func SetRawOptions

func SetRawOptions(json, path, value string, opts *Options) (string, error)

SetRawOptions sets a raw json value for the specified path with options. This furnction works the same as SetOptions except that the value is set as a raw block of json. This allows for setting premarshalled json objects.

Types

type Options

type Options struct {
	// Optimistic is a hint that the value likely exists which
	// allows for the sjson to perform a fast-track search and replace.
	Optimistic bool
	// ReplaceInPlace is a hint to replace the input json rather than
	// allocate a new json byte slice. When this field is specified
	// the input json will not longer be valid and it should not be used
	// In the case when the destination slice doesn't have enough free
	// bytes to replace the data in place, a new bytes slice will be
	// created under the hood.
	// The Optimistic flag must be set to true and the input must be a
	// byte slice in order to use this field.
	ReplaceInPlace bool
}

Options represents additional options for the Set and Delete functions.