package csv

import "encoding/csv"

Package csv 读取和写入逗号分隔值(CSV)文件。 CSV 文件有多种类型;本包支持 RFC 4180 中描述的格式, 只是 Writer 默认使用 LF 而不是 CRLF 作为换行字符。

一个 csv 文件包含零条或多条记录,每条记录包含一个或多个字段。 每条记录由换行字符分隔。最后一条记录后面 可以选择性地跟一个换行字符。

field1,field2,field3

空白字符被视为字段的一部分。

换行字符之前的回车符会被静默移除。

空行会被忽略。仅含空白字符的行(不包括 结尾的换行字符)不算空行。

以引号字符 " 开头和结尾的字段称为 带引号字段。开头和结尾的引号不属于 字段的一部分。

源内容:

normal string,"quoted-field"

会得到字段

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

在带引号字段内,紧跟着第二个引号字符的引号字符 被视为单个引号。

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

会得到

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

换行符和逗号可以包含在带引号字段中

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

会得到

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

Index

Examples

Variables

var (
	ErrBareQuote  = errors.New("bare \" in non-quoted-field")
	ErrQuote      = errors.New("extraneous or missing \" in quoted-field")
	ErrFieldCount = errors.New("wrong number of fields")

	// Deprecated: ErrTrailingComma 不再被使用。
	ErrTrailingComma = errors.New("extra delimiter at end of line")
)

这些是可以在 ParseError.Err 中返回的错误。

Types

type ParseError

type ParseError struct {
	StartLine int   // 记录开始的行
	Line      int   // 发生错误的行
	Column    int   // 发生错误的列(从 1 开始的字节索引)
	Err       error // 实际的错误
}

解析错误会返回 ParseError。 行号和列号从 1 开始索引。

func (*ParseError) Error
func (e *ParseError) Error() string
func (*ParseError) Unwrap
func (e *ParseError) Unwrap() error

type Reader

type Reader struct {
	// Comma 是字段分隔符。
	// 由 NewReader 设为逗号(',')。
	// Comma 必须是有效的 rune,且不能是 \r、\n
	// 或 Unicode 替换字符(0xFFFD)。
	Comma rune

	// Comment 若非 0,则它是注释字符。以 Comment 字符开头
	// 且前面没有空白字符的行会被忽略。
	// 若有前导空白字符,则 Comment 字符会成为
	// 字段的一部分,即使 TrimLeadingSpace 为 true。
	// Comment 必须是有效的 rune,且不能是 \r、\n
	// 或 Unicode 替换字符(0xFFFD)。
	// 它也不能等于 Comma。
	Comment rune

	// FieldsPerRecord 是每条记录期望的字段数。
	// 如果 FieldsPerRecord 为正,Read 要求每条记录
	// 具有给定的字段数。如果 FieldsPerRecord 为 0,Read 会将它设为
	// 第一条记录的字段数,从而使后续记录必须
	// 具有相同的字段计数。如果 FieldsPerRecord 为负,则不进行检查,
	// 记录可以具有可变的字段数。
	FieldsPerRecord int

	// 如果 LazyQuotes 为 true,引号可以出现在不带引号的字段中,
	// 非成对的引号也可以出现在带引号的字段中。
	LazyQuotes bool

	// 如果 TrimLeadingSpace 为 true,字段中的前导空白会被忽略。
	// 即使字段分隔符 Comma 是空白,也会这样做。
	TrimLeadingSpace bool

	// ReuseRecord 控制 Read 的调用是否可以为提升性能而返回
	// 与上一次调用返回的切片共享底层数组的切片。
	// 默认情况下,每次调用 Read 都返回由调用者拥有的新分配内存。
	ReuseRecord bool

	// Deprecated: TrailingComma 不再被使用。
	TrailingComma bool
	// contains filtered or unexported fields
}

Reader 从 CSV 编码的文件中读取记录。

由 NewReader 返回的 Reader 期望输入符合 RFC 4180。 导出的字段可以在首次调用 Reader.Read 或 Reader.ReadAll 之前更改,以自定义各个细节。

