package csv

Import Path
	encoding/csv (on go.dev)

Dependency Relation
	imports 8 packages, and imported by 0 packages


Involved Source Files

	
		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.
		
			field1,field2,field3
		
		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:
		
			normal string,"quoted-field"
		
		results in the fields
		
			{`normal string`, `quoted-field`}
		
		Within a quoted-field a quote character followed by a second quote
		character is considered a single quote.
		
			"the ""word"" is true","a ""quoted-field"""
		
		results in
		
			{`the "word" is true`, `a "quoted-field"`}
		
		Newlines and commas may be included in a quoted-field
		
			"Multi-line
			field","comma is ,"
		
		results in
		
			{`Multi-line
			field`, `comma is ,`}

	    writer.go


Code Examples

	
		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)
			}
		}

	
		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)
		}

	
		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)
		}

	
		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)
			}
		}

	
		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)
			}
		}




Package-Level Type Names (total 3)


	/* sort by:  |  */
	
		A ParseError is returned for parsing errors.
		Line and column numbers are 1-indexed.

		
			
				// Column (1-based byte index) where the error occurred

			
				// The actual error

			
				// Line where the error occurred

			
				// Line where the record starts

		
			(*ParseError) Error() string
			(*ParseError) Unwrap() error
		
			*ParseError : error


	
		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 [Reader.Read] or [Reader.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.

		
			
				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).

			
				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.

			
				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.

			
				If LazyQuotes is true, a quote may appear in an unquoted field and a
				non-doubled quote may appear in a quoted field.

			
				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.

			
				Deprecated: TrailingComma is no longer used.

			
				If TrimLeadingSpace is true, leading white space in a field is ignored.
				This is done even if the field delimiter, Comma, is white space.

		
			
				FieldPos returns the line and column corresponding to
				the start of the field with the given index in the slice most recently
				returned by [Reader.Read]. Numbering of lines and columns starts at 1;
				columns are counted in bytes, not runes.
				
				If this is called with an out-of-bounds index, it panics.

			
				InputOffset returns the input stream byte offset of the current reader
				position. The offset gives the location of the end of the most recently
				read row and the beginning of the next row.

			
				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].
				If the record contains a field that cannot be parsed,
				Read returns a partial record along with the parse error.
				The partial record contains all fields read before the error.
				If there is no data left to be read, Read returns nil, [io.EOF].
				If [Reader.ReuseRecord] is true, the returned slice may be shared
				between multiple calls to Read.

			
				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.

		
			func NewReader(r io.Reader) *Reader


	
		A Writer writes records using CSV encoding.
		
		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 [Writer.Write] or [Writer.WriteAll].
		
		[Writer.Comma] is the field delimiter.
		
		If [Writer.UseCRLF] is true,
		the Writer ends each output line with \r\n instead of \n.
		
		The writes of individual records are buffered.
		After all data has been written, the client should call the
		[Writer.Flush] method to guarantee all data has been forwarded to
		the underlying [io.Writer].  Any errors that occurred should
		be checked by calling the [Writer.Error] method.

		
			
				// Field delimiter (set to ',' by NewWriter)

			
				// True to use \r\n as the line terminator

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

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

			
				Write 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.
				Writes are buffered, so [Writer.Flush] must eventually be called to ensure
				that the record is written to the underlying [io.Writer].

			
				WriteAll writes multiple CSV records to w using [Writer.Write] and
				then calls [Writer.Flush], returning any error from the Flush.

		
			*Writer : net/http.Flusher
		
			func NewWriter(w io.Writer) *Writer




Package-Level Functions (total 2)


	
		NewReader returns a new Reader that reads from r.


	
		NewWriter returns a new Writer that writes to w.




Package-Level Variables (total 4)


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


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


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


	
		Deprecated: ErrTrailingComma is no longer used.