Overview

Package csv reads and writes comma-separated values (CSV) files. There are many
kinds of CSV files; this package supports the format described in RFC 4180.

A csv file contains zero or more records of one or more fields per record. Each
record is separated by the newline character. The final record may optionally be
followed by a newline character.

White space is considered part of a field.

Carriage returns before newline characters are silently removed.

Blank lines are ignored. A line with only whitespace characters (excluding the
ending newline character) is not considered a blank line.

Fields which start and stop with the quote character “ are called quoted-fields.
The beginning and ending quote are not part of the field.

The source:

  1. normal string,"quoted-field"

results in the fields

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

Within a quoted-field a quote character followed by a second quote character is
considered a single quote.

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

results in

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

Newlines and commas may be included in a quoted-field

  1. "Multi-line
  2. field","comma is ,"

results in

  1. {`Multi-line
  2. field`, `comma is ,`}

Package files

writer.go

Variables

  1. var (
  2.     ErrTrailingComma = .New("extra delimiter at end of line") // Deprecated: No longer used.
  3.     ErrBareQuote     = .New("bare \" in non-quoted-field")
  4.     ErrQuote         = .New("extraneous or missing \" in quoted-field")
  5.     ErrFieldCount    = .New("wrong number of fields")
  6. )

These are the errors that can be returned in ParseError.Err.

A ParseError is returned for parsing errors. Line numbers are 1-indexed and
columns are 0-indexed.

func (*ParseError) 

  1. func (e *) Error() string

type 

  1. type Reader struct {
  2.     // Comma is the field delimiter.
  3.     // It is set to comma (',') by NewReader.
  4.     // Comma must be a valid rune and must not be \r, \n,
  5.     // or the Unicode replacement character (0xFFFD).
  6.     Comma 
  7.  
  8.     // Comment, if not 0, is the comment character. Lines beginning with the
  9.     // Comment character without preceding whitespace are ignored.
  10.     // With leading whitespace the Comment character becomes part of the
  11.     // field, even if TrimLeadingSpace is true.
  12.     // Comment must be a valid rune and must not be \r, \n,
  13.     // or the Unicode replacement character (0xFFFD).
  14.     // It must also not be equal to Comma.
  15.  
  16.     // FieldsPerRecord is the number of expected fields per record.
  17.     // If FieldsPerRecord is positive, Read requires each record to
  18.     // have the given number of fields. If FieldsPerRecord is 0, Read sets it to
  19.     // the number of fields in the first record, so that future records must
  20.     // have the same field count. If FieldsPerRecord is negative, no check is
  21.     // made and records may have a variable number of fields.
  22.     FieldsPerRecord int
  23.  
  24.     // If LazyQuotes is true, a quote may appear in an unquoted field and a
  25.     // non-doubled quote may appear in a quoted field.
  26.     LazyQuotes 
  27.  
  28.     // If TrimLeadingSpace is true, leading white space in a field is ignored.
  29.     // This is done even if the field delimiter, Comma, is white space.
  30.     TrimLeadingSpace bool
  31.  
  32.     // ReuseRecord controls whether calls to Read may return a slice sharing
  33.     // the backing array of the previous call's returned slice for performance.
  34.     // By default, each call to Read returns newly allocated memory owned by the caller.
  35.     ReuseRecord 
  36.  
  37.     TrailingComma bool // Deprecated: No longer used.
  38.     // contains filtered or unexported fields
  39. }

A Reader reads records from a CSV-encoded file.

As returned by NewReader, a Reader expects input conforming to RFC 4180. The
exported fields can be changed to customize the details before the first call to
Read or ReadAll.

The Reader converts all \r\n sequences in its input to plain \n, including in
multiline field values, so that the returned data does not depend on which
line-ending convention an input file uses.


Example:

  1. in := `first_name,last_name,username
  2. "Rob","Pike",rob
  3. Ken,Thompson,ken
  4. "Robert","Griesemer","gri"
  5. `
  6. r := csv.NewReader(strings.NewReader(in))
  8. for {
  9.     record, err := r.Read()
  10.     if err == io.EOF {
  11.         break
  12.     }
  13.     if err != nil {
  14.         log.Fatal(err)
  15.     }
  18. }
  19. // Output:
  20. // [first_name last_name username]
  21. // [Rob Pike rob]
  22. // [Ken Thompson ken]
  23. // [Robert Griesemer gri]


Example:

  1. in := `first_name;last_name;username
  2. "Rob";"Pike";rob
  3. # lines beginning with a # character are ignored
  4. "Robert";"Griesemer";"gri"
  5. `
  6. r := csv.NewReader(strings.NewReader(in))
  7. r.Comma = ';'
  8. r.Comment = '#'
  10. records, err := r.ReadAll()
  11. if err != nil {
  12.     log.Fatal(err)
  13. }
  15. fmt.Print(records)
  16. // Output:
  17. // [[first_name last_name username] [Rob Pike rob] [Ken Thompson ken] [Robert Griesemer gri]]

  1. func NewReader(r .Reader) *

NewReader returns a new Reader that reads from r.

func (*Reader) Read

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

Read reads one record (a slice of fields) from r. If the record has an
unexpected number of fields, Read returns the record along with the error
ErrFieldCount. Except for that case, Read always returns either a non-nil record
or a non-nil error, but not both. If there is no data left to be read, Read
returns nil, io.EOF. If ReuseRecord is true, the returned slice may be shared
between multiple calls to Read.

func (*Reader) 

  1. func (r *) ReadAll() (records [][]string, err )

ReadAll reads all the remaining records from r. Each record is a slice of
fields. A successful call returns err == nil, not err == io.EOF. Because ReadAll
is defined to read until EOF, it does not treat end of file as an error to be
reported.


Example:

  1. type Writer struct {
  2.     Comma    // Field delimiter (set to ',' by NewWriter)
  3.     UseCRLF bool // True to use \r\n as the line terminator
  4.     // contains filtered or unexported fields
  5. }

As returned by NewWriter, a Writer writes records terminated by a newline and
uses ‘,’ as the field delimiter. The exported fields can be changed to customize
the details before the first call to Write or WriteAll.

Comma is the field delimiter.

If UseCRLF is true, the Writer ends each output line with \r\n instead of \n.


Example:

  2.     {"first_name", "last_name", "username"},
  3.     {"Rob", "Pike", "rob"},
  4.     {"Ken", "Thompson", "ken"},
  5.     {"Robert", "Griesemer", "gri"},
  6. }
  8. w := csv.NewWriter(os.Stdout)
  10. for _, record := range records {
  11.     if err := w.Write(record); err != nil {
  12.         log.Fatalln("error writing record to csv:", err)
  13.     }
  14. }
  16. // Write any buffered data to the underlying writer (standard output).
  17. w.Flush()
  19. if err := w.Error(); err != nil {
  20.     log.Fatal(err)
  21. }
  22. // Output:
  23. // first_name,last_name,username
  24. // Rob,Pike,rob
  25. // Ken,Thompson,ken

  1. func NewWriter(w io.) *Writer

NewWriter returns a new Writer that writes to w.

func (*Writer) 

  1. func (w *) Error() error

Error reports any error that has occurred during a previous Write or Flush.

func (*Writer) 

  1. func (w *) Flush()

Flush writes any buffered data to the underlying io.Writer. To check if an error
occurred during the Flush, call Error.

    Writer writes a single CSV record to w along with any necessary quoting. A
    record is a slice of strings with each string being one field.

    func (*Writer) WriteAll

    1. func (w *Writer) WriteAll(records [][]) error

    WriteAll writes multiple CSV records to w using Write and then calls Flush.