...

パッケージ csv

import "encoding/csv"
概要
目次

概要 ▾

csv パッケージは,カンマ区切り (CSV) ファイルを読み書きします。 たくさんの種類の CSV ファイルがありますが,このパッケージでは,RFC 4180 で定義されたフォーマットをサポートしています。

csv ファイルには,レコードごとに 1 つ以上のフィールドを持つ, 0 個以上のレコードが含まれています。 各レコードは改行文字で区切られています。 最後のレコードの後に​​は,オプションで改行文字を続けることができます。

field1,field2,field3

空白はフィールドの一部と見なされます。

改行文字の前のキャレッジリターンは削除されます。

空白行は無視されます。 空白文字のみを含む行 (末尾の改行文字を除く) は,空白行とは見なされません。

引用符 "" で始まって終わるフィールドは,引用符付きフィールドと呼ばれます。 開始引用符と終了引用符は,フィールドの一部ではありません。

ソース:

normal string,"quoted-field"

は次のようになります。

{`normal string`, `quoted-field`}

引用符付きフィールド内では, 2 番目の引用符文字が後に続く引用符文字は 1 つの引用符と見なされます。

"the ""word"" is true","a ""quoted-field"""

は,次のようになります

{`the "word" is true`, `a "quoted-field"`}

改行とコンマは引用符付きフィールドに含めることができます

"Multi-line
field","comma is ,"

は,次のようになります

{`Multi-line
field`, `comma is ,`}

変数

これらは ParseError.Err で返される可能性があるエラーです。

var (
    ErrTrailingComma = errors.New("extra delimiter at end of line") // 非推奨: もう使用されていません。
    ErrBareQuote     = errors.New("bare \" in non-quoted-field")
    ErrQuote         = errors.New("extraneous or missing \" in quoted-field")
    ErrFieldCount    = errors.New("wrong number of fields")
)

type ParseError

ParseError (解析エラー) は,パース中のエラーで返されます。 Line 番号は 1 から始まり,Column は 0 から始まります。

type ParseError struct {
    StartLine int   // レコードが始まる行; added in Go 1.10
    Line      int   // エラーが発生した行
    Column    int   // エラーが発生した列 (ルーンインデックス)
    Err       error // 実際のエラー
}

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) Unwrap 1.13

func (e *ParseError) Unwrap() error

type Reader

Reader (リーダー) は CSV でエンコードされたファイルからレコードを読み取ります。

NewReader から返されるように, Reader は RFC 4180 に準拠した入力を想定しています。 Read または ReadAll を最初に呼び出す前にエクスポートされたフィールドを変更して, 詳細をカスタマイズできます。

Reader は,複数行のフィールド値を含め,入力内のすべての \r\n シーケンスを \n に変換します。 そのため,返されるデータは,入力ファイルが使用する行末規則には依存しません。

type Reader struct {
    // Comma はフィールド区切り文字です。
    // NewReader によってコンマ (',') に設定されます。
    // Comma は有効なルーンである必要があり, \r , \n ,または Unicode 置換文字 (0xFFFD) にすることはできません。
    Comma rune

    // Comment は, 0 でなければ,コメント文字です。
    // 先頭に空白を含まない Comment 文字で始まる行は無視されます。
    // TrimLeadingSpace が true であっても,先頭に空白があれば Comment 文字はフィールドの一部になります。
    // Comment は有効なルーンである必要があり, \r , \n ,または Unicode 置換文字 (0xFFFD) にすることはできません。
    // また,Comma と等しくてはいけません。
    Comment rune

    // FieldsPerRecord は, 1 レコードあたりの予想フィールド数です。
    // FieldsPerRecord が正の値の場合, Read は各レコードに指定された数のフィールドがあることを要求します。
    // FieldsPerRecord が 0 の場合, Read はそれを最初のレコードのフィールド数に設定します。
    // それで,以降のレコードは同じフィールド数を持つ必要があります。
    // FieldsPerRecord が負の場合,チェックは行われず,レコードは可変数のフィールドを持つことができます。
    FieldsPerRecord int

    // LazyQuotes が true の場合,引用符で囲まれていないフィールドに引用符が現れる可能性があります。
    // また,二重でない引用符が引用符で囲まれたフィールド現れる可能性があります。
    LazyQuotes bool

    // TrimLeadingSpace が true の場合,フィールド内の先頭の空白は無視されます。
    // これは,フィールド区切り文字のカンマが空白文字の場合でも行われます。
    TrimLeadingSpace bool

    // ReuseRecord は,パフォーマンスを向上させるために,
    // Read の前回の呼び出しで返されたスライスの内部配列を共有するスライスを返すことができるかどうかを制御します。
    // デフォルトでは, Read を呼び出すたびに,呼び出し元が所有する,新しく割り当てられたメモリが返されます。
    ReuseRecord bool // Go 1.9

    TrailingComma bool // 非推奨: もう使用されていません。
    // エクスポートされていないフィールドがあります
}

コード:

in := `first_name,last_name,username
"Rob","Pike",rob
Ken,Thompson,ken
"Robert","Griesemer","gri"
`
r := csv.NewReader(strings.NewReader(in))

for {
    record, err := r.Read()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(record)
}

出力:

[first_name last_name username]
[Rob Pike rob]
[Ken Thompson ken]
[Robert Griesemer gri]

例 (Options)

