org.apache.commons.csv

Class CSVFormat

java.lang.Object

org.apache.commons.csv.CSVFormat

All Implemented Interfaces:

java.io.Serializable

public final class CSVFormat
extends java.lang.Object
implements java.io.Serializable

Specifies the format of a CSV file and parses input.

Using predefined formats

You can use one of the predefined formats:

• DEFAULT
• EXCEL
• MYSQL
• RFC4180
• TDF

For example:

 CSVParser parser = CSVFormat.EXCEL.parse(reader);
 

The CSVParser provides static methods to parse other input types, for example:

 CSVParser parser = CSVParser.parse(file, StandardCharsets.US_ASCII, CSVFormat.EXCEL);
 

Defining formats

You can extend a format by calling the with methods. For example:

 CSVFormat.EXCEL.withNullString("N/A").withIgnoreSurroundingSpaces(true);
 

Defining column names

To define the column names you want to use to access records, write:

 CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3");
 

Calling withHeader(String...) let's you use the given names to address values in a CSVRecord, and assumes that your CSV source does not contain a first record that also defines column names. If it does, then you are overriding this metadata with your names and you should skip the first record by calling withSkipHeaderRecord(boolean) with true.

Parsing

You can use a format directly to parse a reader. For example, to parse an Excel file with columns header, write:

 Reader in = ...;
 CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3").parse(in);
 

For other input types, like resources, files, and URLs, use the static methods on CSVParser.

Referencing columns safely

If your source contains a header record, you can simplify your code and safely reference columns, by using withHeader(String...) with no arguments:

 CSVFormat.EXCEL.withHeader();
 

This causes the parser to read the first record and use its values as column names. Then, call one of the CSVRecord get method that takes a String column name argument:

 String value = record.get("Col1");
 

This makes your code impervious to changes in column order in the CSV file.

Notes

This class is immutable.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CSVFormat.Predefined Predefines formats.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	allowMissingColumnNames
private java.lang.Character	commentMarker
static CSVFormat	DEFAULT Standard comma separated format, as for RFC4180 but allowing empty lines.
private char	delimiter
private java.lang.Character	escapeCharacter
static CSVFormat	EXCEL Excel file format (using a comma as the value delimiter).
private java.lang.String[]	header
private java.lang.String[]	headerComments
private boolean	ignoreEmptyLines
private boolean	ignoreHeaderCase
private boolean	ignoreSurroundingSpaces
static CSVFormat	INFORMIX_UNLOAD Default Informix CSV UNLOAD format used by the UNLOAD TO file_name operation.
static CSVFormat	INFORMIX_UNLOAD_CSV Default Informix CSV UNLOAD format used by the UNLOAD TO file_name operation (escaping is disabled.)
static CSVFormat	MYSQL Default MySQL format used by the SELECT INTO OUTFILE and LOAD DATA INFILE operations.
private java.lang.String	nullString
static CSVFormat	POSTGRESQL_CSV Default PostgreSQL CSV format used by the COPY operation.
static CSVFormat	POSTGRESQL_TEXT Default PostgreSQL text format used by the COPY operation.
private java.lang.Character	quoteCharacter
private QuoteMode	quoteMode
private java.lang.String	recordSeparator
static CSVFormat	RFC4180 Comma separated format as defined by RFC 4180.
private static long	serialVersionUID
private boolean	skipHeaderRecord
static CSVFormat	TDF Tab-delimited format.
private boolean	trailingDelimiter
private boolean	trim

Constructor Summary

Constructors

Modifier

Constructor and Description

private

