Documentation
¶
Overview ¶
package fastjson provides fast JSON parsing.
Arbitrary JSON may be parsed by fastjson without the need for creating structs or for generating go code. Just parse JSON and get the required fields with Get* functions.
Index ¶
- func Exists(data []byte, keys ...string) bool
- func GetBool(data []byte, keys ...string) bool
- func GetBytes(data []byte, keys ...string) []byte
- func GetFloat64(data []byte, keys ...string) float64
- func GetInt(data []byte, keys ...string) int
- func GetString(data []byte, keys ...string) string
- func ParseBestEffort(s string) float64
- func ParseInt64BestEffort(s string) int64
- func ParseUint64BestEffort(s string) uint64
- type Arena
- func (a *Arena) NewArray() *Value
- func (a *Arena) NewFalse() *Value
- func (a *Arena) NewNull() *Value
- func (a *Arena) NewNumberFloat64(f float64) *Value
- func (a *Arena) NewNumberInt(n int) *Value
- func (a *Arena) NewNumberString(s string) *Value
- func (a *Arena) NewObject() *Value
- func (a *Arena) NewString(s string) *Value
- func (a *Arena) NewStringBytes(b []byte) *Value
- func (a *Arena) NewTrue() *Value
- func (a *Arena) Reset()
- type ArenaPool
- type Object
- type Parser
- type ParserPool
- type Type
- type Value
- func (v *Value) Array() ([]*Value, error)
- func (v *Value) Bool() (bool, error)
- func (v *Value) Del(key string)
- func (v *Value) Exists(keys ...string) bool
- func (v *Value) Float64() (float64, error)
- func (v *Value) Get(keys ...string) *Value
- func (v *Value) GetArray(keys ...string) []*Value
- func (v *Value) GetBool(keys ...string) bool
- func (v *Value) GetFloat64(keys ...string) float64
- func (v *Value) GetInt(keys ...string) int
- func (v *Value) GetInt64(keys ...string) int64
- func (v *Value) GetObject(keys ...string) *Object
- func (v *Value) GetString(key string) string
- func (v *Value) GetStringBytes(keys ...string) []byte
- func (v *Value) GetUint(keys ...string) uint
- func (v *Value) GetUint64(keys ...string) uint64
- func (v *Value) Int() (int, error)
- func (v *Value) Int64() (int64, error)
- func (v *Value) MarshalTo(dst []byte) []byte
- func (v *Value) Object() (*Object, error)
- func (v *Value) Set(key string, value *Value)
- func (v *Value) SetArrayItem(idx int, value *Value)
- func (v *Value) String() string
- func (v *Value) StringBytes() ([]byte, error)
- func (v *Value) Type() Type
- func (v *Value) Uint() (uint, error)
- func (v *Value) Uint64() (uint64, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Exists ¶
Exists returns true if the field identified by keys path exists in JSON data.
Array indexes may be represented as decimal numbers in keys.
False is returned on error. Use Parser for proper error handling.
Parser is faster when multiple fields must be checked in the JSON.
Example ¶
data := []byte(`{"foo": [1.23,{"bar":33,"baz":null}]}`) fmt.Printf("exists(data.foo) = %v\n", Exists(data, "foo")) fmt.Printf("exists(data.foo[0]) = %v\n", Exists(data, "foo", "0")) fmt.Printf("exists(data.foo[1].baz) = %v\n", Exists(data, "foo", "1", "baz")) fmt.Printf("exists(data.foobar) = %v\n", Exists(data, "foobar")) fmt.Printf("exists(data.foo.bar) = %v\n", Exists(data, "foo", "bar"))
Output: exists(data.foo) = true exists(data.foo[0]) = true exists(data.foo[1].baz) = true exists(data.foobar) = false exists(data.foo.bar) = false
func GetBool ¶
GetBool returns boolean value for the field identified by keys path in JSON data.
Array indexes may be represented as decimal numbers in keys.
False is returned on error. Use Parser for proper error handling.
Parser is faster for obtaining multiple fields from JSON.
func GetBytes ¶
GetBytes returns string value for the field identified by keys path in JSON data.
Array indexes may be represented as decimal numbers in keys.
nil is returned on error. Use Parser for proper error handling.
Parser is faster for obtaining multiple fields from JSON.
func GetFloat64 ¶
GetFloat64 returns float64 value for the field identified by keys path in JSON data.
Array indexes may be represented as decimal numbers in keys.
0 is returned on error. Use Parser for proper error handling.
Parser is faster for obtaining multiple fields from JSON.
func GetInt ¶
GetInt returns int value for the field identified by keys path in JSON data.
Array indexes may be represented as decimal numbers in keys.
0 is returned on error. Use Parser for proper error handling.
Parser is faster for obtaining multiple fields from JSON.
Example ¶
data := []byte(`{"foo": [233,true, {"bar": [2343]} ]}`) n1 := GetInt(data, "foo", "0") fmt.Printf("data.foo[0] = %d\n", n1) n2 := GetInt(data, "foo", "2", "bar", "0") fmt.Printf("data.foo[2].bar[0] = %d\n", n2)
Output: data.foo[0] = 233 data.foo[2].bar[0] = 2343
func GetString ¶
GetString returns string value for the field identified by keys path in JSON data.
Array indexes may be represented as decimal numbers in keys.
An empty string is returned on error. Use Parser for proper error handling.
Parser is faster for obtaining multiple fields from JSON.
Example ¶
data := []byte(`{"foo":{"bar":[123,"baz"]}}`) s := GetString(data, "foo", "bar", "1") fmt.Printf("data.foo.bar[1] = %s", s)
Output: data.foo.bar[1] = baz
func ParseBestEffort ¶
ParseBestEffort parses floating-point number s.
It is equivalent to strconv.ParseFloat(s, 64), but is faster.
0 is returned if the number cannot be parsed.
func ParseInt64BestEffort ¶
ParseInt64BestEffort parses int64 number s.
It is equivalent to strconv.ParseInt(s, 10, 64), but is faster.
0 is returned if the number cannot be parsed.
func ParseUint64BestEffort ¶
ParseUint64BestEffort parses uint64 number s.
It is equivalent to strconv.ParseUint(s, 10, 64), but is faster.
0 is returned if the number cannot be parsed.
Types ¶
type Arena ¶
type Arena struct {
// contains filtered or unexported fields
}
Arena may be used for fast creation and re-use of Values.
Typical Arena lifecycle:
- Construct Values via the Arena and Value.Set* calls.
- Marshal the constructed Values with Value.MarshalTo call.
- Reset all the constructed Values at once by Arena.Reset call.
- Go to 1 and re-use the Arena.
It is unsafe calling Arena methods from concurrent goroutines. Use per-goroutine Arenas or ArenaPool instead.
func (*Arena) NewArray ¶
NewArray returns new empty array value.
New entries may be added to the returned array via Set* calls.
The returned array is valid until Reset is called on a.
func (*Arena) NewNumberFloat64 ¶
NewNumberFloat64 returns new number value containing f.
The returned number is valid until Reset is called on a.
func (*Arena) NewNumberInt ¶
NewNumberInt returns new number value containing n.
The returned number is valid until Reset is called on a.
func (*Arena) NewNumberString ¶
NewNumberString returns new number value containing s.
The returned number is valid until Reset is called on a.
func (*Arena) NewObject ¶
NewObject returns new empty object value.
New entries may be added to the returned object via Set call.
The returned object is valid until Reset is called on a.
func (*Arena) NewString ¶
NewString returns new string value containing s.
The returned string is valid until Reset is called on a.
func (*Arena) NewStringBytes ¶
NewStringBytes returns new string value containing b.
The returned string is valid until Reset is called on a.
type ArenaPool ¶
type ArenaPool struct {
// contains filtered or unexported fields
}
ArenaPool may be used for pooling Arenas for similarly typed JSONs.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object represents JSON object.
Object cannot be used from concurrent goroutines. Use per-goroutine parsers or ParserPool instead.
func (*Object) Del ¶
Del deletes the entry with the given key from o.
Example ¶
package main import ( "fmt" "github.com/mymmsc/gox/fastjson" "log" ) func main() { v := fastjson.MustParse(`{"foo": 123, "bar": [1,2], "baz": "xyz"}`) o, err := v.Object() if err != nil { log.Fatalf("cannot otain object: %s", err) } fmt.Printf("%s\n", o) o.Del("bar") fmt.Printf("%s\n", o) o.Del("foo") fmt.Printf("%s\n", o) o.Del("baz") fmt.Printf("%s\n", o) }
Output: {"foo":123,"bar":[1,2],"baz":"xyz"} {"foo":123,"baz":"xyz"} {"baz":"xyz"} {}
func (*Object) Get ¶
Get returns the value for the given key in the o.
Returns nil if the value for the given key isn't found.
The returned value is valid until Parse is called on the Parser returned o.
func (*Object) Set ¶
Set sets (key, value) entry in the o.
The value must be unchanged during o lifetime.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser parses JSON.
Parser may be re-used for subsequent parsing.
Parser cannot be used from concurrent goroutines. Use per-goroutine parsers or ParserPool instead.
type ParserPool ¶
type ParserPool struct {
// contains filtered or unexported fields
}
ParserPool may be used for pooling Parsers for similarly typed JSONs.
func (*ParserPool) Get ¶
func (pp *ParserPool) Get() *Parser
Get returns a Parser from pp.
The Parser must be Put to pp after use.
func (*ParserPool) Put ¶
func (pp *ParserPool) Put(p *Parser)
Put returns p to pp.
p and objects recursively returned from p cannot be used after p is put into pp.
type Type ¶
type Type int
Type represents JSON type.
const ( // TypeNull is JSON null. TypeNull Type = 0 // TypeObject is JSON object type. TypeObject Type = 1 // TypeArray is JSON array type. TypeArray Type = 2 // TypeString is JSON string type. TypeString Type = 3 // TypeNumber is JSON number type. TypeNumber Type = 4 // TypeTrue is JSON true. TypeTrue Type = 5 // TypeFalse is JSON false. TypeFalse Type = 6 )
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value represents any JSON value.
Call Type in order to determine the actual type of the JSON value.
Value cannot be used from concurrent goroutines. Use per-goroutine parsers or ParserPool instead.
func MustParse ¶
MustParse parses fastjson string s.
The function panics if s cannot be parsed. The function is slower than the Parser.Parse for re-used Parser.
func MustParseBytes ¶
MustParseBytes parses b containing fastjson.
The function banics if b cannot be parsed. The function is slower than the Parser.ParseBytes for re-used Parser.
func Parse ¶
Parse parses fastjson string s.
The function is slower than the Parser.Parse for re-used Parser.
func ParseBytes ¶
ParseBytes parses b containing fastjson.
The function is slower than the Parser.ParseBytes for re-used Parser.
func (*Value) Array ¶
Array returns the underlying JSON array for the v.
The returned array is valid until Parse is called on the Parser returned v.
Use GetArray if you don't need error handling.
func (*Value) Bool ¶
Bool returns the underlying JSON bool for the v.
Use GetBool if you don't need error handling.
func (*Value) Del ¶
Del deletes the entry with the given key from array or object v.
Example ¶
package main import ( "fmt" "github.com/mymmsc/gox/fastjson" ) func main() { v := fastjson.MustParse(`{"foo": 123, "bar": [1,2], "baz": "xyz"}`) fmt.Printf("%s\n", v) v.Del("foo") fmt.Printf("%s\n", v) v.Get("bar").Del("0") fmt.Printf("%s\n", v) }
Output: {"foo":123,"bar":[1,2],"baz":"xyz"} {"bar":[1,2],"baz":"xyz"} {"bar":[2],"baz":"xyz"}
func (*Value) Exists ¶
Exists returns true if the field exists for the given keys path.
Array indexes may be represented as decimal numbers in keys.
func (*Value) Float64 ¶
Float64 returns the underlying JSON number for the v.
Use GetFloat64 if you don't need error handling.
func (*Value) Get ¶
Get returns value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
nil is returned for non-existing keys path.
The returned value is valid until Parse is called on the Parser returned v.
func (*Value) GetArray ¶
GetArray returns array value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
nil is returned for non-existing keys path or for invalid value type.
The returned array is valid until Parse is called on the Parser returned v.
func (*Value) GetBool ¶
GetBool returns bool value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
false is returned for non-existing keys path or for invalid value type.
func (*Value) GetFloat64 ¶
GetFloat64 returns float64 value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
0 is returned for non-existing keys path or for invalid value type.
func (*Value) GetInt ¶
GetInt returns int value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
0 is returned for non-existing keys path or for invalid value type.
func (*Value) GetInt64 ¶
GetInt64 returns int64 value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
0 is returned for non-existing keys path or for invalid value type.
func (*Value) GetObject ¶
GetObject returns object value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
nil is returned for non-existing keys path or for invalid value type.
The returned object is valid until Parse is called on the Parser returned v.
func (*Value) GetStringBytes ¶
GetStringBytes returns string value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
nil is returned for non-existing keys path or for invalid value type.
The returned string is valid until Parse is called on the Parser returned v.
func (*Value) GetUint ¶
GetUint returns uint value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
0 is returned for non-existing keys path or for invalid value type.
func (*Value) GetUint64 ¶
GetUint64 returns uint64 value by the given keys path.
Array indexes may be represented as decimal numbers in keys.
0 is returned for non-existing keys path or for invalid value type.
func (*Value) Int ¶
Int returns the underlying JSON int for the v.
Use GetInt if you don't need error handling.
func (*Value) Int64 ¶
Int64 returns the underlying JSON int64 for the v.
Use GetInt64 if you don't need error handling.
func (*Value) Object ¶
Object returns the underlying JSON object for the v.
The returned object is valid until Parse is called on the Parser returned v.
Use GetObject if you don't need error handling.
func (*Value) Set ¶
Set sets (key, value) entry in the array or object v.
The value must be unchanged during v lifetime.
Example ¶
package main import ( "fmt" "github.com/mymmsc/gox/fastjson" ) func main() { v := fastjson.MustParse(`{"foo":1,"bar":[2,3]}`) // Replace `foo` value with "xyz" v.Set("foo", fastjson.MustParse(`"xyz"`)) // Add "newv":123 v.Set("newv", fastjson.MustParse(`123`)) fmt.Printf("%s\n", v) // Replace `bar.1` with {"x":"y"} v.Get("bar").Set("1", fastjson.MustParse(`{"x":"y"}`)) // Add `bar.3="qwe" v.Get("bar").Set("3", fastjson.MustParse(`"qwe"`)) fmt.Printf("%s\n", v) }
Output: {"foo":"xyz","bar":[2,3],"newv":123} {"foo":"xyz","bar":[2,{"x":"y"},null,"qwe"],"newv":123}
func (*Value) SetArrayItem ¶
SetArrayItem sets the value in the array v at idx position.
The value must be unchanged during v lifetime.
func (*Value) String ¶
String returns string representation of the v.
The function is for debugging purposes only. It isn't optimized for speed. See MarshalTo instead.
Don't confuse this function with StringBytes, which must be called for obtaining the underlying JSON string for the v.
func (*Value) StringBytes ¶
StringBytes returns the underlying JSON string for the v.
The returned string is valid until Parse is called on the Parser returned v.
Use GetStringBytes if you don't need error handling.