Reader 会将其输入中所有 \r\n 序列转换为单纯的 \n, 包括多行字段值中的,因此返回的数据不会 依赖于输入文件使用哪种行结束约定。

Example
package main

import (
	"encoding/csv"
	"fmt"
	"io"
	"log"
	"strings"
)

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

Output:

[first_name last_name username]
[Rob Pike rob]
[Ken Thompson ken]
[Robert Griesemer gri]
Example (Options)

This example shows how csv.Reader can be configured to handle other types of CSV files.

package main

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

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

Output:

[[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) FieldPos
func (r *Reader) FieldPos(field int) (line, column int)

FieldPos 返回 Reader.Read 最近返回的切片中 给定索引的字段起始位置所对应的行和列。行号和列号从 1 开始; 列按字节计数,而不是按 rune。

如果使用越界的索引调用它,它会 panic。

func (*Reader) InputOffset
func (r *Reader) InputOffset() int64

InputOffset 返回当前读取器位置的输入流字节偏移量。 该偏移量给出最近读取的行的末尾位置 以及下一行的起始位置。

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

Read 从 r 读取一条记录(一个字段切片)。 如果记录的字段数不符合预期, Read 会返回该记录以及错误 ErrFieldCount。 如果记录中包含无法解析的字段, Read 会返回部分记录以及解析错误。 该部分记录包含出错之前已读取的所有字段。 如果没有剩余数据可读,Read 返回 nil, io.EOF。 如果 Reader.ReuseRecord 为 true,返回的切片可能在 多次调用 Read 之间共享。

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

ReadAll 从 r 读取所有剩余记录。 每条记录是一个字段切片。 成功的调用返回 err == nil,而不是 err == io.EOF。因为 ReadAll 定义为读取到 EOF,它不把文件末尾视为需要 报告的错误。

Example
package main

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

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

Output:

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

type Writer

type Writer struct {
	Comma   rune // 字段分隔符(由 NewWriter 设为 ',')
	UseCRLF bool // 若为 true,则使用 \r\n 作为行终止符
	// contains filtered or unexported fields
}

Writer 使用 CSV 编码写入记录。

由 NewWriter 返回的 Writer 写入以换行符结尾的记录,并使用 ',' 作为字段分隔符。 导出的字段可以在首次调用 Writer.Write 或 Writer.WriteAll 之前更改,以自定义各个细节。

Writer.Comma 是字段分隔符。

如果 Writer.UseCRLF 为 true, Writer 会用 \r\n 而不是 \n 结束每一输出行。

单条记录的写入是带缓冲的。 所有数据写入完毕后,客户端应调用 Writer.Flush 方法,以保证所有数据都已转发到 底层 io.Writer。任何发生的错误都应 通过调用 Writer.Error 方法检查。

Example
package main

import (
	"encoding/csv"
	"log"
	"os"
)

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

	// Write any buffered data to the underlying writer (standard output).
	w.Flush()

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

Output:

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
func (w *Writer) Error() error

Error 报告在之前的 Writer.Write 或 Writer.Flush 期间 发生的任何错误。

func (*Writer) Flush
func (w *Writer) Flush()

Flush 将任何缓冲数据写入底层 io.Writer。 要检查 Flush 期间是否发生错误,请调用 Writer.Error。

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

Write 将单条 CSV 记录连同任何必要的引号一起写入 w。 记录是一个字符串切片,其中每个字符串为一个字段。 写入是带缓冲的,因此最终必须调用 Writer.Flush 以确保 记录被写入底层 io.Writer。

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

WriteAll 使用 Writer.Write 将多条 CSV 记录写入 w, 然后调用 Writer.Flush,返回 Flush 产生的任何错误。

Example
package main

import (
	"encoding/csv"
	"log"
	"os"
)

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

	w := csv.NewWriter(os.Stdout)
	w.WriteAll(records) // calls Flush internally

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

Output:

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