Пакет csv
Обзор
Пакет 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 ,`}
Указатель
Файлы пакета
reader.go writer.go
Переменные
Это ошибки, которые могут возвращаться в ParseError.Err.
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 is no longer used.
ErrTrailingComma = errors.New("extra delimiter at end of line")
) тип ParseError
ParseError возвращается при ошибках разбора. Нумерация строк и столбцов начинается с 1.
type ParseError struct {
StartLine int // Line where the record starts; added in Go 1.10
Line int // Line where the error occurred
Column int // Column (1-based byte index) where the error occurred
Err error // The actual error
}
func (*ParseError) Error
func (e *ParseError) Error() string
func (*ParseError) Unwrap 1.13
func (e *ParseError) Unwrap() error
тип Reader
Reader считывает записи из файла в формате CSV.
Как и Reader, возвращаемый функцией NewReader, он ожидает входные данные, соответствующие RFC 4180. Экспортируемые поля можно изменить, чтобы настроить параметры до первого вызова Reader.Read или Reader.ReadAll.
Reader преобразует все последовательности \r\n во входных данных в обычные \n, в том числе в значениях многострочных полей, чтобы возвращаемые данные не зависели от используемого во входном файле соглашения об окончании строк.
type Reader struct {
// Comma is the field delimiter.
// It is set to comma (',') by NewReader.
// Comma must be a valid rune and must not be \r, \n,
// or the Unicode replacement character (0xFFFD).
Comma rune
// Comment, if not 0, is the comment character. Lines beginning with the
// Comment character without preceding whitespace are ignored.
// With leading whitespace the Comment character becomes part of the
// field, even if TrimLeadingSpace is true.
// Comment must be a valid rune and must not be \r, \n,
// or the Unicode replacement character (0xFFFD).
// It must also not be equal to Comma.
Comment rune
// FieldsPerRecord is the number of expected fields per record.
// If FieldsPerRecord is positive, Read requires each record to
// have the given number of fields. If FieldsPerRecord is 0, Read sets it to
// the number of fields in the first record, so that future records must
// have the same field count. If FieldsPerRecord is negative, no check is
// made and records may have a variable number of fields.
FieldsPerRecord int
// If LazyQuotes is true, a quote may appear in an unquoted field and a
// non-doubled quote may appear in a quoted field.
LazyQuotes bool
// If TrimLeadingSpace is true, leading white space in a field is ignored.
// This is done even if the field delimiter, Comma, is white space.
TrimLeadingSpace bool
// ReuseRecord controls whether calls to Read may return a slice sharing
// the backing array of the previous call's returned slice for performance.
// By default, each call to Read returns newly allocated memory owned by the caller.
ReuseRecord bool // Go 1.9
// Deprecated: TrailingComma is no longer used.
TrailingComma bool
// contains filtered or unexported fields
}
Пример
Код:
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]
Пример (параметры)
В этом примере показано, как настроить 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 возвращает новый Reader, считывающий данные из r.
func (*Reader) FieldPos 1.17
func (r *Reader) FieldPos(field int) (line, column int)
FieldPos возвращает номер строки и столбца, соответствующие началу поля с заданным индексом в срезе, недавно возвращённом функцией Reader.Read. Нумерация строк и столбцов начинается с 1; столбцы считаются в байтах, а не в рунах.
При вызове с индексом за пределами допустимого диапазона происходит паника.
func (*Reader) InputOffset 1.19
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, конец файла не считается ошибкой, о которой следует сообщать.
Пример
Код:
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]]
тип Writer
Writer записывает записи в формате CSV.
Writer, возвращаемый функцией NewWriter, записывает записи, завершая их символом новой строки, и использует ',' в качестве разделителя полей. Экспортируемые поля можно изменить, чтобы настроить параметры до первого вызова Writer.Write или Writer.WriteAll.
Writer.Comma задаёт разделитель полей.
Если Writer.UseCRLF равно true, Writer завершает каждую строку вывода последовательностью \r\n вместо \n.
Записи буферизуются по отдельности. После записи всех данных клиенту следует вызвать метод Writer.Flush, чтобы гарантировать передачу всех данных нижележащему io.Writer. Следует проверить наличие ошибок, вызвав метод Writer.Error.
type Writer struct {
Comma rune // Field delimiter (set to ',' by NewWriter)
UseCRLF bool // True to use \r\n as the line terminator
// contains filtered or unexported fields
}
Пример
Код:
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 возвращает новый Writer, записывающий данные в w.
func (*Writer) Error 1.1
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 записывает в w одну запись CSV, добавляя необходимые кавычки. Запись представляет собой срез строк, каждая из которых является одним полем. Запись буферизуется, поэтому для гарантированной передачи записи нижележащему io.Writer необходимо вызвать Writer.Flush.
func (*Writer) WriteAll
func (w *Writer) WriteAll(records [][]string) error
WriteAll записывает несколько записей CSV в w с помощью Writer.Write, а затем вызывает Writer.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) // 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
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/encoding/csv/
