#include <Csv.h>

Public Member Functions
	CsvWriter (std::string const &path, CsvControl const &control, bool truncate=false, bool append=false)

	CsvWriter (std::ostream &out, CsvControl const &control)

	~CsvWriter ()

CsvControl const &	getControl () const

void	endRecord ()

void	flush ()

size_t	getNumLines () const

size_t	getNumRecords () const

size_t	getNumFields () const

Append field(s) to the end of a record
void	appendFields (std::vector< std::string > const &fields)

void	appendField (std::string const &v)

void	appendField (char const *v)

void	appendField (bool v)

void	appendField (char v)

void	appendField (signed char v)

void	appendField (short v)

void	appendField (int v)

void	appendField (long v)

void	appendField (long long v)

void	appendField (unsigned char v)

void	appendField (unsigned short v)

void	appendField (unsigned int v)

void	appendField (unsigned long v)

void	appendField (unsigned long long v)

void	appendField (float v)

void	appendField (double v)

void	appendField (long double v)

void	appendNull ()


void	write (std::string const &v)

void	write (char c)

Private Member Functions
	CsvWriter (CsvWriter const &)

CsvWriter &	operator= (CsvWriter const &)

void	_write (char const *s)

void	_writeQuoted (char const *s)

void	_writeUnquoted (char const *s)

Private Attributes
boost::scoped_ptr< std::ofstream >	_stream
	Output file stream. More...

std::ostream *	_out
	Output stream. More...

CsvControl	_control
	File format. More...

size_t	_numRecords
	Number of records written. More...

size_t	_numLines
	Number of lines written. More...

size_t	_numFields
	Number of fields written. More...

Detailed Description

A class for writing fields and records to Character-Separated-Value files in sequential order.

Field Output

Methods are provided to output strings, bool, signed/unsigned integers, floating point types, and database NULLs. Integers are always output in base 10, and booleans are output as "1" (true) or "0". The precision of the decimal output for floating point numbers is such that the original binary value can be recovered exactly if the systems float to decimal conversion routines are correctly rounded and the input/output rounding modes agree.

Exception Safety

This class provides the minimal exception safety guarantee - that is, exceptions will not cause crashes or leaks, and one can technically continue using the writer. However, the CSV files written under these conditions are not guaranteed to be legal. For example, partially written fields may be produced by a writer when raising an exception.

Limitations

Field values containing embedded null characters are not written out properly. Only the characters before the first null character will be written.
The line terminator cannot be specified, and is always '\n'.

Definition at line 249 of file Csv.h.

Constructor & Destructor Documentation

lsst::ap::utils::CsvWriter::CsvWriter	(	std::string const &	path,
		CsvControl const &	control,
		bool	truncate = `false`,
		bool	append = `false`
	)

Creates a new CsvWriter that outputs to the given file.

Parameters

path	Name of file to write to.
control	CSV format of the output file.
truncate	If true, an existing file is truncated. Otherwise, an attempt to create a writer for an existing file raises an exception unless append is true.
append	If true, append to an existing file. Has no effect if truncate is true.

Definition at line 649 of file Csv.cc.

   :
     _stream(),
     _out(0),
     _control(control),
     _numRecords(0),
     _numLines(0),
     _numFields(0)
 {
     ios::openmode mode = ios::out | ios::binary;
     if (!truncate && boost::filesystem::exists(path)) {
         if (append) {
             mode |= ios::app;
         } else {
             throw LSST_EXCEPT(pexExcept::IoError,
                               "file " + path + " already exists");
         }
     }
     if (truncate) {
         mode |= ios::trunc;
     }
     _stream.reset(new ofstream(path.c_str(), mode));
     if (!_stream->good()) {
         throw LSST_EXCEPT(pexExcept::IoError,
                           "failed to open file " + path + " for writing");
     }
     _out = _stream.get();
     // throw on any kind of output error
     _stream->exceptions(ios::eofbit | ios::failbit | ios::badbit);
 }

lsst::ap::utils::CsvWriter::CsvWriter	(	std::ostream &	out,
		CsvControl const &	control
	)

Creates a new CsvWriter that sends output to the given std::ostream.

This std::ostream must be kept alive for the life-time of the CsvWriter. If it is externally modified while the writer is alive (e.g. its exception mask is changed, or external writes are performed on it), then the behaviour and output of the writer is undefined.

Definition at line 695 of file Csv.cc.

                                                                :
     _stream(),
     _out(&out),
     _control(control),
     _numRecords(0),
     _numLines(0),
     _numFields(0)
 {
     if (!out.good()) {
         throw LSST_EXCEPT(pexExcept::IoError,
                           "std::ostream not good() for writing");
     }
     out.exceptions(ios::eofbit | ios::failbit | ios::badbit);
 }

lsst::ap::utils::CsvWriter::~CsvWriter ( )

Definition at line 710 of file Csv.cc.

                       {
     _out = 0;
 }

lsst::ap::utils::CsvWriter::CsvWriter ( CsvWriter const & )

private

Member Function Documentation

void lsst::ap::utils::CsvWriter::_write ( char const * s )

private

Appends a field to the current record.

