com.opengamma.strata.collect.io

Class CsvOutput

java.lang.Object

com.opengamma.strata.collect.io.CsvOutput

public final class CsvOutput
extends Object

Outputs a CSV formatted file.

Provides a simple tool for writing a CSV file.

Each line in the CSV file will consist of comma separated entries. Each entry may be quoted using a double quote. If an entry contains a double quote, comma or trimmable whitespace, it will be quoted. If an entry starts with '=' or '@', it will be quoted. Two double quotes will be used to escape a double quote.

There are two modes of output. Standard mode provides the encoding described above which is accepted by most CSV parsers. Safe mode provides extra encoding to protect unsafe content from being run as a script in tools like Excel.

Instances of this class contain mutable state. A new instance must be created for each file to be output.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CsvOutput.CsvRowOutputWithHeaders Class used when outputting CSV with headers.

Method Summary

Modifier and Type	Method and Description
static CsvOutput	safe(Appendable underlying) Creates an instance, using the system default line separator and using a comma separator.
static CsvOutput	safe(Appendable underlying, String newLine) Creates an instance, allowing the new line character to be controlled and using a comma separator.
static CsvOutput	safe(Appendable underlying, String newLine, String separator) Creates an instance, allowing the new line character to be controlled, specifying the separator.
static CsvOutput	standard(Appendable underlying) Creates an instance, using the system default line separator and using a comma separator.
static CsvOutput	standard(Appendable underlying, String newLine) Creates an instance, allowing the new line character to be controlled and using a comma separator.
static CsvOutput	standard(Appendable underlying, String newLine, String separator) Creates an instance, allowing the new line character to be controlled, specifying the separator.
CsvOutput.CsvRowOutputWithHeaders	withHeaders(List<String> headers, boolean alwaysQuote) Write a header line to the underlying, returning an instance that allows cells to be written by header name.
CsvOutput	writeCell(String cell) Writes a single cell to the current line, only quoting if needed.
CsvOutput	writeCell(String cell, boolean alwaysQuote) Writes a single cell to the current line.
void	writeCsvFile(CsvFile file, boolean alwaysQuote) Writes the provided CsvFile to the underlying.
void	writeCsvIterator(CsvIterator iterator, boolean alwaysQuote) Writes the output of the provided CsvIterator to the underlying.
void	writeLine(List<String> line) Writes a single CSV line to the underlying, only quoting if needed.
void	writeLine(List<String> line, boolean alwaysQuote) Writes a single CSV line to the underlying.
void	writeLines(Iterable<? extends List<String>> lines, boolean alwaysQuote) Writes multiple CSV lines to the underlying.
CsvOutput	writeNewLine() Writes a new line character.
void	writeRow(CsvRow row) Writes a single CsvRow to the underlying, only quoting if needed.
void	writeRow(CsvRow row, boolean alwaysQuote) Writes a single CsvRow to the underlying.
void	writeRows(Iterable<CsvRow> rows, boolean alwaysQuote) Writes multiple CsvRows to the underlying.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

standard

public static CsvOutput standard(Appendable underlying)

Creates an instance, using the system default line separator and using a comma separator.

See the standard quoting rules in the class-level documentation.

Parameters:

underlying - the destination to write to

Returns:

the CSV outputter

standard

public static CsvOutput standard(Appendable underlying,
                                 String newLine)

Creates an instance, allowing the new line character to be controlled and using a comma separator.

See the standard quoting rules in the class-level documentation.

Parameters:

underlying - the destination to write to

newLine - the new line string

Returns:

the CSV outputter

standard

public static CsvOutput standard(Appendable underlying,
                                 String newLine,
                                 String separator)

Creates an instance, allowing the new line character to be controlled, specifying the separator.

See the standard quoting rules in the class-level documentation.

Parameters:

underlying - the destination to write to

newLine - the new line string

separator - the separator used to separate each field, typically a comma, but a tab is sometimes used

Returns:

the CSV outputter

safe

public static CsvOutput safe(Appendable underlying)

Creates an instance, using the system default line separator and using a comma separator.

This applies the standard quoting rules from the class-level documentation, plus an additional rule. If an entry starts with an expression character, '=', '@', '+' or '-', the entry will be quoted and the quote section will be preceeded by equals. Thus, the string '=Foo' will be written as '="=Foo"'. This avoids the string being treated as an expression by tools like Excel. Simple numbers are not quoted. Thus, the number '-1234' will still be written as '-1234'.

Parameters:

underlying - the destination to write to

Returns:

the CSV outputter

safe

public static CsvOutput safe(Appendable underlying,
                             String newLine)

Creates an instance, allowing the new line character to be controlled and using a comma separator.

This applies the standard quoting rules from the class-level documentation, plus an additional rule. If an entry starts with an expression character, '=', '@', '+' or '-', the entry will be quoted and the quote section will be preceeded by equals. Thus, the string '=Foo' will be written as '="=Foo"'. This avoids the string being treated as an expression by tools like Excel. Simple numbers are not quoted. Thus, the number '-1234' will still be written as '-1234'.