CSVFormat(char delimiter, java.lang.Character quoteChar, QuoteMode quoteMode, java.lang.Character commentStart, java.lang.Character escape, boolean ignoreSurroundingSpaces, boolean ignoreEmptyLines, java.lang.String recordSeparator, java.lang.String nullString, java.lang.Object[] headerComments, java.lang.String[] header, boolean skipHeaderRecord, boolean allowMissingColumnNames, boolean ignoreHeaderCase, boolean trim, boolean trailingDelimiter) Creates a customized CSV format.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj)
java.lang.String	format(java.lang.Object... values) Formats the specified values.
boolean	getAllowMissingColumnNames() Specifies whether missing column names are allowed when parsing the header line.
java.lang.Character	getCommentMarker() Returns the character marking the start of a line comment.
char	getDelimiter() Returns the character delimiting the values (typically ';', ',' or '\t').
java.lang.Character	getEscapeCharacter() Returns the escape character.
java.lang.String[]	getHeader() Returns a copy of the header array.
java.lang.String[]	getHeaderComments() Returns a copy of the header comment array.
boolean	getIgnoreEmptyLines() Specifies whether empty lines between records are ignored when parsing input.
boolean	getIgnoreHeaderCase() Specifies whether header names will be accessed ignoring case.
boolean	getIgnoreSurroundingSpaces() Specifies whether spaces around values are ignored when parsing input.
java.lang.String	getNullString() Gets the String to convert to and from null.
java.lang.Character	getQuoteCharacter() Returns the character used to encapsulate values containing special characters.
QuoteMode	getQuoteMode() Returns the quote policy output fields.
java.lang.String	getRecordSeparator() Returns the record separator delimiting output records.
boolean	getSkipHeaderRecord() Returns whether to skip the header record.
boolean	getTrailingDelimiter() Returns whether to add a trailing delimiter.
boolean	getTrim() Returns whether to trim leading and trailing blanks.
int	hashCode()
boolean	isCommentMarkerSet() Specifies whether comments are supported by this format.
boolean	isEscapeCharacterSet() Returns whether escape are being processed.
private static boolean	isLineBreak(char c) Returns true if the given character is a line break character.
private static boolean	isLineBreak(java.lang.Character c) Returns true if the given character is a line break character.
boolean	isNullStringSet() Returns whether a nullString has been defined.
boolean	isQuoteCharacterSet() Returns whether a quoteChar has been defined.
static CSVFormat	newFormat(char delimiter) Creates a new CSV format with the specified delimiter.
CSVParser	parse(java.io.Reader in) Parses the specified content.
CSVPrinter	print(java.lang.Appendable out) Prints to the specified output.
CSVPrinter	print(java.io.File out, java.nio.charset.Charset charset) Prints to the specified output.
void	print(java.lang.Object value, java.lang.Appendable out, boolean newRecord) Prints the value as the next value on the line to out.
private void	print(java.lang.Object object, java.lang.CharSequence value, int offset, int len, java.lang.Appendable out, boolean newRecord)
CSVPrinter	print(java.nio.file.Path out, java.nio.charset.Charset charset) Prints to the specified output.
private void	printAndEscape(java.lang.CharSequence value, int offset, int len, java.lang.Appendable out)
private void	printAndQuote(java.lang.Object object, java.lang.CharSequence value, int offset, int len, java.lang.Appendable out, boolean newRecord)
CSVPrinter	printer() Prints to the System.out.
void	println(java.lang.Appendable out) Outputs the trailing delimiter (if set) followed by the record separator (if set).
void	printRecord(java.lang.Appendable out, java.lang.Object... values) Prints the given values to out as a single record of delimiter separated values followed by the record separator.
java.lang.String	toString()
private java.lang.String[]	toStringArray(java.lang.Object[] values)
private java.lang.CharSequence	trim(java.lang.CharSequence charSequence)
private void	validate() Verifies the consistency of the parameters and throws an IllegalArgumentException if necessary.
static CSVFormat	valueOf(java.lang.String format) Gets one of the predefined formats from CSVFormat.Predefined.
CSVFormat	withAllowMissingColumnNames() Returns a new CSVFormat with the missing column names behavior of the format set to true
CSVFormat	withAllowMissingColumnNames(boolean allowMissingColumnNames) Returns a new CSVFormat with the missing column names behavior of the format set to the given value.
CSVFormat	withCommentMarker(char commentMarker) Returns a new CSVFormat with the comment start marker of the format set to the specified character.
CSVFormat	withCommentMarker(java.lang.Character commentMarker) Returns a new CSVFormat with the comment start marker of the format set to the specified character.
CSVFormat	withDelimiter(char delimiter) Returns a new CSVFormat with the delimiter of the format set to the specified character.
CSVFormat	withEscape(char escape) Returns a new CSVFormat with the escape character of the format set to the specified character.
CSVFormat	withEscape(java.lang.Character escape) Returns a new CSVFormat with the escape character of the format set to the specified character.
CSVFormat	withFirstRecordAsHeader() Returns a new CSVFormat using the first record as header.
CSVFormat	withHeader(java.lang.Class<? extends java.lang.Enum<?>> headerEnum) Returns a new CSVFormat with the header of the format defined by the enum class.
CSVFormat	withHeader(java.sql.ResultSet resultSet) Returns a new CSVFormat with the header of the format set from the result set metadata.
CSVFormat	withHeader(java.sql.ResultSetMetaData metaData) Returns a new CSVFormat with the header of the format set from the result set metadata.
CSVFormat	withHeader(java.lang.String... header) Returns a new CSVFormat with the header of the format set to the given values.
CSVFormat	withHeaderComments(java.lang.Object... headerComments) Returns a new CSVFormat with the header comments of the format set to the given values.
CSVFormat	withIgnoreEmptyLines() Returns a new CSVFormat with the empty line skipping behavior of the format set to true.
CSVFormat	withIgnoreEmptyLines(boolean ignoreEmptyLines) Returns a new CSVFormat with the empty line skipping behavior of the format set to the given value.
CSVFormat	withIgnoreHeaderCase() Returns a new CSVFormat with the header ignore case behavior set to true.
CSVFormat	withIgnoreHeaderCase(boolean ignoreHeaderCase) Returns a new CSVFormat with whether header names should be accessed ignoring case.
CSVFormat	withIgnoreSurroundingSpaces() Returns a new CSVFormat with the trimming behavior of the format set to true.
CSVFormat	withIgnoreSurroundingSpaces(boolean ignoreSurroundingSpaces) Returns a new CSVFormat with the trimming behavior of the format set to the given value.
CSVFormat	withNullString(java.lang.String nullString) Returns a new CSVFormat with conversions to and from null for strings on input and output.
CSVFormat	withQuote(char quoteChar) Returns a new CSVFormat with the quoteChar of the format set to the specified character.
CSVFormat	withQuote(java.lang.Character quoteChar) Returns a new CSVFormat with the quoteChar of the format set to the specified character.
CSVFormat	withQuoteMode(QuoteMode quoteModePolicy) Returns a new CSVFormat with the output quote policy of the format set to the specified value.
CSVFormat	withRecordSeparator(char recordSeparator) Returns a new CSVFormat with the record separator of the format set to the specified character.
CSVFormat	withRecordSeparator(java.lang.String recordSeparator) Returns a new CSVFormat with the record separator of the format set to the specified String.
CSVFormat	withSkipHeaderRecord() Returns a new CSVFormat with skipping the header record set to true.
CSVFormat	withSkipHeaderRecord(boolean skipHeaderRecord) Returns a new CSVFormat with whether to skip the header record.
CSVFormat	withTrailingDelimiter() Returns a new CSVFormat to add a trailing delimiter.
CSVFormat	withTrailingDelimiter(boolean trailingDelimiter) Returns a new CSVFormat with whether to add a trailing delimiter.
CSVFormat	withTrim() Returns a new CSVFormat to trim leading and trailing blanks.
CSVFormat	withTrim(boolean trim) Returns a new CSVFormat with whether to trim leading and trailing blanks.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT

public static final CSVFormat DEFAULT

Standard comma separated format, as for RFC4180 but allowing empty lines.

Settings are:

• withDelimiter(',')
• withQuote('"')
• withRecordSeparator("\r\n")
• withIgnoreEmptyLines(true)

See Also:

CSVFormat.Predefined.Default

EXCEL

public static final CSVFormat EXCEL

Excel file format (using a comma as the value delimiter). Note that the actual value delimiter used by Excel is locale dependent, it might be necessary to customize this format to accommodate to your regional settings.

For example for parsing or generating a CSV file on a French system the following format will be used:

 CSVFormat fmt = CSVFormat.EXCEL.withDelimiter(';');
 

Settings are:

• withDelimiter(',')
• withQuote('"')
• withRecordSeparator("\r\n")
• withIgnoreEmptyLines(false)
• withAllowMissingColumnNames(true)

Note: this is currently like RFC4180 plus withAllowMissingColumnNames(true).

See Also:

CSVFormat.Predefined.Excel

INFORMIX_UNLOAD

public static final CSVFormat INFORMIX_UNLOAD

Default Informix CSV UNLOAD format used by the UNLOAD TO file_name operation.

This is a comma-delimited format with a LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

Settings are:

• withDelimiter(',')
• withQuote("\"")
• withRecordSeparator('\n')
• withEscape('\\')

Since:

1.3

See Also:

CSVFormat.Predefined.MySQL, http://www.ibm.com/support/knowledgecenter/SSBJG3_2.5.0/com.ibm.gen_busug.doc/c_fgl_InOutSql_UNLOAD.htm

INFORMIX_UNLOAD_CSV

public static final CSVFormat INFORMIX_UNLOAD_CSV

Default Informix CSV UNLOAD format used by the UNLOAD TO file_name operation (escaping is disabled.)

This is a comma-delimited format with a LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

Settings are:

• withDelimiter(',')
• withQuote("\"")
• withRecordSeparator('\n')

Since:

1.3

See Also:

CSVFormat.Predefined.MySQL, http://www.ibm.com/support/knowledgecenter/SSBJG3_2.5.0/com.ibm.gen_busug.doc/c_fgl_InOutSql_UNLOAD.htm

MYSQL

public static final CSVFormat MYSQL

Default MySQL format used by the SELECT INTO OUTFILE and LOAD DATA INFILE operations.

This is a tab-delimited format with a LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

Settings are:

• withDelimiter('\t')
• withQuote(null)
• withRecordSeparator('\n')
• withIgnoreEmptyLines(false)
• withEscape('\\')
• withNullString("\\N")
• withQuoteMode(QuoteMode.ALL_NON_NULL)

See Also:

CSVFormat.Predefined.MySQL, http://dev.mysql.com/doc/refman/5.1/en/load -data.html

POSTGRESQL_CSV

public static final CSVFormat POSTGRESQL_CSV

Default PostgreSQL CSV format used by the COPY operation.

This is a comma-delimited format with a LF character as the line separator. Values are double quoted and special characters are escaped with '"'. The default NULL string is "".