Definition at line 915 of file Csv.cc.

                                     {
     // output leading delimiter except for the first field in a record
     if (_numFields > 0) {
         _out->put(_control.getDelimiter());
     }
     ++_numFields;
     if (_control.quoting == "QUOTE_NONE") {
         if (_control.hasNull && _control.null == s) {
             throw LSST_EXCEPT(pexExcept::RuntimeError,
                               "Field value coincides with NULL string "
                               "and quoting is disabled");
         }
         _writeUnquoted(s);
         return;
     } else if (_control.quoting == "QUOTE_ALL" ||
                (_control.hasNull && _control.null == s)) {
         _writeQuoted(s);
         return;
     }
 
     // minimal quoting mode - first determine whether to quote/escape
     size_t n = 0;
     bool wantEscape = false;
     bool wantQuote = false;
     for (char c = *s; c != '\0'; c = s[++n]) {
         if (c == '\n' || c == '\r') {
             if (_control.standardEscapes) {
                 wantEscape = true;
             } else {
                 wantQuote = true;
             }
         } else if (c == _control.getDelimiter()) {
             wantQuote = true;
         } else if (c == _control.getEscapeChar()) {
             wantQuote = true;
             wantEscape = true;
         } else if (c == _control.getQuoteChar()) {
             if (_control.doubleQuote) {
                 wantQuote = true;
             }
             wantEscape = true;
         }
     }
     // if no escapes are necessary, blast chars to output stream, otherwise
     // delegate to _writeQuoted() and _writeUnquoted()
     if (wantQuote) {
         if (wantEscape) {
             _writeQuoted(s);
         } else {
             _out->put(_control.getQuoteChar());
             _out->write(s, n);
             _out->put(_control.getQuoteChar());
         }
     } else if (wantEscape) {
         _writeUnquoted(s);
     } else {
         _out->write(s, n);
     }
 }

void lsst::ap::utils::CsvWriter::_writeQuoted ( char const * s )

private

Writes quoted field data, handling any required escaping.

Definition at line 977 of file Csv.cc.

                                           {
     _out->put(_control.getQuoteChar());
     size_t n = 0;
     while (true) {
         char const c = s[n];
         if (c == '\0') {
             _out->write(s, n);
             break;
         }
         if (c == _control.getQuoteChar()) {
             _out->write(s, n);
             s += n + 1;
             n = 0;
             if (_control.doubleQuote) {
                 _out->put(c);
                 _out->put(c);
             } else if (_control.getEscapeChar() == '\0') {
                 _out->put(c);
                 throw LSST_EXCEPT(pexExcept::InvalidParameterError,
                                   "Field value requires escaping, but "
                                   "no escape character is set");
             } else {
                 _out->put(_control.getEscapeChar());
                 _out->put(c);
             }
         } else if (c == _control.getEscapeChar()) {
             _out->write(s, n);
             s += n + 1;
             n = 0;
             _out->put(c);
             _out->put(c);
         } else if (_control.standardEscapes && (c == '\n' || c == '\r')) {
             _out->write(s, n);
             s += n + 1;
             n = 0;
             if (_control.getEscapeChar() == '\0') {
                 _out->put(_control.getQuoteChar());
                 throw LSST_EXCEPT(pexExcept::InvalidParameterError,
                                   "Field value requires escaping, but "
                                   "no escape character is set");
             }
             _out->put(_control.getEscapeChar());
             _out->put(c == '\n' ? 'n' : 'r');
         } else {
             ++n;
         }
     }
     _out->put(_control.getQuoteChar());
 }

void lsst::ap::utils::CsvWriter::_writeUnquoted ( char const * s )

private

Writes unquoted field data, handling any required escaping.

Definition at line 1029 of file Csv.cc.

                                             {
     size_t n = 0;
     while (true) {
         char const c = s[n];
         if (c == '\0') {
             _out->write(s, n);
             break;
         }
         if (c == '\n' ||
             c == '\r' ||
             c == _control.getDelimiter() ||
             c == _control.getEscapeChar()) {
 
             _out->write(s, n);
             s += n + 1;
             n = 0;
             if (_control.getEscapeChar() == '\0') {
                 throw LSST_EXCEPT(pexExcept::InvalidParameterError,
                                   "Field value requires escaping, but "
                                   "no escape character is set");
             }
             _out->put(_control.getEscapeChar());
             if (c == '\n') {
                 _out->put(_control.standardEscapes ? 'n' : c);
             } else if (c == '\r') {
                 _out->put(_control.standardEscapes ? 'r' : c);
             } else {
                 _out->put(c);
             }
             continue;
         } else if (c == _control.getQuoteChar() &&
                    _control.quoting != "QUOTE_NONE") {
 
             _out->write(s, n);
             s += n + 1;
             n = 0;
             if (_control.doubleQuote) {
                 _out->put(c);
                 _out->put(c);
             } else if (_control.getEscapeChar() == '\0') {
                 throw LSST_EXCEPT(pexExcept::InvalidParameterError,
                                   "Field value requires escaping, but "
                                   "no escape character is set");
             } else {
                _out->put(_control.getEscapeChar());
                _out->put(c);
            }
         } else {
             ++n;
         }
     }
 }

void lsst::ap::utils::CsvWriter::appendField ( std::string const & v )

inline