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,
包括多行字段值中的,因此返回的数据不会
依赖于输入文件使用哪种行结束约定。
Output: This example shows how csv.Reader can be configured to handle other
types of CSV files.
Output: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)
}
}
[first_name last_name username]
[Rob Pike rob]
[Ken Thompson ken]
[Robert Griesemer gri]
Example (Options)
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)
}
[[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,它不把文件末尾视为需要
报告的错误。
Output: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)
}
[[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 方法检查。
Output: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)
}
}
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 产生的任何错误。
Output: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)
}
}
first_name,last_name,username
Rob,Pike,rob
Ken,Thompson,ken
Robert,Griesemer,gri