Settings are:

• withDelimiter(',')
• withQuote('"')
• withRecordSeparator('\n')
• withIgnoreEmptyLines(false)
• withEscape('\\')
• withNullString("")
• withQuoteMode(QuoteMode.ALL_NON_NULL)

Since:

1.5

See Also:

CSVFormat.Predefined.MySQL, http://dev.mysql.com/doc/refman/5.1/en/load -data.html

POSTGRESQL_TEXT

public static final CSVFormat POSTGRESQL_TEXT

Default PostgreSQL text format used by the COPY operation.

This is a tab-delimited format with a LF character as the line separator. Values are double quoted and special characters are escaped with '"'. The default NULL string is "\\N".

Settings are:

• withDelimiter('\t')
• withQuote('"')
• withRecordSeparator('\n')
• withIgnoreEmptyLines(false)
• withEscape('\\')
• withNullString("\\N")
• withQuoteMode(QuoteMode.ALL_NON_NULL)

Since:

1.5

See Also:

CSVFormat.Predefined.MySQL, http://dev.mysql.com/doc/refman/5.1/en/load -data.html

RFC4180

public static final CSVFormat RFC4180

Comma separated format as defined by RFC 4180.

Settings are:

• withDelimiter(',')
• withQuote('"')
• withRecordSeparator("\r\n")
• withIgnoreEmptyLines(false)

See Also:

CSVFormat.Predefined.RFC4180

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

TDF

public static final CSVFormat TDF

Tab-delimited format.

Settings are:

• withDelimiter('\t')
• withQuote('"')
• withRecordSeparator("\r\n")
• withIgnoreSurroundingSpaces(true)

See Also:

CSVFormat.Predefined.TDF

allowMissingColumnNames

private final boolean allowMissingColumnNames

commentMarker

private final java.lang.Character commentMarker

delimiter

private final char delimiter

escapeCharacter

private final java.lang.Character escapeCharacter

header

private final java.lang.String[] header

headerComments

private final java.lang.String[] headerComments

ignoreEmptyLines

private final boolean ignoreEmptyLines

ignoreHeaderCase

private final boolean ignoreHeaderCase

ignoreSurroundingSpaces

private final boolean ignoreSurroundingSpaces

nullString

private final java.lang.String nullString

quoteCharacter

private final java.lang.Character quoteCharacter

quoteMode

private final QuoteMode quoteMode

recordSeparator

private final java.lang.String recordSeparator

skipHeaderRecord

private final boolean skipHeaderRecord

trailingDelimiter

private final boolean trailingDelimiter

trim

private final boolean trim

Constructor Detail

CSVFormat

private CSVFormat(char delimiter,
                  java.lang.Character quoteChar,
                  QuoteMode quoteMode,
                  java.lang.Character commentStart,
                  java.lang.Character escape,
                  boolean ignoreSurroundingSpaces,
                  boolean ignoreEmptyLines,
                  java.lang.String recordSeparator,
                  java.lang.String nullString,
                  java.lang.Object[] headerComments,
                  java.lang.String[] header,
                  boolean skipHeaderRecord,
                  boolean allowMissingColumnNames,
                  boolean ignoreHeaderCase,
                  boolean trim,
                  boolean trailingDelimiter)

Creates a customized CSV format.

Parameters:

delimiter - the char used for value separation, must not be a line break character

quoteChar - the Character used as value encapsulation marker, may be null to disable

quoteMode - the quote mode

commentStart - the Character used for comment identification, may be null to disable

escape - the Character used to escape special characters in values, may be null to disable

ignoreSurroundingSpaces - true when whitespaces enclosing values should be ignored

ignoreEmptyLines - true when the parser should skip empty lines

recordSeparator - the line separator to use for output

nullString - the line separator to use for output

headerComments - the comments to be printed by the Printer before the actual CSV data

header - the header

skipHeaderRecord - TODO

allowMissingColumnNames - TODO

ignoreHeaderCase - TODO

trim - TODO

trailingDelimiter - TODO

Throws:

java.lang.IllegalArgumentException - if the delimiter is a line break character

Method Detail

isLineBreak

private static boolean isLineBreak(char c)

Returns true if the given character is a line break character.

Parameters:

c - the character to check

Returns:

true if c is a line break character

isLineBreak

private static boolean isLineBreak(java.lang.Character c)

Returns true if the given character is a line break character.

Parameters:

c - the character to check, may be null

Returns:

true if c is a line break character (and not null)

newFormat

public static CSVFormat newFormat(char delimiter)

Creates a new CSV format with the specified delimiter.

Use this method if you want to create a CSVFormat from scratch. All fields but the delimiter will be initialized with null/false.

Parameters:

delimiter - the char used for value separation, must not be a line break character

Returns:

a new CSV format.

Throws:

java.lang.IllegalArgumentException - if the delimiter is a line break character

