diff options
Diffstat (limited to 'devdocs/go/encoding%2Fcsv%2Findex.html')
| -rw-r--r-- | devdocs/go/encoding%2Fcsv%2Findex.html | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/devdocs/go/encoding%2Fcsv%2Findex.html b/devdocs/go/encoding%2Fcsv%2Findex.html new file mode 100644 index 00000000..ce4b7e36 --- /dev/null +++ b/devdocs/go/encoding%2Fcsv%2Findex.html @@ -0,0 +1,239 @@ +<h1> Package csv </h1> <ul id="short-nav"> +<li><code>import "encoding/csv"</code></li> +<li><a href="#pkg-overview" class="overviewLink">Overview</a></li> +<li><a href="#pkg-index" class="indexLink">Index</a></li> +<li><a href="#pkg-examples" class="examplesLink">Examples</a></li> +</ul> <h2 id="pkg-overview">Overview </h2> <p>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. </p> +<p>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. </p> +<pre data-language="go">field1,field2,field3 +</pre> <p>White space is considered part of a field. </p> +<p>Carriage returns before newline characters are silently removed. </p> +<p>Blank lines are ignored. A line with only whitespace characters (excluding the ending newline character) is not considered a blank line. </p> +<p>Fields which start and stop with the quote character " are called quoted-fields. The beginning and ending quote are not part of the field. </p> +<p>The source: </p> +<pre data-language="go">normal string,"quoted-field" +</pre> <p>results in the fields </p> +<pre data-language="go">{`normal string`, `quoted-field`} +</pre> <p>Within a quoted-field a quote character followed by a second quote character is considered a single quote. </p> +<pre data-language="go">"the ""word"" is true","a ""quoted-field""" +</pre> <p>results in </p> +<pre data-language="go">{`the "word" is true`, `a "quoted-field"`} +</pre> <p>Newlines and commas may be included in a quoted-field </p> +<pre data-language="go">"Multi-line +field","comma is ," +</pre> <p>results in </p> +<pre data-language="go">{`Multi-line +field`, `comma is ,`} +</pre> <h2 id="pkg-index">Index </h2> <ul id="manual-nav"> +<li><a href="#pkg-variables">Variables</a></li> +<li><a href="#ParseError">type ParseError</a></li> +<li> <a href="#ParseError.Error">func (e *ParseError) Error() string</a> +</li> +<li> <a href="#ParseError.Unwrap">func (e *ParseError) Unwrap() error</a> +</li> +<li><a href="#Reader">type Reader</a></li> +<li> <a href="#NewReader">func NewReader(r io.Reader) *Reader</a> +</li> +<li> <a href="#Reader.FieldPos">func (r *Reader) FieldPos(field int) (line, column int)</a> +</li> +<li> <a href="#Reader.InputOffset">func (r *Reader) InputOffset() int64</a> +</li> +<li> <a href="#Reader.Read">func (r *Reader) Read() (record []string, err error)</a> +</li> +<li> <a href="#Reader.ReadAll">func (r *Reader) ReadAll() (records [][]string, err error)</a> +</li> +<li><a href="#Writer">type Writer</a></li> +<li> <a href="#NewWriter">func NewWriter(w io.Writer) *Writer</a> +</li> +<li> <a href="#Writer.Error">func (w *Writer) Error() error</a> +</li> +<li> <a href="#Writer.Flush">func (w *Writer) Flush()</a> +</li> +<li> <a href="#Writer.Write">func (w *Writer) Write(record []string) error</a> +</li> +<li> <a href="#Writer.WriteAll">func (w *Writer) WriteAll(records [][]string) error</a> +</li> +</ul> <div id="pkg-examples"> <h3>Examples</h3> <dl> <dd><a class="exampleLink" href="#example_Reader">Reader</a></dd> <dd><a class="exampleLink" href="#example_Reader_ReadAll">Reader.ReadAll</a></dd> <dd><a class="exampleLink" href="#example_Reader_options">Reader (Options)</a></dd> <dd><a class="exampleLink" href="#example_Writer">Writer</a></dd> <dd><a class="exampleLink" href="#example_Writer_WriteAll">Writer.WriteAll</a></dd> </dl> </div> <h3>Package files</h3> <p> <span>reader.go</span> <span>writer.go</span> </p> <h2 id="pkg-variables">Variables</h2> <p>These are the errors that can be returned in [ParseError.Err]. </p> +<pre data-language="go">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") +)</pre> <h2 id="ParseError">type <span>ParseError</span> </h2> <p>A ParseError is returned for parsing errors. Line and column numbers are 1-indexed. </p> +<pre data-language="go">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 +} +</pre> <h3 id="ParseError.Error">func (*ParseError) <span>Error</span> </h3> <pre data-language="go">func (e *ParseError) Error() string</pre> <h3 id="ParseError.Unwrap">func (*ParseError) <span>Unwrap</span> <span title="Added in Go 1.13">1.13</span> </h3> <pre data-language="go">func (e *ParseError) Unwrap() error</pre> <h2 id="Reader">type <span>Reader</span> </h2> <p>A Reader reads records from a CSV-encoded file. </p> +<p>As returned by <a href="#NewReader">NewReader</a>, a Reader expects input conforming to RFC 4180. The exported fields can be changed to customize the details before the first call to <a href="#Reader.Read">Reader.Read</a> or <a href="#Reader.ReadAll">Reader.ReadAll</a>. </p> +<p>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. </p> +<pre data-language="go">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 +} +</pre> <h4 id="example_Reader"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">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) +} +</pre> <p>Output:</p> <pre class="output" data-language="go">[first_name last_name username] +[Rob Pike rob] +[Ken Thompson ken] +[Robert Griesemer gri] +</pre> <h4 id="example_Reader_options"> <span class="text">Example (Options)</span> +</h4> <p>This example shows how csv.Reader can be configured to handle other types of CSV files. </p> <p>Code:</p> <pre class="code" data-language="go">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) +</pre> <p>Output:</p> <pre class="output" data-language="go">[[first_name last_name username] [Rob Pike rob] [Ken Thompson ken] [Robert Griesemer gri]] +</pre> <h3 id="NewReader">func <span>NewReader</span> </h3> <pre data-language="go">func NewReader(r io.Reader) *Reader</pre> <p>NewReader returns a new Reader that reads from r. </p> +<h3 id="Reader.FieldPos">func (*Reader) <span>FieldPos</span> <span title="Added in Go 1.17">1.17</span> </h3> <pre data-language="go">func (r *Reader) FieldPos(field int) (line, column int)</pre> <p>FieldPos returns the line and column corresponding to the start of the field with the given index in the slice most recently returned by <a href="#Reader.Read">Reader.Read</a>. Numbering of lines and columns starts at 1; columns are counted in bytes, not runes. </p> +<p>If this is called with an out-of-bounds index, it panics. </p> +<h3 id="Reader.InputOffset">func (*Reader) <span>InputOffset</span> <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (r *Reader) InputOffset() int64</pre> <p>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. </p> +<h3 id="Reader.Read">func (*Reader) <span>Read</span> </h3> <pre data-language="go">func (r *Reader) Read() (record []string, err error)</pre> <p>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 <a href="#ErrFieldCount">ErrFieldCount</a>. 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, <span>io.EOF</span>. If [Reader.ReuseRecord] is true, the returned slice may be shared between multiple calls to Read. </p> +<h3 id="Reader.ReadAll">func (*Reader) <span>ReadAll</span> </h3> <pre data-language="go">func (r *Reader) ReadAll() (records [][]string, err error)</pre> <p>ReadAll reads all the remaining records from r. Each record is a slice of fields. A successful call returns err == nil, not err == <span>io.EOF</span>. Because ReadAll is defined to read until EOF, it does not treat end of file as an error to be reported. </p> <h4 id="example_Reader_ReadAll"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">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) +</pre> <p>Output:</p> <pre class="output" data-language="go">[[first_name last_name username] [Rob Pike rob] [Ken Thompson ken] [Robert Griesemer gri]] +</pre> <h2 id="Writer">type <span>Writer</span> </h2> <p>A Writer writes records using CSV encoding. </p> +<p>As returned by <a href="#NewWriter">NewWriter</a>, 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 <a href="#Writer.Write">Writer.Write</a> or <a href="#Writer.WriteAll">Writer.WriteAll</a>. </p> +<p>[Writer.Comma] is the field delimiter. </p> +<p>If [Writer.UseCRLF] is true, the Writer ends each output line with \r\n instead of \n. </p> +<p>The writes of individual records are buffered. After all data has been written, the client should call the <a href="#Writer.Flush">Writer.Flush</a> method to guarantee all data has been forwarded to the underlying <span>io.Writer</span>. Any errors that occurred should be checked by calling the <a href="#Writer.Error">Writer.Error</a> method. </p> +<pre data-language="go">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 +} +</pre> <h4 id="example_Writer"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">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) +} +</pre> <p>Output:</p> <pre class="output" data-language="go">first_name,last_name,username +Rob,Pike,rob +Ken,Thompson,ken +Robert,Griesemer,gri +</pre> <h3 id="NewWriter">func <span>NewWriter</span> </h3> <pre data-language="go">func NewWriter(w io.Writer) *Writer</pre> <p>NewWriter returns a new Writer that writes to w. </p> +<h3 id="Writer.Error">func (*Writer) <span>Error</span> <span title="Added in Go 1.1">1.1</span> </h3> <pre data-language="go">func (w *Writer) Error() error</pre> <p>Error reports any error that has occurred during a previous <a href="#Writer.Write">Writer.Write</a> or <a href="#Writer.Flush">Writer.Flush</a>. </p> +<h3 id="Writer.Flush">func (*Writer) <span>Flush</span> </h3> <pre data-language="go">func (w *Writer) Flush()</pre> <p>Flush writes any buffered data to the underlying <span>io.Writer</span>. To check if an error occurred during Flush, call <a href="#Writer.Error">Writer.Error</a>. </p> +<h3 id="Writer.Write">func (*Writer) <span>Write</span> </h3> <pre data-language="go">func (w *Writer) Write(record []string) error</pre> <p>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 <a href="#Writer.Flush">Writer.Flush</a> must eventually be called to ensure that the record is written to the underlying <span>io.Writer</span>. </p> +<h3 id="Writer.WriteAll">func (*Writer) <span>WriteAll</span> </h3> <pre data-language="go">func (w *Writer) WriteAll(records [][]string) error</pre> <p>WriteAll writes multiple CSV records to w using <a href="#Writer.Write">Writer.Write</a> and then calls <a href="#Writer.Flush">Writer.Flush</a>, returning any error from the Flush. </p> <h4 id="example_Writer_WriteAll"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">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) +} +</pre> <p>Output:</p> <pre class="output" data-language="go">first_name,last_name,username +Rob,Pike,rob +Ken,Thompson,ken +Robert,Griesemer,gri +</pre><div class="_attribution"> + <p class="_attribution-p"> + © Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br> + <a href="http://golang.org/pkg/encoding/csv/" class="_attribution-link">http://golang.org/pkg/encoding/csv/</a> + </p> +</div> |