...

パッケージ json

import "encoding/json"
概要
目次

概要 ▾

json パッケージは RFC 7159 で定義された JSON のエンコードとデコードを実装します。 JSON と Go の値のマッピングは Marshal と Unmarshal 関数のドキュメントに記述されています。

このパッケージの入門として,"JSON and Go" をご覧ください。 https://golang.org/doc/articles/json_and_go.html

例 (CustomMarshalJSON)

コード:

package json_test

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 Example_customMarshalJSON() {
    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
}

例 (TextMarshalJSON)

コード:

package json_test

import (
    "encoding/json"
    "fmt"
    "log"
    "strings"
)

type Size int

const (
    Unrecognized Size = iota
    Small
    Large
)

func (s *Size) UnmarshalText(text []byte) error {
    switch strings.ToLower(string(text)) {
    default:
        *s = Unrecognized
    case "small":
        *s = Small
    case "large":
        *s = Large
    }
    return nil
}

func (s Size) MarshalText() ([]byte, error) {
    var name string
    switch s {
    default:
        name = "unrecognized"
    case Small:
        name = "small"
    case Large:
        name = "large"
    }
    return []byte(name), nil
}

func Example_textMarshalJSON() {
    blob := `["small","regular","large","unrecognized","small","normal","small","large"]`
    var inventory []Size
    if err := json.Unmarshal([]byte(blob), &inventory); err != nil {
        log.Fatal(err)
    }

    counts := make(map[Size]int)
    for _, size := range inventory {
        counts[size] += 1
    }

    fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
        counts[Small], counts[Large], counts[Unrecognized])

    // Output:
    // Inventory Counts:
    // * Small:        3
    // * Large:        2
    // * Unrecognized: 3
}

目次 ▾

func Compact(dst *bytes.Buffer, src []byte) error
func HTMLEscape(dst *bytes.Buffer, src []byte)
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
func Valid(data []byte) bool
type Decoder
    func NewDecoder(r io.Reader) *Decoder
    func (dec *Decoder) Buffered() io.Reader
    func (dec *Decoder) Decode(v interface{}) error
    func (dec *Decoder) DisallowUnknownFields()
    func (dec *Decoder) More() bool
    func (dec *Decoder) Token() (Token, error)
    func (dec *Decoder) UseNumber()
type Delim
    func (d Delim) String() string
type Encoder
    func NewEncoder(w io.Writer) *Encoder
    func (enc *Encoder) Encode(v interface{}) error
    func (enc *Encoder) SetEscapeHTML(on bool)
    func (enc *Encoder) SetIndent(prefix, indent string)
type InvalidUTF8Error
    func (e *InvalidUTF8Error) Error() string
type InvalidUnmarshalError
    func (e *InvalidUnmarshalError) Error() string
type Marshaler
type MarshalerError
    func (e *MarshalerError) Error() string
    func (e *MarshalerError) Unwrap() error
type Number
    func (n Number) Float64() (float64, error)
    func (n Number) Int64() (int64, error)
    func (n Number) String() string
type RawMessage
    func (m RawMessage) MarshalJSON() ([]byte, error)
    func (m *RawMessage) UnmarshalJSON(data []byte) error
type SyntaxError
    func (e *SyntaxError) Error() string
type Token
type UnmarshalFieldError
    func (e *UnmarshalFieldError) Error() string
type UnmarshalTypeError
    func (e *UnmarshalTypeError) Error() string
type Unmarshaler
type UnsupportedTypeError
    func (e *UnsupportedTypeError) Error() string
type UnsupportedValueError
    func (e *UnsupportedValueError) Error() string

パッケージファイル

decode.go encode.go fold.go indent.go scanner.go stream.go tables.go tags.go

func Compact

func Compact(dst *bytes.Buffer, src []byte) error

Compact は,意味のない空白文字を取り除いた, JSON エンコードされた src を dst に追加します。 Like Marshal, Compact applies HTMLEscape to any string literals so that the JSON will be safe to embed inside HTML <script> tags.

func HTMLEscape

func HTMLEscape(dst *bytes.Buffer, src []byte)

HTMLEscape は,HTML <script> タグの中に埋め込んでも安全になるように,文字列リテラル内の <, >, &, U+2028 および U+2029 文字を \u003c, \u003e, \u0026, \u2028, \u2029 に変更して JSON エンコード src を dst に追加します。 歴史的な理由から, Web ブラウザは <script> タグ内での標準の HTML エスケープを適用しないため, 代わりの JSON エンコーディングを使用する必要があります。