Parameters:

underlying - the destination to write to

newLine - the new line string

Returns:

the CSV outputter

safe

public static CsvOutput safe(Appendable underlying,
                             String newLine,
                             String separator)

Creates an instance, allowing the new line character to be controlled, specifying the separator.

This applies the standard quoting rules from the class-level documentation, plus an additional rule. If an entry starts with an expression character, '=', '@', '+' or '-', the entry will be quoted and the quote section will be preceeded by equals. Thus, the string '=Foo' will be written as '="=Foo"'. This avoids the string being treated as an expression by tools like Excel. Simple numbers are not quoted. Thus, the number '-1234' will still be written as '-1234'.

Parameters:

underlying - the destination to write to

newLine - the new line string

separator - the separator used to separate each field, typically a comma, but a tab is sometimes used

Returns:

the CSV outputter

withHeaders

public CsvOutput.CsvRowOutputWithHeaders withHeaders(List<String> headers,
                                                     boolean alwaysQuote)

Write a header line to the underlying, returning an instance that allows cells to be written by header name.

This writes the header line to the underlying. This is normally called once when the CsvOutput instance is created with only the returned instance used to write additional rows. While it is possible to write rows through both instances, this is likely to get confusing.

Parameters:

headers - the list of headers

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Returns:

the writer to use from now on

Throws:

UncheckedIOException - if an IO exception occurs

writeLines

public void writeLines(Iterable<? extends List<String>> lines,
                       boolean alwaysQuote)

Writes multiple CSV lines to the underlying.

The boolean flag controls whether each entry is always quoted or only quoted when necessary.

Parameters:

lines - the lines to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeLine

public void writeLine(List<String> line)

Writes a single CSV line to the underlying, only quoting if needed.

This can be used as a method reference from a Stream pipeline from Stream.forEachOrdered(Consumer).

This method writes each cell in the specified list to the underlying, followed by a new line character.

Parameters:

line - the line to write

Throws:

UncheckedIOException - if an IO exception occurs

writeLine

public void writeLine(List<String> line,
                      boolean alwaysQuote)

Writes a single CSV line to the underlying.

The boolean flag controls whether each entry is always quoted or only quoted when necessary.

This method writes each cell in the specified list to the underlying, followed by a new line character.

Parameters:

line - the line to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeRows

public void writeRows(Iterable<CsvRow> rows,
                      boolean alwaysQuote)

Writes multiple CsvRows to the underlying.

The boolean flag controls whether each entry is always quoted or only quoted when necessary.

Parameters:

rows - the rows to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeRow

public void writeRow(CsvRow row)

Writes a single CsvRow to the underlying, only quoting if needed.

This can be used as a method reference from a Stream pipeline from Stream.forEachOrdered(Consumer).

This method writes each field in the specified row to the underlying, followed by a new line character.

Parameters:

row - the row to write

Throws:

UncheckedIOException - if an IO exception occurs

writeRow

public void writeRow(CsvRow row,
                     boolean alwaysQuote)

Writes a single CsvRow to the underlying.

The boolean flag controls whether each entry is always quoted or only quoted when necessary.

This method writes each field in the specified row to the underlying, followed by a new line character.

Parameters:

row - the row to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeCsvFile

public void writeCsvFile(CsvFile file,
                         boolean alwaysQuote)

Writes the provided CsvFile to the underlying.

Parameters:

file - the file whose contents to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeCsvIterator

public void writeCsvIterator(CsvIterator iterator,
                             boolean alwaysQuote)

Writes the output of the provided CsvIterator to the underlying.

Parameters:

iterator - the iterator whose output to write

alwaysQuote - when true, each column will be quoted, when false, quoting is selective

Throws:

UncheckedIOException - if an IO exception occurs

writeCell

public CsvOutput writeCell(String cell)

Writes a single cell to the current line, only quoting if needed.

When using this method, either writeNewLine() or one of the writeLine methods must be called at the end of the line.

Parameters:

cell - the cell to write

Returns:

this, for method chaining

Throws:

UncheckedIOException - if an IO exception occurs

writeCell

public CsvOutput writeCell(String cell,
                           boolean alwaysQuote)

Writes a single cell to the current line.

The boolean flag controls whether each entry is always quoted or only quoted when necessary.

When using this method, either writeNewLine() or one of the writeLine methods must be called at the end of the line.

Parameters:

cell - the cell to write

alwaysQuote - when true, the cell will be quoted, when false, quoting is selective

Returns:

this, for method chaining

Throws:

UncheckedIOException - if an IO exception occurs

writeNewLine

public CsvOutput writeNewLine()

Writes a new line character.

Returns:

this, for method chaining

Throws:

UncheckedIOException - if an IO exception occurs