Documentation ¶
Overview ¶
Example (CustomMarshalJSON) ¶
package main import ( "encoding/json" "fmt" "log" "strings" ) type Animal int const ( Unknown Animal = iota Gopher Zebra ) func (a *Animal) UnmarshalJSON(b []byte) error { var s string if err := json.Unmarshal(b, &s); err != nil { return err } switch strings.ToLower(s) { default: *a = Unknown case "gopher": *a = Gopher case "zebra": *a = Zebra } return nil } func (a Animal) MarshalJSON() ([]byte, error) { var s string switch a { default: s = "unknown" case Gopher: s = "gopher" case Zebra: s = "zebra" } return json.Marshal(s) } func main() { blob := `["gopher","armadillo","zebra","unknown","gopher","bee","gopher","zebra"]` var zoo []Animal if err := json.Unmarshal([]byte(blob), &zoo); err != nil { log.Fatal(err) } census := make(map[Animal]int) for _, animal := range zoo { census[animal] += 1 } fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras: %d\n* Unknown: %d\n", census[Gopher], census[Zebra], census[Unknown]) }
Output: Zoo Census: * Gophers: 3 * Zebras: 2 * Unknown: 3
Index ¶
- func Append(b []byte, x interface{}, flags AppendFlags) ([]byte, error)
- func AppendEscape(b []byte, s string, flags AppendFlags) []byte
- func AppendUnescape(b []byte, s []byte, flags ParseFlags) []byte
- func Compact(dst *bytes.Buffer, src []byte) error
- func Escape(s string) []byte
- func HTMLEscape(dst *bytes.Buffer, src []byte)
- func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
- func Marshal(x interface{}) ([]byte, error)
- func MarshalIndent(x interface{}, prefix, indent string) ([]byte, error)
- func Parse(b []byte, x interface{}, flags ParseFlags) ([]byte, error)
- func Unescape(s []byte) []byte
- func Unmarshal(b []byte, x interface{}) error
- func Valid(data []byte) bool
- type AppendFlags
- type Decoder
- func (dec *Decoder) Buffered() io.Reader
- func (dec *Decoder) Decode(v interface{}) error
- func (dec *Decoder) DisallowUnknownFields()
- func (dec *Decoder) DontCopyNumber()
- func (dec *Decoder) DontCopyRawMessage()
- func (dec *Decoder) DontCopyString()
- func (dec *Decoder) DontMatchCaseInsensitiveStructFields()
- func (dec *Decoder) InputOffset() int64
- func (dec *Decoder) UseNumber()
- func (dec *Decoder) ZeroCopy()
- type Delim
- type Encoder
- type InvalidUTF8Error
- type InvalidUnmarshalError
- type Kind
- type Marshaler
- type MarshalerError
- type Number
- type ParseFlags
- type RawMessage
- type RawValue
- type SyntaxError
- type Token
- type Tokenizer
- func (t *Tokenizer) Bool() bool
- func (t *Tokenizer) Float() float64
- func (t *Tokenizer) Int() int64
- func (t *Tokenizer) Kind() Kind
- func (t *Tokenizer) Next() bool
- func (t *Tokenizer) Remaining() int
- func (t *Tokenizer) Reset(b []byte)
- func (t *Tokenizer) String() []byte
- func (t *Tokenizer) Uint() uint64
- type UnmarshalFieldError
- type UnmarshalTypeError
- type Unmarshaler
- type UnsupportedTypeError
- type UnsupportedValueError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
func Append(b []byte, x interface{}, flags AppendFlags) ([]byte, error)
Append acts like Marshal but appends the json representation to b instead of always reallocating a new slice.
func AppendEscape ¶ added in v0.2.6
func AppendEscape(b []byte, s string, flags AppendFlags) []byte
AppendEscape appends s to b with the string escaped as a JSON value. This will include the starting and ending quote characters, and the appropriate characters will be escaped correctly for JSON encoding.
func AppendUnescape ¶ added in v0.2.8
func AppendUnescape(b []byte, s []byte, flags ParseFlags) []byte
AppendUnescape appends s to b with the string unescaped as a JSON value. This will remove starting and ending quote characters, and the appropriate characters will be escaped correctly as if JSON decoded. New space will be reallocated if more space is needed.
func Compact ¶
Compact is documented at https://golang.org/pkg/encoding/json/#Compact
func Escape ¶ added in v0.2.6
Escape is a convenience helper to construct an escaped JSON string from s. The function escales HTML characters, for more control over the escape behavior and to write to a pre-allocated buffer, use AppendEscape.
func HTMLEscape ¶
HTMLEscape is documented at https://golang.org/pkg/encoding/json/#HTMLEscape
Example ¶
package main import ( "bytes" "encoding/json" "os" ) func main() { var out bytes.Buffer json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`)) out.WriteTo(os.Stdout) }
Output: {"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}
func Indent ¶
Indent is documented at https://golang.org/pkg/encoding/json/#Indent
Example ¶
package main import ( "bytes" "encoding/json" "log" "os" ) func main() { type Road struct { Name string Number int } roads := []Road{ {"Diamond Fork", 29}, {"Sheep Creek", 51}, } b, err := json.Marshal(roads) if err != nil { log.Fatal(err) } var out bytes.Buffer json.Indent(&out, b, "=", "\t") out.WriteTo(os.Stdout) }
Output: [ = { = "Name": "Diamond Fork", = "Number": 29 = }, = { = "Name": "Sheep Creek", = "Number": 51 = } =]
func Marshal ¶
Marshal is documented at https://golang.org/pkg/encoding/json/#Marshal
Example ¶
package main import ( "encoding/json" "fmt" "os" ) func main() { type ColorGroup struct { ID int Name string Colors []string } group := ColorGroup{ ID: 1, Name: "Reds", Colors: []string{"Crimson", "Red", "Ruby", "Maroon"}, } b, err := json.Marshal(group) if err != nil { fmt.Println("error:", err) } os.Stdout.Write(b) }
Output: {"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}
func MarshalIndent ¶
MarshalIndent is documented at https://golang.org/pkg/encoding/json/#MarshalIndent
Example ¶
package main import ( "encoding/json" "fmt" "log" ) func main() { data := map[string]int{ "a": 1, "b": 2, } json, err := json.MarshalIndent(data, "<prefix>", "<indent>") if err != nil { log.Fatal(err) } fmt.Println(string(json)) }
Output: { <prefix><indent>"a": 1, <prefix><indent>"b": 2 <prefix>}
func Parse ¶
func Parse(b []byte, x interface{}, flags ParseFlags) ([]byte, error)
Parse behaves like Unmarshal but the caller can pass a set of flags to configure the parsing behavior.
func Unescape ¶ added in v0.2.8
Unescape is a convenience helper to unescape a JSON value. For more control over the unescape behavior and to write to a pre-allocated buffer, use AppendUnescape.
func Unmarshal ¶
Unmarshal is documented at https://golang.org/pkg/encoding/json/#Unmarshal
Example ¶
package main import ( "encoding/json" "fmt" ) func main() { var jsonBlob = []byte(`[ {"Name": "Platypus", "Order": "Monotremata"}, {"Name": "Quoll", "Order": "Dasyuromorphia"} ]`) type Animal struct { Name string Order string } var animals []Animal err := json.Unmarshal(jsonBlob, &animals) if err != nil { fmt.Println("error:", err) } fmt.Printf("%+v", animals) }
Output: [{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
func Valid ¶
Valid is documented at https://golang.org/pkg/encoding/json/#Valid
Example ¶
package main import ( "encoding/json" "fmt" ) func main() { goodJSON := `{"example": 1}` badJSON := `{"example":2:]}}` fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON))) }
Output: true false
Types ¶
type AppendFlags ¶
type AppendFlags uint32
AppendFlags is a type used to represent configuration options that can be applied when formatting json output.
const ( // EscapeHTML is a formatting flag used to to escape HTML in json strings. EscapeHTML AppendFlags = 1 << iota // SortMapKeys is formatting flag used to enable sorting of map keys when // encoding JSON (this matches the behavior of the standard encoding/json // package). SortMapKeys // TrustRawMessage is a performance optimization flag to skip value // checking of raw messages. It should only be used if the values are // known to be valid json (e.g., they were created by json.Unmarshal). TrustRawMessage )
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder is documented at https://golang.org/pkg/encoding/json/#Decoder
Example ¶
This example uses a Decoder to decode a stream of distinct JSON values.
package main import ( "encoding/json" "fmt" "io" "log" "strings" ) func main() { const jsonStream = ` {"Name": "Ed", "Text": "Knock knock."} {"Name": "Sam", "Text": "Who's there?"} {"Name": "Ed", "Text": "Go fmt."} {"Name": "Sam", "Text": "Go fmt who?"} {"Name": "Ed", "Text": "Go fmt yourself!"} ` type Message struct { Name, Text string } dec := json.NewDecoder(strings.NewReader(jsonStream)) for { var m Message if err := dec.Decode(&m); err == io.EOF { break } else if err != nil { log.Fatal(err) } fmt.Printf("%s: %s\n", m.Name, m.Text) } }
Output: Ed: Knock knock. Sam: Who's there? Ed: Go fmt. Sam: Go fmt who? Ed: Go fmt yourself!
func NewDecoder ¶
NewDecoder is documented at https://golang.org/pkg/encoding/json/#NewDecoder
func (*Decoder) Buffered ¶
Buffered is documented at https://golang.org/pkg/encoding/json/#Decoder.Buffered
func (*Decoder) Decode ¶
Decode is documented at https://golang.org/pkg/encoding/json/#Decoder.Decode
Example (Stream) ¶
This example uses a Decoder to decode a streaming array of JSON objects.
package main import ( "encoding/json" "fmt" "log" "strings" ) func main() { const jsonStream = ` [ {"Name": "Ed", "Text": "Knock knock."}, {"Name": "Sam", "Text": "Who's there?"}, {"Name": "Ed", "Text": "Go fmt."}, {"Name": "Sam", "Text": "Go fmt who?"}, {"Name": "Ed", "Text": "Go fmt yourself!"} ] ` type Message struct { Name, Text string } dec := json.NewDecoder(strings.NewReader(jsonStream)) // read open bracket t, err := dec.Token() if err != nil { log.Fatal(err) } fmt.Printf("%T: %v\n", t, t) // while the array contains values for dec.More() { var m Message // decode an array value (Message) err := dec.Decode(&m) if err != nil { log.Fatal(err) } fmt.Printf("%v: %v\n", m.Name, m.Text) } // read closing bracket t, err = dec.Token() if err != nil { log.Fatal(err) } fmt.Printf("%T: %v\n", t, t) }
Output: json.Delim: [ Ed: Knock knock. Sam: Who's there? Ed: Go fmt. Sam: Go fmt who? Ed: Go fmt yourself! json.Delim: ]
func (*Decoder) DisallowUnknownFields ¶
func (dec *Decoder) DisallowUnknownFields()
DisallowUnknownFields is documented at https://golang.org/pkg/encoding/json/#Decoder.DisallowUnknownFields
func (*Decoder) DontCopyNumber ¶
func (dec *Decoder) DontCopyNumber()
DontCopyNumber is an extension to the standard encoding/json package which instructs the decoder to not copy numbers loaded from the json payloads.
func (*Decoder) DontCopyRawMessage ¶
func (dec *Decoder) DontCopyRawMessage()
DontCopyRawMessage is an extension to the standard encoding/json package which instructs the decoder to not allocate RawMessage values in separate memory buffers (see the documentation of the DontcopyRawMessage flag for more detais).
func (*Decoder) DontCopyString ¶
func (dec *Decoder) DontCopyString()
DontCopyString is an extension to the standard encoding/json package which instructs the decoder to not copy strings loaded from the json payloads when possible.
func (*Decoder) DontMatchCaseInsensitiveStructFields ¶
func (dec *Decoder) DontMatchCaseInsensitiveStructFields()
DontMatchCaseInsensitiveStructFields is an extension to the standard encoding/json package which instructs the decoder to not match object fields against struct fields in a case-insensitive way, the field names have to match exactly to be decoded into the struct field values.
func (*Decoder) InputOffset ¶ added in v0.1.11
InputOffset returns the input stream byte offset of the current decoder position. The offset gives the location of the end of the most recently returned token and the beginning of the next token.
func (*Decoder) UseNumber ¶
func (dec *Decoder) UseNumber()
UseNumber is documented at https://golang.org/pkg/encoding/json/#Decoder.UseNumber
type Delim ¶
Delim is documented at https://golang.org/pkg/encoding/json/#Delim
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder is documented at https://golang.org/pkg/encoding/json/#Encoder
func NewEncoder ¶
NewEncoder is documented at https://golang.org/pkg/encoding/json/#NewEncoder
func (*Encoder) Encode ¶
Encode is documented at https://golang.org/pkg/encoding/json/#Encoder.Encode
func (*Encoder) SetAppendNewline ¶ added in v0.3.4
SetAppendNewline is an extension to the standard encoding/json package which allows the program to toggle the addition of a newline in Encode on or off.
func (*Encoder) SetEscapeHTML ¶
SetEscapeHTML is documented at https://golang.org/pkg/encoding/json/#Encoder.SetEscapeHTML
func (*Encoder) SetIndent ¶
SetIndent is documented at https://golang.org/pkg/encoding/json/#Encoder.SetIndent
func (*Encoder) SetSortMapKeys ¶
SetSortMapKeys is an extension to the standard encoding/json package which allows the program to toggle sorting of map keys on and off.
func (*Encoder) SetTrustRawMessage ¶ added in v0.1.12
SetTrustRawMessage skips value checking when encoding a raw json message. It should only be used if the values are known to be valid json, e.g. because they were originally created by json.Unmarshal.
type InvalidUTF8Error ¶
type InvalidUTF8Error = json.InvalidUTF8Error
InvalidUTF8Error is documented at https://golang.org/pkg/encoding/json/#InvalidUTF8Error
type InvalidUnmarshalError ¶
type InvalidUnmarshalError = json.InvalidUnmarshalError
InvalidUnmarshalError is documented at https://golang.org/pkg/encoding/json/#InvalidUnmarshalError
type Kind ¶ added in v0.2.12
type Kind uint
Kind represents the different kinds of value that exist in JSON.
const ( Undefined Kind = 0 Null Kind = 1 // Null is not zero, so we keep zero for "undefined". Bool Kind = 2 // Bit two is set to 1, means it's a boolean. False Kind = 2 // Bool + 0 True Kind = 3 // Bool + 1 Num Kind = 4 // Bit three is set to 1, means it's a number. Uint Kind = 5 // Num + 1 Int Kind = 6 // Num + 2 Float Kind = 7 // Num + 3 String Kind = 8 // Bit four is set to 1, means it's a string. Unescaped Kind = 9 // String + 1 Array Kind = 16 // Equivalent to Delim == '[' Object Kind = 32 // Equivalent to Delim == '{' )
type Marshaler ¶
Marshaler is documented at https://golang.org/pkg/encoding/json/#Marshaler
type MarshalerError ¶
type MarshalerError = json.MarshalerError
MarshalerError is documented at https://golang.org/pkg/encoding/json/#MarshalerError
type Number ¶
Number is documented at https://golang.org/pkg/encoding/json/#Number
type ParseFlags ¶
type ParseFlags uint32
ParseFlags is a type used to represent configuration options that can be applied when parsing json input.
const ( // DisallowUnknownFields is a parsing flag used to prevent decoding of // objects to Go struct values when a field of the input does not match // with any of the struct fields. DisallowUnknownFields ParseFlags = 1 << iota // UseNumber is a parsing flag used to load numeric values as Number // instead of float64. UseNumber // DontCopyString is a parsing flag used to provide zero-copy support when // loading string values from a json payload. It is not always possible to // avoid dynamic memory allocations, for example when a string is escaped in // the json data a new buffer has to be allocated, but when the `wire` value // can be used as content of a Go value the decoder will simply point into // the input buffer. DontCopyString // DontCopyNumber is a parsing flag used to provide zero-copy support when // loading Number values (see DontCopyString and DontCopyRawMessage). DontCopyNumber // DontCopyRawMessage is a parsing flag used to provide zero-copy support // when loading RawMessage values from a json payload. When used, the // RawMessage values will not be allocated into new memory buffers and // will instead point directly to the area of the input buffer where the // value was found. DontCopyRawMessage // DontMatchCaseInsensitiveStructFields is a parsing flag used to prevent // matching fields in a case-insensitive way. This can prevent degrading // performance on case conversions, and can also act as a stricter decoding // mode. DontMatchCaseInsensitiveStructFields // Decode integers into *big.Int. // Takes precedence over UseNumber for integers. UseBigInt // Decode in-range integers to int64. // Takes precedence over UseNumber and UseBigInt for in-range integers. UseInt64 // Decode in-range positive integers to uint64. // Takes precedence over UseNumber, UseBigInt, and UseInt64 // for positive, in-range integers. UseUint64 // ZeroCopy is a parsing flag that combines all the copy optimizations // available in the package. // // The zero-copy optimizations are better used in request-handler style // code where none of the values are retained after the handler returns. ZeroCopy = DontCopyString | DontCopyNumber | DontCopyRawMessage )
type RawMessage ¶
type RawMessage = json.RawMessage
RawMessage is documented at https://golang.org/pkg/encoding/json/#RawMessage
Example (Marshal) ¶
This example uses RawMessage to use a precomputed JSON during marshal.
package main import ( "encoding/json" "fmt" "os" ) func main() { h := json.RawMessage(`{"precomputed": true}`) c := struct { Header *json.RawMessage `json:"header"` Body string `json:"body"` }{Header: &h, Body: "Hello Gophers!"} b, err := json.MarshalIndent(&c, "", "\t") if err != nil { fmt.Println("error:", err) } os.Stdout.Write(b) }
Output: { "header": { "precomputed": true }, "body": "Hello Gophers!" }
Example (Unmarshal) ¶
This example uses RawMessage to delay parsing part of a JSON message.
package main import ( "encoding/json" "fmt" "log" ) func main() { type Color struct { Space string Point json.RawMessage // delay parsing until we know the color space } type RGB struct { R uint8 G uint8 B uint8 } type YCbCr struct { Y uint8 Cb int8 Cr int8 } var j = []byte(`[ {"Space": "YCbCr", "Point": {"Y": 255, "Cb": 0, "Cr": -10}}, {"Space": "RGB", "Point": {"R": 98, "G": 218, "B": 255}} ]`) var colors []Color err := json.Unmarshal(j, &colors) if err != nil { log.Fatalln("error:", err) } for _, c := range colors { var dst interface{} switch c.Space { case "RGB": dst = new(RGB) case "YCbCr": dst = new(YCbCr) } err := json.Unmarshal(c.Point, dst) if err != nil { log.Fatalln("error:", err) } fmt.Println(c.Space, dst) } }
Output: YCbCr &{255 0 -10} RGB &{98 218 255}
type RawValue ¶
type RawValue []byte
RawValue represents a raw json value, it is intended to carry null, true, false, number, and string values only.
func (RawValue) AppendUnquote ¶
AppendUnquote writes the unquoted version of the string value in v into b.
type SyntaxError ¶
type SyntaxError = json.SyntaxError
A SyntaxError is a description of a JSON syntax error.
type Token ¶
Token is documented at https://golang.org/pkg/encoding/json/#Token
type Tokenizer ¶
type Tokenizer struct { // When the tokenizer is positioned on a json delimiter this field is not // zero. In this case the possible values are '{', '}', '[', ']', ':', and // ','. Delim Delim // This field contains the raw json token that the tokenizer is pointing at. // When Delim is not zero, this field is a single-element byte slice // continaing the delimiter value. Otherwise, this field holds values like // null, true, false, numbers, or quoted strings. Value RawValue // When the tokenizer has encountered invalid content this field is not nil. Err error // When the value is in an array or an object, this field contains the depth // at which it was found. Depth int // When the value is in an array or an object, this field contains the // position at which it was found. Index int // This field is true when the value is the key of an object. IsKey bool // contains filtered or unexported fields }
Tokenizer is an iterator-style type which can be used to progressively parse through a json input.
Tokenizing json is useful to build highly efficient parsing operations, for example when doing tranformations on-the-fly where as the program reads the input and produces the transformed json to an output buffer.
Here is a common pattern to use a tokenizer:
for t := json.NewTokenizer(b); t.Next(); { switch k := t.Kind(); k.Class() { case json.Null: ... case json.Bool: ... case json.Num: ... case json.String: ... case json.Array: ... case json.Object: ... } }
func NewTokenizer ¶
NewTokenizer constructs a new Tokenizer which reads its json input from b.
func (*Tokenizer) Bool ¶ added in v0.2.12
Bool returns a bool containing the value of the json boolean that the tokenizer is currently pointing at.
This method must only be called after checking the kind of the token via a call to Kind.
If the tokenizer is not positioned on a boolean, the behavior is undefined.
func (*Tokenizer) Float ¶ added in v0.2.12
Float returns a byte slice containing the value of the json number that the tokenizer is currently pointing at.
This method must only be called after checking the kind of the token via a call to Kind.
If the tokenizer is not positioned on a number, the behavior is undefined.
func (*Tokenizer) Int ¶ added in v0.2.12
Int returns a byte slice containing the value of the json number that the tokenizer is currently pointing at.
This method must only be called after checking the kind of the token via a call to Kind.
If the tokenizer is not positioned on an integer, the behavior is undefined.
func (*Tokenizer) Kind ¶ added in v0.2.12
Kind returns the kind of the value that the tokenizer is currently positioned on.
func (*Tokenizer) Next ¶
Next returns a new tokenizer pointing at the next token, or the zero-value of Tokenizer if the end of the json input has been reached.
If the tokenizer encounters malformed json while reading the input the method sets t.Err to an error describing the issue, and returns false. Once an error has been encountered, the tokenizer will always fail until its input is cleared by a call to its Reset method.
func (*Tokenizer) Remaining ¶ added in v0.3.6
Remaining returns the number of bytes left to parse.
The position of the tokenizer's current Value within the original byte slice can be calculated like so:
end := len(b) - tok.Remaining() start := end - len(tok.Value)
And slicing b[start:end] will yield the tokenizer's current Value.
func (*Tokenizer) Reset ¶
Reset erases the state of t and re-initializes it with the json input from b.
func (*Tokenizer) String ¶ added in v0.2.12
String returns a byte slice containing the value of the json string that the tokenizer is currently pointing at.
This method must only be called after checking the kind of the token via a call to Kind.
When possible, the returned byte slice references the backing array of the tokenizer. A new slice is only allocated if the tokenizer needed to unescape the json string.
If the tokenizer is not positioned on a string, the behavior is undefined.
func (*Tokenizer) Uint ¶ added in v0.2.12
Uint returns a byte slice containing the value of the json number that the tokenizer is currently pointing at.
This method must only be called after checking the kind of the token via a call to Kind.
If the tokenizer is not positioned on a positive integer, the behavior is undefined.
type UnmarshalFieldError ¶
type UnmarshalFieldError = json.UnmarshalFieldError
UnmarshalFieldError is documented at https://golang.org/pkg/encoding/json/#UnmarshalFieldError
type UnmarshalTypeError ¶
type UnmarshalTypeError = json.UnmarshalTypeError
UnmarshalTypeError is documented at https://golang.org/pkg/encoding/json/#UnmarshalTypeError
type Unmarshaler ¶
type Unmarshaler = json.Unmarshaler
Unmarshaler is documented at https://golang.org/pkg/encoding/json/#Unmarshaler
type UnsupportedTypeError ¶
type UnsupportedTypeError = json.UnsupportedTypeError
UnsupportedTypeError is documented at https://golang.org/pkg/encoding/json/#UnsupportedTypeError
type UnsupportedValueError ¶
type UnsupportedValueError = json.UnsupportedValueError
UnsupportedValueError is documented at https://golang.org/pkg/encoding/json/#UnsupportedValueError