コード:

var out bytes.Buffer
json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`))
out.WriteTo(os.Stdout)

出力:

{"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}

func Indent

func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error

Indent は JSON エンコードされた,インデント付きの src を dst に追加します。 JSON オブジェクトまたは配列の各要素は,prefix で始まる新しいインデント行で始まり, その後にインデントのネストに従って 1 つ以上の indent のコピーが続きます。 dst に追加されるデータは,他のフォーマットされた JSON データ内に埋め込むのを容易にするために,prefix やインデントで始まっていません。 src の先頭にある先頭の空白文字 (スペース,タブ,キャリッジリターン,改行) は削除されますが, src の末尾にある空白文字は保持され, dst にコピーされます。 たとえば, src に末尾のスペースがない場合は, dst の末尾にもスペースはありません。src の末尾が改行で終わっていれば, dst も末尾が改行で終わります。

コード:

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)

出力:

[
=	{
=		"Name": "Diamond Fork",
=		"Number": 29
=	},
=	{
=		"Name": "Sheep Creek",
=		"Number": 51
=	}
=]

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal は v の JSON エンコーディングを返します。

Marshal は値 v を再帰的に横断します。 値が Marshaler インターフェースを実装していて, nil ポインターではない場合, Marshal は MarshalJSON メソッドを呼び出して JSON を生成します。 MarshalJSON メソッドが存在せず,値が代わりに encoding.TextMarshaler を実装している場合, Marshal はその MarshalText メソッドを呼び出し,結果を JSON 文字列としてエンコードします。 nil ポインター例外は厳密には必要ではありませんが, UnmarshalJSON で必要とされる例外を模倣しています。

それ以外の場合, Marshal は次の型依存のデフォルトエンコーディングを使用します。

ブール値は JSON ブール値としてエンコードされます。

浮動小数点,整数,および数値の値は JSON 数値としてエンコードされます。

文字列値は有効な UTF-8 に強制変換された JSON 文字列としてエンコードされ, 無効なバイトは Unicode の置換文字列に置き換えられます。 JSON が HTML <script> タグ内に安全に埋め込めるようにするため,文字列は HTMLEscape を使ってエンコードされます。 そのため,"<", ">", "&", U+2028, U+2029 は, "\u003c","\u003e", "\u0026", "\u2028", "\u2029" にエスケープされます。 この置換は,Encoder を使っている場合, SetEscapeHTML(false) を呼び出して無効にできます。

配列とスライス値は JSON 配列としてエンコードされます。 ただし,[]byte は base64 でエンコードされた文字列としてエンコードされます。 また,nil スライスは JSON null 値とエンコードされます。

構造体の値は JSON オブジェクトとしてエンコードされます。 エクスポートされた構造体フィールドは,フィールド名をオブジェクトキーとして, オブジェクトのメンバーになります。 ただし,以下の場合,フィールドは省略されます。

各構造体フィールドのエンコーディングは,その構造体フィールドのタグの "json" キーの下に格納されているフォーマット文字列によってカスタマイズできます。 フォーマット文字列は,フィールドの名前を示し,その後にオプションのコンマ区切りリストが続くこともあります。 デフォルトのフィールド名を上書きせずにオプションを指定するために,名前は空にすることができます。

"omitempty" オプションは,フィールドが空の値 (false, 0, nil ポインター, nil インターフェース値,および空の配列,スライス,マップ,または文字列) を持つ場合,そのフィールドをエンコードから除外することを指定します。

特別な場合として,フィールドタグが "-" の場合,フィールドは常に省略されます。 "-" という名前のフィールドは,タグ "-," を使用して生成できます。

構造体フィールドタグとその意味の例

// Field は JSON にキー "myName" として現れます。
Field int `json:"myName"`

// Field は JSON にキー "myName" として現れます。
// ただし,上で定義した空の値の場合,省略されます。
Field int `json:"myName,omitempty"`

// Field はキー "Field" (デフォルト) として JSON に現れますが,空の場合はスキップされます。
// 先頭のカンマに注意してください。
Field int `json:",omitempty"`

// このパッケージでは Field は無視されます。
Field int `json:"-"`

// Field はキー "-" として JSON に現れます。
Field int `json:"-,"`

"string" オプションは,フィールドが JSON エンコードの文字列内に JSON として格納されることを示します。 文字列,浮動小数点,整数,またはブール型のフィールドにのみ適用されます。 この特別なレベルのエンコーディングは, JavaScript プログラムと通信するときに使用されることがあります。

Int64String int64 `json:",string"`

引用符,バックスラッシュ,およびコンマを除く, Unicode の文字,数字,および ASCII 句読点のみで構成される空でない文字列の場合は,キー名が使用されます。

匿名の構造体フィールドは,通常,内部のエクスポートされたフィールドが外部の構造体のフィールドであるかのように整列化されます。 次の段落で説明する修正された Go 可視性ルールに従います。 JSON タグで指定された名前を持つ匿名の構造体フィールドは,匿名ではなく,その名前を持つものとして扱われます。 インターフェース型の匿名構造体フィールドは,匿名ではなく,その型の名前を持つものとして扱われます。

どのフィールドを整列化または非整列化するかを決定するときに,構造体フィールドの JSON 用に修正された Go 可視ルールを使います。 同じレベルに複数のフィールドがあり,そのレベルがネストが最も少ない (したがって,通常の Go ルールによって選択されるネストレベルになる) 場合は,次の追加ルールが適用されます。

1) これらのフィールドのうち, JSON タグ付きのものがある場合は, 衝突するタグ付けされていないフィールドが複数ある場合でも,タグ付きフィールドのみが考慮されます。

2) フィールドが 1 つだけある場合 (最初の規則に従ってタグ付けされているかどうかにかかわらず),それが選択されます。

3) それ以外で,複数のフィールドがる場合,すべて無視されます。 エラーは発生しません。

匿名の構造体フィールドの処理は Go 1.1 で新しく追加されました。 Go 1.1 以前は,無名の構造体フィールドは無視されていました。 現在および以前のバージョンの両方で匿名の構造体フィールドを無視することを強制するには, そのフィールドに "-" の JSON タグを付けます。

マップ値は JSON オブジェクトとしてエンコードされます。 マップのキー型は,文字列,整数型,または encoding.TextMarshaler を実装する必要があります。 下記のルールに従って,マップキーは並べ替えられ, JSON オブジェクトキーとして使用されます。なお,文字列に対する上記の UTF-8 規則も適用されます。

- 任意の文字列型のキーは直接使用されます
- encoding.TextMarshaler は整列化されます
- 整数キーは文字列に変換されます

ポインタ値は,指す値がエンコードされます。 nil ポインタは JSON null 値としてエンコードされます。

インターフェース値は,インターフェースに含まれる値がエンコードされます。 nil インターフェース値は, JSON null 値としてエンコードされます。

チャンネル,複素数,および関数の値は JSON でエンコードできません。 そのような値をエンコードしようとすると, Marshal は UnsupportedTypeError を返します。

JSON は循環データ構造を表現できず, Marshal はそれらを処理しません。 巡回構造を Marshal に渡すと,無限再帰が発生します。

コード:

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)

出力:

{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}

func MarshalIndent

func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)

MarshalIndent は Marshal に似ていますが,出力をフォーマットするために indent を適用します。 出力の各 JSON 要素は,prefix で始まる新しい行で始まり,その後にインデントのネストに従って 1 つ以上の indent のコピーが続きます。

コード:

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))

出力:

{
<prefix><indent>"a": 1,
<prefix><indent>"b": 2
<prefix>}

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal は JSON エンコードされたデータを解析し,結果を v が指す値に格納します。 v が nil であるかポインタではない場合, Unmarshal は InvalidUnmarshalError を返します。

Unmarshal は,Marshal が使用するエンコーディングの逆を使用し,必要に応じてマップ,スライス,およびポインタを割り当てます。 ただし,次の追加規則があります。

JSON をポインターに非整列化するには, Unmarshal はまず JSON が JSON リテラルの null であるケースを処理します。 その場合, Unmarshal はポインタを nil に設定します。 それ以外の場合, Unmarshal は JSON をポインタが指す値に非整列化します。 ポインタが nil の場合, Unmarshal はそれを指すために新しい値を割り当てます。

JSON を Unmarshaler インターフェースを実装する値に非整列化するために, Unmarshal は入力が JSON null の場合も含めて, その値の UnmarshalJSON メソッドを呼び出します。 それ以外の場合,値が encoding.TextUnmarshaler を実装し,入力が JSON 引用符付き文字列の場合, Unmarshal は引用符なし形式の文字列を使用してその値の UnmarshalText メソッドを呼び出します。

JSON を構造体に非整列化するには, Unmarshal は入力オブジェクトのキーを Marshal が使用するキー (構造体のフィールド名またはそのタグ) と一致させます。 完全一致を優先しますが,大文字と小文字を区別しない一致も受け入れます。 デフォルトでは,対応する struct フィールドを持たないオブジェクトキーは無視されます (他の方法は, Decoder.DisallowUnknownFields を見てください) 。

JSON をインターフェース値に非整列化するために, Unmarshal は以下のいずれかをインターフェース値に格納します。

bool, JSON ブール値の場合
float64, JSON 数値の場合
string, JSON 文字列の場合
[]interface{}, JSON 配列の場合
map[string]interface{}, JSON オブジェクトの場合
nil, JSON null の場合

JSON 配列をスライスに非整列化するため, Unmarshal はスライスの長さをゼロにリセットしてから各要素をスライスに追加します。 特別な場合として,空の JSON 配列をスライスに非整列化するために, Unmarshal はスライスを新しい空のスライスに置き換えます。

JSON 配列を Go 配列に非整列化するため, Unmarshal は JSON 配列要素を対応する Go 配列要素にデコードします。 Go 配列が JSON 配列よりも小さい場合,追加の JSON 配列要素は破棄されます。 JSON 配列が Go 配列よりも小さい場合,追加の Go 配列要素はゼロ値に設定されます。

JSON オブジェクトをマップに非整列化するために, Unmarshal は最初に使用するマップを用意します。 マップが nil の場合, Unmarshal は新しいマップを割り当てます。 それ以外の場合, Unmarshal は既存のマップを再利用し,既存のエントリを保持します。 Unmarshal は JSON オブジェクトのキーと値のペアをマップに保存します。 マップのキーの型は文字列か整数,あるいは encoding.TextUnmarshaler を実装する必要があります。

JSON 値が特定のターゲットの型に適していない場合,または JSON 数値がターゲットの型ではオーバーフローする場合, Unmarshal はそのフィールドをスキップして可能な限り非整列化を完了します。 それ以上重大なエラーが発生しない場合, Unmarshal はそのような最初のエラーを説明する UnmarshalTypeError を返します。 いずれにせよ,問題のあるフィールドの後は, 残りのすべてのフィールドがターゲットオブジェクトに非整列化されるという保証はありません。

JSON の null 値は,インターフェース,マップ,ポインタ,またはスライスの場合, Go 値を nil に設定することによって非整列化します。 JSON では null が "存在しない" ことを意味するためによく使用されるため, JSON null を他の Go 型に非整列化しても値に影響はなく,エラーも発生しません。

引用符付き文字列を非整列化するとき,無効な UTF-8 または無効な UTF-16 サロゲートペアはエラーとして扱われません。 代わりに,それらは Unicode 置換文字 U+FFFD に置き換えられます。

コード:

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)

出力:

[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]

func Valid 1.9

func Valid(data []byte) bool

Valid は,データが有効な JSON エンコーディングかどうかを報告します。

コード:

goodJSON := `{"example": 1}`
badJSON := `{"example":2:]}}`

fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON)))

出力:

true false

type Decoder

Decoder は入力ストリームから JSON 値を読み込んでデコードします。

type Decoder struct {
    // エクスポートされていないフィールドがあります
}

この例では, Decoder を使用して,異なる JSON 値のストリームをデコードします。

コード:

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)
}

出力:

Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder は, r から読み取る新しいデコーダを返します。

デコーダは独自のバッファリングを導入し,リクエストされた JSON 値を超えて r からデータを読み取ることができます。

func (*Decoder) Buffered 1.1

func (dec *Decoder) Buffered() io.Reader

Buffered は,Decoder のバッファに残っているデータのリーダーを返します。 リーダーは,次に Decode を呼び出すまで有効です。

func (*Decoder) Decode

func (dec *Decoder) Decode(v interface{}) error

デコードは,入力から次の JSON エンコード値を読み取り, それを v が指す値に保管します。

JSON から Go 値への変換の詳細については, Unmarshal のドキュメントを参照してください。

例 (Stream)

この例では,Decoder を使用して JSON オブジェクトのストリーミング配列をデコードします。

コード:

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))

// 左括弧を読む
t, err := dec.Token()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%T: %v\n", t, t)

// 配列に値が含まれている間
for dec.More() {
    var m Message
    // 配列値をデコードする (Message)
    err := dec.Decode(&m)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("%v: %v\n", m.Name, m.Text)
}

// 右括弧を読む
t, err = dec.Token()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%T: %v\n", t, t)

出力:

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 1.10

func (dec *Decoder) DisallowUnknownFields()

DisallowUnknownFields は,デコード先が構造体であり, 入力にデコード先の中の無視されずエクスポートされたフィールドと一致しないオブジェクトキーが含まれている場合に, Decoder がエラーを返すようにします。

func (*Decoder) More 1.5

func (dec *Decoder) More() bool

現在の配列または解析中のオブジェクトに別の要素があるかどうかをさらに報告します。

func (*Decoder) Token 1.5

func (dec *Decoder) Token() (Token, error)

Token (トークン) は入力ストリーム内の次の JSON トークンを返します。 入力ストリームの終わりで, Token は nil, io.EOF を返します。

Token はそれが返す区切り文字 [ ] { } が適切に入れ子になっていて一致していることを保証します。 もし Token が入力中に予期しない区切り文字を見つけた場合,エラーを返します。

入力ストリームは,配列およびオブジェクトの開始と終了を示す Delim 型の区切り文字 [ ] { } とともに, 基本的な JSON 値 (bool, string, number, および null) で構成されています。 コンマとコロンは省略されます。

この例では, Decoder を使用して,異なる JSON 値のストリームをデコードします。

コード:

const jsonStream = `
    {"Message": "Hello", "Array": [1, 2, 3], "Null": null, "Number": 1.234}
