From 0db5534d7acb3c5ce39145ec3aaa490cca1a81ea Mon Sep 17 00:00:00 2001 From: Brian Kessler Date: Thu, 31 Jan 2019 22:05:49 -0700 Subject: [PATCH] encoding/csv: document that Writer is buffered Add documentation that individual Write calls are buffered and copy documentation from bufio.Writer notifying the user to call Flush and Error when all writes are complete. Remove reference to "file" since the implementation is general and allows any io.Writer. Fixes #30045 Change-Id: I50165470e548f296494e764707fbabe36c665015 Reviewed-on: https://go-review.googlesource.com/c/160680 Reviewed-by: Brad Fitzpatrick --- src/encoding/csv/writer.go | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/encoding/csv/writer.go b/src/encoding/csv/writer.go index 31c4f9c22d..b18996a930 100644 --- a/src/encoding/csv/writer.go +++ b/src/encoding/csv/writer.go @@ -12,7 +12,7 @@ import ( "unicode/utf8" ) -// A Writer writes records to a CSV encoded file. +// 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 @@ -21,6 +21,12 @@ import ( // Comma is the field delimiter. // // If 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 +// Flush method to guarantee all data has been forwarded to +// the underlying io.Writer. Any errors that occurred should +// be checked by calling the Error method. type Writer struct { Comma rune // Field delimiter (set to ',' by NewWriter) UseCRLF bool // True to use \r\n as the line terminator @@ -37,6 +43,8 @@ func NewWriter(w io.Writer) *Writer { // 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. +// Writes are buffered, so Flush must eventually be called to ensure +// that the record is written to the underlying io.Writer. func (w *Writer) Write(record []string) error { if !validDelim(w.Comma) { return errInvalidDelim @@ -122,7 +130,8 @@ func (w *Writer) Error() error { return err } -// WriteAll writes multiple CSV records to w using Write and then calls Flush. +// WriteAll writes multiple CSV records to w using Write and then calls Flush, +// returning any error from the Flush. func (w *Writer) WriteAll(records [][]string) error { for _, record := range records { err := w.Write(record) -- 2.50.0