See Also:

DEFAULT, RFC4180, MYSQL, EXCEL, TDF

valueOf

public static CSVFormat valueOf(java.lang.String format)

Gets one of the predefined formats from CSVFormat.Predefined.

Parameters:

format - name

Returns:

one of the predefined formats

Since:

1.2

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

format

public java.lang.String format(java.lang.Object... values)

Formats the specified values.

Parameters:

values - the values to format

Returns:

the formatted values

getAllowMissingColumnNames

public boolean getAllowMissingColumnNames()

Specifies whether missing column names are allowed when parsing the header line.

Returns:

true if missing column names are allowed when parsing the header line, false to throw an IllegalArgumentException.

getCommentMarker

public java.lang.Character getCommentMarker()

Returns the character marking the start of a line comment.

Returns:

the comment start marker, may be null

getDelimiter

public char getDelimiter()

Returns the character delimiting the values (typically ';', ',' or '\t').

Returns:

the delimiter character

getEscapeCharacter

public java.lang.Character getEscapeCharacter()

Returns the escape character.

Returns:

the escape character, may be null

getHeader

public java.lang.String[] getHeader()

Returns a copy of the header array.

Returns:

a copy of the header array; null if disabled, the empty array if to be read from the file

getHeaderComments

public java.lang.String[] getHeaderComments()

Returns a copy of the header comment array.

Returns:

a copy of the header comment array; null if disabled.

getIgnoreEmptyLines

public boolean getIgnoreEmptyLines()

Specifies whether empty lines between records are ignored when parsing input.

Returns:

true if empty lines between records are ignored, false if they are turned into empty records.

getIgnoreHeaderCase

public boolean getIgnoreHeaderCase()

Specifies whether header names will be accessed ignoring case.

Returns:

true if header names cases are ignored, false if they are case sensitive.

Since:

1.3

getIgnoreSurroundingSpaces

public boolean getIgnoreSurroundingSpaces()

Specifies whether spaces around values are ignored when parsing input.

Returns:

true if spaces around values are ignored, false if they are treated as part of the value.

getNullString

public java.lang.String getNullString()

Gets the String to convert to and from null.

• Reading: Converts strings equal to the given nullString to null when reading records.
• Writing: Writes null as the given nullString when writing records.

Returns:

the String to convert to and from null. No substitution occurs if null

getQuoteCharacter

public java.lang.Character getQuoteCharacter()

Returns the character used to encapsulate values containing special characters.

Returns:

the quoteChar character, may be null

getQuoteMode

public QuoteMode getQuoteMode()

Returns the quote policy output fields.

Returns:

the quote policy

getRecordSeparator

public java.lang.String getRecordSeparator()

Returns the record separator delimiting output records.

Returns:

the record separator

getSkipHeaderRecord

public boolean getSkipHeaderRecord()

Returns whether to skip the header record.

Returns:

whether to skip the header record.

getTrailingDelimiter

public boolean getTrailingDelimiter()

Returns whether to add a trailing delimiter.

Returns:

whether to add a trailing delimiter.

Since:

1.3

getTrim

public boolean getTrim()

Returns whether to trim leading and trailing blanks.

Returns:

whether to trim leading and trailing blanks.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

isCommentMarkerSet

public boolean isCommentMarkerSet()

Specifies whether comments are supported by this format. Note that the comment introducer character is only recognized at the start of a line.

Returns:

true is comments are supported, false otherwise

isEscapeCharacterSet

public boolean isEscapeCharacterSet()

Returns whether escape are being processed.

Returns:

true if escapes are processed

isNullStringSet

public boolean isNullStringSet()

Returns whether a nullString has been defined.

Returns:

true if a nullString is defined

isQuoteCharacterSet

public boolean isQuoteCharacterSet()

Returns whether a quoteChar has been defined.

Returns:

true if a quoteChar is defined

parse

public CSVParser parse(java.io.Reader in)
                throws java.io.IOException

Parses the specified content.

See also the various static parse methods on CSVParser.

Parameters:

in - the input stream

Returns:

a parser over a stream of CSVRecords.

Throws:

java.io.IOException - If an I/O error occurs

print

public CSVPrinter print(java.lang.Appendable out)
                 throws java.io.IOException

Prints to the specified output.

See also CSVPrinter.

Parameters:

out - the output.

Returns:

a printer to an output.

Throws:

java.io.IOException - thrown if the optional header cannot be printed.

printer

public CSVPrinter printer()
                   throws java.io.IOException

Prints to the System.out.

See also CSVPrinter.

Returns:

a printer to System.out.

Throws:

java.io.IOException - thrown if the optional header cannot be printed.

Since:

1.5

print

public CSVPrinter print(java.io.File out,
                        java.nio.charset.Charset charset)
                 throws java.io.IOException

Prints to the specified output.

See also CSVPrinter.

Parameters:

out - the output.

charset - A charset.

Returns:

a printer to an output.

Throws:

java.io.IOException - thrown if the optional header cannot be printed.

Since:

1.5

print

public CSVPrinter print(java.nio.file.Path out,
                        java.nio.charset.Charset charset)
                 throws java.io.IOException

Prints to the specified output.

See also CSVPrinter.

Parameters:

out - the output.

charset - A charset.

Returns:

a printer to an output.

Throws:

java.io.IOException - thrown if the optional header cannot be printed.

Since:

1.5

print

public void print(java.lang.Object value,
                  java.lang.Appendable out,
                  boolean newRecord)
           throws java.io.IOException

Prints the value as the next value on the line to out. The value will be escaped or encapsulated as needed. Useful when one wants to avoid creating CSVPrinters.

Parameters:

value - value to output.

out - where to print the value.

newRecord - if this a new record.

Throws:

java.io.IOException - If an I/O error occurs.

Since:

1.4

print

private void print(java.lang.Object object,
                   java.lang.CharSequence value,
                   int offset,
                   int len,
                   java.lang.Appendable out,
                   boolean newRecord)
            throws java.io.IOException

Throws:

java.io.IOException

printAndEscape

private void printAndEscape(java.lang.CharSequence value,
                            int offset,
                            int len,
                            java.lang.Appendable out)
                     throws java.io.IOException

Throws:

java.io.IOException

printAndQuote

private void printAndQuote(java.lang.Object object,
                           java.lang.CharSequence value,
                           int offset,
                           int len,
                           java.lang.Appendable out,
                           boolean newRecord)
                    throws java.io.IOException

Throws:

java.io.IOException

println

public void println(java.lang.Appendable out)
             throws java.io.IOException

Outputs the trailing delimiter (if set) followed by the record separator (if set).

Parameters:

out - where to write

Throws:

java.io.IOException - If an I/O error occurs

Since:

1.4

printRecord

public void printRecord(java.lang.Appendable out,
                        java.lang.Object... values)
                 throws java.io.IOException

Prints the given values to out as a single record of delimiter separated values followed by the record separator.

The values will be quoted if needed. Quotes and new-line characters will be escaped. This method adds the record separator to the output after printing the record, so there is no need to call println(Appendable).

Parameters:

out - where to write.

values - values to output.

Throws:

java.io.IOException - If an I/O error occurs.

Since:

1.4

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toStringArray

private java.lang.String[] toStringArray(java.lang.Object[] values)

trim

private java.lang.CharSequence trim(java.lang.CharSequence charSequence)

validate

private void validate()
               throws java.lang.IllegalArgumentException

Verifies the consistency of the parameters and throws an IllegalArgumentException if necessary.

Throws:

java.lang.IllegalArgumentException

withAllowMissingColumnNames

public CSVFormat withAllowMissingColumnNames()

Returns a new CSVFormat with the missing column names behavior of the format set to true

Returns:

A new CSVFormat that is equal to this but with the specified missing column names behavior.

Since:

1.1

See Also:

withAllowMissingColumnNames(boolean)

withAllowMissingColumnNames

public CSVFormat withAllowMissingColumnNames(boolean allowMissingColumnNames)

Returns a new CSVFormat with the missing column names behavior of the format set to the given value.

Parameters:

allowMissingColumnNames - the missing column names behavior, true to allow missing column names in the header line, false to cause an IllegalArgumentException to be thrown.

Returns:

A new CSVFormat that is equal to this but with the specified missing column names behavior.

withCommentMarker

public CSVFormat withCommentMarker(char commentMarker)

Returns a new CSVFormat with the comment start marker of the format set to the specified character. Note that the comment start character is only recognized at the start of a line.

Parameters:

commentMarker - the comment start marker

Returns:

A new CSVFormat that is equal to this one but with the specified character as the comment start marker

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withCommentMarker

public CSVFormat withCommentMarker(java.lang.Character commentMarker)

Returns a new CSVFormat with the comment start marker of the format set to the specified character. Note that the comment start character is only recognized at the start of a line.

Parameters:

commentMarker - the comment start marker, use null to disable

Returns:

A new CSVFormat that is equal to this one but with the specified character as the comment start marker

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withDelimiter

public CSVFormat withDelimiter(char delimiter)

Returns a new CSVFormat with the delimiter of the format set to the specified character.

Parameters:

delimiter - the delimiter character

Returns:

A new CSVFormat that is equal to this with the specified character as delimiter

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withEscape

public CSVFormat withEscape(char escape)

Returns a new CSVFormat with the escape character of the format set to the specified character.

Parameters:

escape - the escape character

Returns:

A new CSVFormat that is equal to his but with the specified character as the escape character

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withEscape

public CSVFormat withEscape(java.lang.Character escape)

Returns a new CSVFormat with the escape character of the format set to the specified character.

Parameters:

escape - the escape character, use null to disable

Returns:

A new CSVFormat that is equal to this but with the specified character as the escape character

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withFirstRecordAsHeader

public CSVFormat withFirstRecordAsHeader()

Returns a new CSVFormat using the first record as header.

Calling this method is equivalent to calling:

 CSVFormat format = aFormat.withHeader().withSkipHeaderRecord();
 

Returns:

A new CSVFormat that is equal to this but using the first record as header.

Since:

1.3

See Also:

withSkipHeaderRecord(boolean), withHeader(String...)

withHeader

public CSVFormat withHeader(java.lang.Class<? extends java.lang.Enum<?>> headerEnum)

Returns a new CSVFormat with the header of the format defined by the enum class.

Example:

 public enum Header {
     Name, Email, Phone
 }

 CSVFormat format = aformat.withHeader(Header.class);
 

The header is also used by the CSVPrinter.

Parameters:

headerEnum - the enum defining the header, null if disabled, empty if parsed automatically, user specified otherwise.

Returns:

A new CSVFormat that is equal to this but with the specified header

Since:

1.3

See Also:

withHeader(String...), withSkipHeaderRecord(boolean)

withHeader

public CSVFormat withHeader(java.sql.ResultSet resultSet)
                     throws java.sql.SQLException

Returns a new CSVFormat with the header of the format set from the result set metadata. The header can either be parsed automatically from the input file with:

 CSVFormat format = aformat.withHeader();
 

or specified manually with:

 CSVFormat format = aformat.withHeader(resultSet);
 

The header is also used by the CSVPrinter.

Parameters:

resultSet - the resultSet for the header, null if disabled, empty if parsed automatically, user specified otherwise.

Returns:

A new CSVFormat that is equal to this but with the specified header

Throws:

java.sql.SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

Since:

1.1

withHeader

public CSVFormat withHeader(java.sql.ResultSetMetaData metaData)
                     throws java.sql.SQLException

Returns a new CSVFormat with the header of the format set from the result set metadata. The header can either be parsed automatically from the input file with:

 CSVFormat format = aformat.withHeader();
 

or specified manually with:

 CSVFormat format = aformat.withHeader(metaData);
 

The header is also used by the CSVPrinter.

Parameters:

metaData - the metaData for the header, null if disabled, empty if parsed automatically, user specified otherwise.

Returns:

A new CSVFormat that is equal to this but with the specified header

Throws:

java.sql.SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

Since:

1.1

withHeader

public CSVFormat withHeader(java.lang.String... header)

Returns a new CSVFormat with the header of the format set to the given values. The header can either be parsed automatically from the input file with:

 CSVFormat format = aformat.withHeader();
 

or specified manually with:

 CSVFormat format = aformat.withHeader("name", "email", "phone");
 

The header is also used by the CSVPrinter.

Parameters:

header - the header, null if disabled, empty if parsed automatically, user specified otherwise.

Returns:

A new CSVFormat that is equal to this but with the specified header

See Also:

withSkipHeaderRecord(boolean)

withHeaderComments

public CSVFormat withHeaderComments(java.lang.Object... headerComments)

Returns a new CSVFormat with the header comments of the format set to the given values. The comments will be printed first, before the headers. This setting is ignored by the parser.

 CSVFormat format = aformat.withHeaderComments("Generated by Apache Commons CSV 1.1.", new Date());
 

Parameters:

headerComments - the headerComments which will be printed by the Printer before the actual CSV data.

Returns:

A new CSVFormat that is equal to this but with the specified header

Since:

1.1

See Also:

withSkipHeaderRecord(boolean)

withIgnoreEmptyLines

public CSVFormat withIgnoreEmptyLines()

Returns a new CSVFormat with the empty line skipping behavior of the format set to true.

Returns:

A new CSVFormat that is equal to this but with the specified empty line skipping behavior.

Since:

withIgnoreEmptyLines(boolean), 1.1

withIgnoreEmptyLines

public CSVFormat withIgnoreEmptyLines(boolean ignoreEmptyLines)

Returns a new CSVFormat with the empty line skipping behavior of the format set to the given value.

Parameters:

ignoreEmptyLines - the empty line skipping behavior, true to ignore the empty lines between the records, false to translate empty lines to empty records.

Returns:

A new CSVFormat that is equal to this but with the specified empty line skipping behavior.

withIgnoreHeaderCase

public CSVFormat withIgnoreHeaderCase()

Returns a new CSVFormat with the header ignore case behavior set to true.

Returns:

A new CSVFormat that will ignore case header name.

Since:

1.3

See Also:

withIgnoreHeaderCase(boolean)

withIgnoreHeaderCase

public CSVFormat withIgnoreHeaderCase(boolean ignoreHeaderCase)

Returns a new CSVFormat with whether header names should be accessed ignoring case.

Parameters:

ignoreHeaderCase - the case mapping behavior, true to access name/values, false to leave the mapping as is.

Returns:

A new CSVFormat that will ignore case header name if specified as true