`
dec := json.NewDecoder(strings.NewReader(jsonStream))
for {
    t, err := dec.Token()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%T: %v", t, t)
    if dec.More() {
        fmt.Printf(" (more)")
    }
    fmt.Printf("\n")
}

出力:

json.Delim: { (more)
string: Message (more)
string: Hello (more)
string: Array (more)
json.Delim: [ (more)
float64: 1 (more)
float64: 2 (more)
float64: 3
json.Delim: ] (more)
string: Null (more)
<nil>: <nil> (more)
string: Number (more)
float64: 1.234
json.Delim: }

func (*Decoder) UseNumber 1.1

func (dec *Decoder) UseNumber()

UseNumber を使用すると, Decoder は,数値を float64 ではなく Number として interface{} に非整列化します。

type Delim 1.5

Delim は JSON の配列またはオブジェクトの区切り文字で, [] { } のいずれかです。

type Delim rune

func (Delim) String 1.5

func (d Delim) String() string

type Encoder

エンコーダは JSON 値を出力ストリームに書き込みます。

type Encoder struct {
    // エクスポートされていないフィールドがあります
}

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder は, w に書き込む新しいエンコーダを返します。

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode は v の JSON エンコードをストリームに書き込み, その後に改行文字を続けます。

Go 値の JSON への変換について詳しくは, Marshal の資料を参照してください。

func (*Encoder) SetEscapeHTML 1.7

func (enc *Encoder) SetEscapeHTML(on bool)

SetEscapeHTML は,問題のある HTML 文字を JSON 引用符付きストリング内でエスケープするかどうかを指定します。 デフォルトの動作は, JSON を HTML に埋め込むときに発生する可能性がある特定の安全上の問題を回避するために,&, <, および > を \u0026, \u003c, および \u003e にエスケープします。

HTML 以外の場合で,エスケープが出力の読みやすさを妨げるときは, SetEscapeHTML(false) でこの動作を無効にします。

func (*Encoder) SetIndent 1.7

func (enc *Encoder) SetIndent(prefix, indent string)

SetIndent は,パッケージレベルの関数 Indent(dst, src, prefix, indent) でインデントされているかのように, 後続の各エンコード値をフォーマットするようにエンコーダに指示します。 SetIndent("", "") を呼び出すと,インデントが無効になります。

type InvalidUTF8Error

Go 1.2 以前では,無効な UTF-8 シーケンスで文字列値をエンコードしようとすると, InvalidUTF8Error が返されました。 Go 1.2 以降, Marshal は代わりに無効なバイトを Unicode の置換文字 U+FFFD に置き換えることで文字列を有効な UTF-8 に変換します。

非推奨: もう使用されていません。 互換性のために保管されています。

type InvalidUTF8Error struct {
    S string // エラーの原因となった文字列値全体
}

func (*InvalidUTF8Error) Error

func (e *InvalidUTF8Error) Error() string

type InvalidUnmarshalError

InvalidUnmarshalError は, Unmarshal に無効な引数が渡されたことを表します。 (Unmarshal への引数は, nil 以外のポインタでなければなりません。)

type InvalidUnmarshalError struct {
    Type reflect.Type
}

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type Marshaler

Marshaler は,有効な JSON に自分自身を整列化できる型で実装されるインターフェースです。

type Marshaler interface {
    MarshalJSON() ([]byte, error)
}

type MarshalerError

MarshalerError は, MarshalJSON または MarshalText メソッドの呼び出しによるエラーを表します。

type MarshalerError struct {
    Type reflect.Type
    Err  error
}

func (*MarshalerError) Error

func (e *MarshalerError) Error() string

func (*MarshalerError) Unwrap

func (e *MarshalerError) Unwrap() error

type Number 1.1

Number は JSON 数値リテラルを表します。

type Number string

func (Number) Float64 1.1

func (n Number) Float64() (float64, error)

Float64 は数値を float64 として返します。

func (Number) Int64 1.1

func (n Number) Int64() (int64, error)

Int64 は数値を int64 として返します。

func (Number) String 1.1

func (n Number) String() string

String は数字のリテラルテキストを返します。

type RawMessage

RawMessage は,生のエンコード済み JSON 値です。 これは Marshaler と Unmarshaler を実装しており, JSON デコードの遅延や JSON エンコードの事前計算に使用できます。

type RawMessage []byte

例 (Marshal)

この例では,整列化時に RawMessage を使用して事前計算済みの JSON を使用します。

コード:

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)

出力:

{
	"header": {
		"precomputed": true
	},
	"body": "Hello Gophers!"
}

例 (Unmarshal)

この例では, RawMessage を使用して JSON メッセージの一部の解析を遅らせます。

コード:

type Color struct {
    Space string
    Point json.RawMessage // 色空間がわかるまで解析を遅らせる
}
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)
}

出力:

YCbCr &{255 0 -10}
RGB &{98 218 255}

func (RawMessage) MarshalJSON 1.8

func (m RawMessage) MarshalJSON() ([]byte, error)

MarshalJSON は, m の JSON エンコーディングとして m を返します。

func (*RawMessage) UnmarshalJSON

func (m *RawMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON は data のコピーを *m に代入します。

type SyntaxError

SyntaxError は, JSON 構文エラーの説明です。

type SyntaxError struct {
    Offset int64 // Offset バイトの読み取り後にエラーが発生しました
    // エクスポートされていないフィールドがあります
}

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Token 1.5

Token (トークン) は,次のいずれかの種類の値を保持します。

Delim, 4 つの JSON 区切り文字 [ ] { } の場合
bool, JSON ブール値の場合
float64, JSON 数値の場合
Number, JSON 数値の場合
string, JSON 文字列リテラルの場合
nil, JSON null の場合
type Token interface{}

type UnmarshalFieldError

UnmarshalFieldError は,エクスポートされていない (したがって書き込み不可能な) 構造体フィールドになる JSON オブジェクトキーを表します。

非推奨: もう使用されていません。 互換性のために保存されています。

type UnmarshalFieldError struct {
    Key   string
    Type  reflect.Type
    Field reflect.StructField
}

func (*UnmarshalFieldError) Error

func (e *UnmarshalFieldError) Error() string

type UnmarshalTypeError

UnmarshalTypeError は,特定の Go 型の値には不適切な JSON 値を表します。

type UnmarshalTypeError struct {
    Value  string       // JSON 値の説明 - "bool", "array", "number -5"
    Type   reflect.Type // 割り当てられなかった Go 値の型
    Offset int64        // Offset バイト数読み取った後にエラーが発生しました; added in Go 1.5
    Struct string       // フィールドを含む構造体型の名前; added in Go 1.8
    Field  string       // the full path from root node to the field; added in Go 1.8
}

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type Unmarshaler

Unmarshaler は,自分自身の JSON 記述を非整列化できる型によって実装されたインターフェースです。 入力は JSON 値の有効なエンコードであると見なすことができます。 UnmarshalJSON は,戻った後もデータを保持する場合は JSON データをコピーする必要があります。

慣例として, Unmarshal 自体の動作と似させるために, Unmarshaler は UnmarshalJSON([]byte("null")) を何もしない操作として実装します。

type Unmarshaler interface {
    UnmarshalJSON([]byte) error
}

type UnsupportedTypeError

UnsupportedTypeError は,サポートされていない値型をエンコードしようとしたときに Marshal によって返されます。

type UnsupportedTypeError struct {
    Type reflect.Type
}

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError

type UnsupportedValueError struct {
    Value reflect.Value
    Str   string
}

func (*UnsupportedValueError) Error

func (e *UnsupportedValueError) Error() string