Пакет 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
}
функция (*ParseError) Error
func (e *ParseError) Error() string
функция (*ParseError) Unwrap 1.13
func (e *ParseError) Unwrap() error
тип Reader
Reader считывает записи из файла, закодированного в формате CSV.
Как возвращается NewReader, Reader ожидает ввода, соответствующего 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]]
функция NewReader
func NewReader(r io.Reader) *Reader
NewReader возвращает новый Reader, который считывает из r.
функция (*Reader) FieldPos 1.17
func (r *Reader) FieldPos(field int) (line, column int)
FieldPos возвращает строку и столбец, соответствующие началу поля с заданным индексом в списке, который был возвращен последним вызовом Reader.Read. Нумерация строк и столбцов начинается с 1; столбцы считаются в байтах, а не в рунах.
Если эта функция вызывается с индексом вне диапазона, она вызывает ошибку паники.
функция (*Reader) InputOffset 1.19
func (r *Reader) InputOffset() int64
InputOffset возвращает смещение входного потока в байтах текущего положения ридера. Смещение указывает расположение конца последней прочитанной строки и начала следующей строки.
функция (*Reader) Read
func (r *Reader) Read() (record []string, err error)
Read считывает одну запись (список полей) из r. Если запись имеет неожиданное количество полей, Read возвращает запись вместе с ошибкой ErrFieldCount. Если запись содержит поле, которое нельзя разобрать, Read возвращает частичную запись вместе с ошибкой парсинга. Частичная запись содержит все поля, считанные до ошибки. Если данных больше нет, Read возвращает None, io.EOF. Если [Reader.ReuseRecord] равно true, возвращаемый срез может быть общим для нескольких вызовов Read.
функция (*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.
Как возвращается NewWriter, Writer записывает записи, завершаемые новой строкой, и использует ',' в качестве разделителя полей. Экспортированные поля можно изменить, чтобы настроить детали перед первым вызовом 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
функция NewWriter
func NewWriter(w io.Writer) *Writer
NewWriter возвращает новый Writer, который записывает в w.
функция (*Writer) Error 1.1
func (w *Writer) Error() error
Error сообщает об ошибке, которая произошла во время предыдущего вызова Writer.Write или Writer.Flush.
функция (*Writer) Flush
func (w *Writer) Flush()
Flush записывает любые буферизованные данные в базовый io.Writer. Чтобы проверить, произошла ли ошибка во время Flush, вызовите Writer.Error.
функция (*Writer) Write
func (w *Writer) Write(record []string) error
Write записывает одну запись CSV в w вместе с любыми необходимыми кавычками. Запись — это массив строк, где каждая строка — одно поле. Записи буферизуются, поэтому необходимо вызвать Writer.Flush, чтобы убедиться, что запись записана в базовый io.Writer.
функция (*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/
