a4005bcf0f | ||
---|---|---|
.travis.yml | ||
LICENSE | ||
README.md | ||
gjson.go | ||
gjson_test.go | ||
logo.png |
README.md
get a json value quickly
GJSON is a Go package the provides a very fast and simple way to get a value from a json document. The reason for this library it to give efficent json indexing for the BuntDB project.
Getting Started
Installing
To start using GJSON, install Go and run go get
:
$ go get -u github.com/tidwall/gjson
This will retrieve the library.
Get a value
Get searches json 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. When the value is found it's returned immediately.
package main
import "github.com/tidwall/gjson"
const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`
func main() {
value := gjson.Get(json, "name.last")
println(value.String())
}
This will print:
Prichard
A path is a series of keys seperated by a dot. A key may contain special wildcard characters '*' and '?'. To access an array value use the index as the key. To get the number of elements in an array use the '#' character.
{
"name": {"first": "Tom", "last": "Anderson"},
"age":37,
"children": ["Sara","Alex","Jack"]
}
"name.last" >> "Anderson"
"age" >> 37
"children.#" >> 3
"children.1" >> "Alex"
"child*.2" >> "Jack"
"c?ildren.0" >> "Sara"
Result Type
GJSON supports the json types string
, number
, bool
, and null
. Arrays and Objects are returned as their raw json types.
The Result
type holds one of these types:
bool, for JSON booleans
float64, for JSON numbers
Number, for JSON numbers
string, for JSON string literals
nil, for JSON null
To get the value call the Value()
method:
result.Value() // interface{} which may be nil, string, float64, or bool
// Or just get the value in one step.
gjson.Get(json, "name.last").Value()
To directly access the value from its original type:
result.Type // can be String, Number, True, False, Null, or JSON
result.Str // holds the string
result.Num // holds the float64 number
result.Raw // holds the raw json
Performance
Benchmarks of GJSON alongside encoding/json, ffjson, and EasyJSON.
BenchmarkGJSONGet-8 3000000 440 ns/op 0 B/op 0 allocs/op
BenchmarkJSONUnmarshalMap-8 600000 10738 ns/op 3176 B/op 69 allocs/op
BenchmarkJSONUnmarshalStruct-8 600000 11635 ns/op 1960 B/op 69 allocs/op
BenchmarkJSONDecoder-8 300000 17193 ns/op 4864 B/op 184 allocs/op
BenchmarkFFJSONLexer-8 1500000 3773 ns/op 1024 B/op 8 allocs/op
BenchmarkEasyJSONLexer-8 3000000 1134 ns/op 741 B/op 6 allocs/op
The JSON document used was:
{
"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 are the results from running the benchmarks on a MacBook Pro 15" 2.8 GHz Intel Core i7:
Contact
Josh Baker @tidwall
License
GJSON source code is available under the MIT License.