この例では, csv.Reader を他の種類の CSV ファイルを 処理するように設定する方法を示します。

コード:

in := `first_name;last_name;username
"Rob";"Pike";rob
# lines beginning with a # character are ignored
Ken;Thompson;ken
"Robert";"Griesemer";"gri"
`
r := csv.NewReader(strings.NewReader(in))
r.Comma = ';'
r.Comment = '#'

records, err := r.ReadAll()
if err != nil {
    log.Fatal(err)
}

fmt.Print(records)

出力:

[[first_name last_name username] [Rob Pike rob] [Ken Thompson ken] [Robert Griesemer gri]]

func NewReader

func NewReader(r io.Reader) *Reader

NewReader は, r から読み取る新しい Reader を返します。

func (*Reader) Read

func (r *Reader) Read() (record []string, err error)

Read は, r から 1 レコード (フィールドのスライス) を読み取ります。 レコードに予期しない数のフィールドがある場合, Read はエラー ErrFieldCount とともにレコードを返します。 その場合を除いて, Read は常に nil 以外のレコードか nil 以外のエラーのどちらかを返しますが,両方は返しません。 読み込むデータが残っていない場合, Read は nil, io.EOF を返します。 ReuseRecord が true の場合,返されるスライスは Read への複数の呼び出し間で共有される可能性があります。

func (*Reader) ReadAll

func (r *Reader) ReadAll() (records [][]string, err error)

ReadAll は r から残りのすべてのレコードを読み取ります。 各レコードはフィールドのスライスです。 呼び出しが成功すると, err == io.EOF ではなく, err == nil が返されます。 ReadAll は EOF まで読み取るように定義されているので,ファイルの終わりをエラーとして扱いません。

コード:

in := `first_name,last_name,username
"Rob","Pike",rob
Ken,Thompson,ken
"Robert","Griesemer","gri"
`
r := csv.NewReader(strings.NewReader(in))

records, err := r.ReadAll()
if err != nil {
    log.Fatal(err)
}

fmt.Print(records)

出力:

[[first_name last_name username] [Rob Pike rob] [Ken Thompson ken] [Robert Griesemer gri]]

type Writer

Writer は,レコードを CSV エンコードを用いて書き込みます。

NewWriter から返されるように, Writer は改行で終了するレコードを書き込み,フィールド区切り文字として ',' を使用します。 最初の Write または WriteAll を呼び出す前に,エクスポートされたフィールドを変更して詳細をカスタマイズできます。

Comma はフィールド区切り文字です。

UseCRLF が true の場合, Writer は各出力行を \n ではなく \r\n で終了します。

個々のレコードの書き込みはバッファリングされます。 すべてのデータが書き込まれた後,クライアントは Flush メソッドを呼び出して,すべてのデータが内部の io.Writer に転送されることを保証する必要があります。 発生したエラーは, Error メソッドを呼び出して確認する必要があります。

type Writer struct {
    Comma   rune // フィールド区切り文字 (NewWriter によって ',' に設定されます)
    UseCRLF bool // 行末文字として \r\n を使用する場合は true
    // エクスポートされていないフィールドがあります
}

コード:

records := [][]string{
    {"first_name", "last_name", "username"},
    {"Rob", "Pike", "rob"},
    {"Ken", "Thompson", "ken"},
    {"Robert", "Griesemer", "gri"},
}

w := csv.NewWriter(os.Stdout)

for _, record := range records {
    if err := w.Write(record); err != nil {
        log.Fatalln("error writing record to csv:", err)
    }
}

// バッファリングされているデータを内部のライターに書き込みます (標準出力) 。
w.Flush()

if err := w.Error(); err != nil {
    log.Fatal(err)
}

出力:

first_name,last_name,username
Rob,Pike,rob
Ken,Thompson,ken
Robert,Griesemer,gri

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter は, w に書き込む新しい Writer を返します。

func (*Writer) Error 1.1

func (w *Writer) Error() error

Error は,前回の Write または Flush 中に発生したエラーを報告します。

func (*Writer) Flush

func (w *Writer) Flush()

Flush はバッファリングされたデータを内部の io.Writer に書き込みます。 Flush 中にエラーが発生したかどうかを確認するには, Error を呼び出します。

func (*Writer) Write

func (w *Writer) Write(record []string) error

Write は,必要な引用符付きで 1 つの CSV レコードを w に書き込みます。 レコードは,各文字列が 1 つのフィールドである文字列のスライスです。 書き込みはバッファリングされるため,最終的に Flush を呼び出して,レコードが内部の io.Writer に確実に書き込まれるようにする必要があります。

func (*Writer) WriteAll

func (w *Writer) WriteAll(records [][]string) error

WriteAll は, Write を使用して w に複数の CSV レコードを書き込み,その後 Flush を呼び出します。 Flush からエラーが返される場合,それを返します。

コード:

records := [][]string{
    {"first_name", "last_name", "username"},
    {"Rob", "Pike", "rob"},
    {"Ken", "Thompson", "ken"},
    {"Robert", "Griesemer", "gri"},
}

w := csv.NewWriter(os.Stdout)
w.WriteAll(records) // 内部のフラッシュを呼び出す

if err := w.Error(); err != nil {
    log.Fatalln("error writing csv:", err)
}

出力:

first_name,last_name,username
Rob,Pike,rob
Ken,Thompson,ken
Robert,Griesemer,gri