Since:

1.3

withIgnoreSurroundingSpaces

public CSVFormat withIgnoreSurroundingSpaces()

Returns a new CSVFormat with the trimming behavior of the format set to true.

Returns:

A new CSVFormat that is equal to this but with the specified trimming behavior.

Since:

1.1

See Also:

withIgnoreSurroundingSpaces(boolean)

withIgnoreSurroundingSpaces

public CSVFormat withIgnoreSurroundingSpaces(boolean ignoreSurroundingSpaces)

Returns a new CSVFormat with the trimming behavior of the format set to the given value.

Parameters:

ignoreSurroundingSpaces - the trimming behavior, true to remove the surrounding spaces, false to leave the spaces as is.

Returns:

A new CSVFormat that is equal to this but with the specified trimming behavior.

withNullString

public CSVFormat withNullString(java.lang.String nullString)

Returns a new CSVFormat with conversions to and from null for strings on input and output.

• Reading: Converts strings equal to the given nullString to null when reading records.
• Writing: Writes null as the given nullString when writing records.

Parameters:

nullString - the String to convert to and from null. No substitution occurs if null

Returns:

A new CSVFormat that is equal to this but with the specified null conversion string.

withQuote

public CSVFormat withQuote(char quoteChar)

Returns a new CSVFormat with the quoteChar of the format set to the specified character.

Parameters:

quoteChar - the quoteChar character

Returns:

A new CSVFormat that is equal to this but with the specified character as quoteChar

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withQuote

public CSVFormat withQuote(java.lang.Character quoteChar)

Returns a new CSVFormat with the quoteChar of the format set to the specified character.

Parameters:

quoteChar - the quoteChar character, use null to disable

Returns:

A new CSVFormat that is equal to this but with the specified character as quoteChar

Throws:

java.lang.IllegalArgumentException - thrown if the specified character is a line break

withQuoteMode

public CSVFormat withQuoteMode(QuoteMode quoteModePolicy)

Returns a new CSVFormat with the output quote policy of the format set to the specified value.

Parameters:

quoteModePolicy - the quote policy to use for output.

Returns:

A new CSVFormat that is equal to this but with the specified quote policy

withRecordSeparator

public CSVFormat withRecordSeparator(char recordSeparator)

Returns a new CSVFormat with the record separator of the format set to the specified character.

Note: This setting is only used during printing and does not affect parsing. Parsing currently only works for inputs with '\n', '\r' and "\r\n"

Parameters:

recordSeparator - the record separator to use for output.

Returns:

A new CSVFormat that is equal to this but with the the specified output record separator

withRecordSeparator

public CSVFormat withRecordSeparator(java.lang.String recordSeparator)

Returns a new CSVFormat with the record separator of the format set to the specified String.

Note: This setting is only used during printing and does not affect parsing. Parsing currently only works for inputs with '\n', '\r' and "\r\n"

Parameters:

recordSeparator - the record separator to use for output.

Returns:

A new CSVFormat that is equal to this but with the the specified output record separator

Throws:

java.lang.IllegalArgumentException - if recordSeparator is none of CR, LF or CRLF

withSkipHeaderRecord

public CSVFormat withSkipHeaderRecord()

Returns a new CSVFormat with skipping the header record set to true.

Returns:

A new CSVFormat that is equal to this but with the the specified skipHeaderRecord setting.

Since:

1.1

See Also:

withSkipHeaderRecord(boolean), withHeader(String...)

withSkipHeaderRecord

public CSVFormat withSkipHeaderRecord(boolean skipHeaderRecord)

Returns a new CSVFormat with whether to skip the header record.

Parameters:

skipHeaderRecord - whether to skip the header record.

Returns:

A new CSVFormat that is equal to this but with the the specified skipHeaderRecord setting.

See Also:

withHeader(String...)

withTrailingDelimiter

public CSVFormat withTrailingDelimiter()

Returns a new CSVFormat to add a trailing delimiter.

Returns:

A new CSVFormat that is equal to this but with the trailing delimiter setting.

Since:

1.3

withTrailingDelimiter

public CSVFormat withTrailingDelimiter(boolean trailingDelimiter)

Returns a new CSVFormat with whether to add a trailing delimiter.

Parameters:

trailingDelimiter - whether to add a trailing delimiter.

Returns:

A new CSVFormat that is equal to this but with the specified trailing delimiter setting.

Since:

1.3

withTrim

public CSVFormat withTrim()

Returns a new CSVFormat to trim leading and trailing blanks.

Returns:

A new CSVFormat that is equal to this but with the trim setting on.

Since:

1.3

withTrim

public CSVFormat withTrim(boolean trim)

Returns a new CSVFormat with whether to trim leading and trailing blanks.

Parameters:

trim - whether to trim leading and trailing blanks.

Returns:

A new CSVFormat that is equal to this but with the specified trim setting.

Since:

1.3