Package org.apache.commons.csv

Class CSVFormat

java.lang.Object
org.apache.commons.csv.CSVFormat
All Implemented Interfaces:
Serializable
public final class CSVFormat extends Object implements Serializable
Specifies the format of a CSV file for parsing and writing.

Using predefined formats

You can use one of the predefined formats:

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 set 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 CSVFormat.Builder.setHeader(String...) lets 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 CSVFormat.Builder.setSkipHeaderRecord(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 CSVFormat.Builder.setHeader(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.

Serialization

This class implements the Serializable interface with the following caveats:

  • This class will no longer implement Serializable in 2.0.
  • Serialization is not supported from one version to the next.

The serialVersionUID values are:

  • Version 1.10.0: 2L
  • Version 1.9.0 through 1.0: 1L

Notes

This class is immutable.

Not all settings are used for both parsing and writing.

See Also:

  • Field Details

    • DEFAULT

      public static final CSVFormat DEFAULT
      Standard Comma Separated Value format, as for RFC4180 but allowing empty lines.

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setQuote('"')
      • setRecordSeparator("\r\n")
      • setIgnoreEmptyLines(true)
      • setDuplicateHeaderMode(DuplicateHeaderMode.ALLOW_ALL)
      See Also:

    • 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 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(';');

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setQuote('"')
      • setRecordSeparator("\r\n")
      • setDuplicateHeaderMode(DuplicateHeaderMode.ALLOW_ALL)
      • setIgnoreEmptyLines(false)
      • setAllowMissingColumnNames(true)
      • setTrailingData(true)
      • setLenientEof(true)

      Note: This is currently like RFC4180 plus Builder#setAllowMissingColumnNames(true) and Builder#setIgnoreEmptyLines(false).

      See Also:

    • 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 an LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setEscape('\\')
      • setQuote("\"")
      • setRecordSeparator('\n')
      Since:
      1.3
      See Also:

    • 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 an LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setQuote("\"")
      • setRecordSeparator('\n')
      Since:
      1.3
      See Also:

    • MONGODB_CSV

      public static final CSVFormat MONGODB_CSV
      Default MongoDB CSV format used by the mongoexport operation.

      Parsing is not supported yet.

      This is a comma-delimited format. Values are double quoted only if needed and special characters are escaped with '"'. A header line with field names is expected.

      As of 2024-04-05, the MongoDB documentation for mongoimport states:

      The csv parser accepts that data that complies with RFC RFC-4180. As a result, backslashes are not a valid escape character. If you use double-quotes to enclose fields in the CSV data, you must escape internal double-quote marks by prepending another double-quote.

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setEscape('"')
      • setQuote('"')
      • setQuoteMode(QuoteMode.ALL_NON_NULL)
      • setSkipHeaderRecord(false)
      Since:
      1.7
      See Also:

    • MONGODB_TSV

      public static final CSVFormat MONGODB_TSV
      Default MongoDB TSV format used by the mongoexport operation.

      Parsing is not supported yet.

      This is a tab-delimited format. Values are double quoted only if needed and special characters are escaped with '"'. A header line with field names is expected.

      The CSVFormat.Builder settings are:

      • setDelimiter('\t')
      • setEscape('"')
      • setQuote('"')
      • setQuoteMode(QuoteMode.ALL_NON_NULL)
      • setSkipHeaderRecord(false)
      Since:
      1.7
      See Also:

    • 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 an LF character as the line separator. Values are not quoted and special characters are escaped with '\'. The default NULL string is "\\N".

      The CSVFormat.Builder settings are:

      • setDelimiter('\t')
      • setEscape('\\')
      • setIgnoreEmptyLines(false)
      • setQuote(null)
      • setRecordSeparator('\n')
      • setNullString("\\N")
      • setQuoteMode(QuoteMode.ALL_NON_NULL)
      See Also:

    • ORACLE

      public static final CSVFormat ORACLE
      Default Oracle format used by the SQL*Loader utility.

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

      The CSVFormat.Builder settings are:

      • setDelimiter(',') // default is {@code FIELDS TERMINATED BY ','}
      • setEscape('\\')
      • setIgnoreEmptyLines(false)
      • setQuote('"') // default is {@code OPTIONALLY ENCLOSED BY '"'}
      • setNullString("\\N")
      • setTrim()
      • setSystemRecordSeparator()
      • setQuoteMode(QuoteMode.MINIMAL)
      Since:
      1.6
      See Also:

    • POSTGRESQL_CSV

      public static final CSVFormat POSTGRESQL_CSV
      Default PostgreSQL CSV format used by the COPY operation.

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

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setEscape(null)
      • setIgnoreEmptyLines(false)
      • setQuote('"')
      • setRecordSeparator('\n')
      • setNullString("")
      • setQuoteMode(QuoteMode.ALL_NON_NULL)
      Since:
      1.5
      See Also:

    • POSTGRESQL_TEXT

      public static final CSVFormat POSTGRESQL_TEXT
      Default PostgreSQL text format used by the COPY operation.

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

      The CSVFormat.Builder settings are:

      • setDelimiter('\t')
      • setEscape('\\')
      • setIgnoreEmptyLines(false)
      • setQuote(null)
      • setRecordSeparator('\n')
      • setNullString("\\N")
      • setQuoteMode(QuoteMode.ALL_NON_NULL)
      Since:
      1.5
      See Also:

    • RFC4180

      public static final CSVFormat RFC4180
      Comma separated format as defined by RFC 4180.

      The CSVFormat.Builder settings are:

      • setDelimiter(',')
      • setQuote('"')
      • setRecordSeparator("\r\n")
      • setIgnoreEmptyLines(false)
      See Also:

    • TDF

      public static final CSVFormat TDF
      Tab-delimited format.

      The CSVFormat.Builder settings are:

      • setDelimiter('\t')
      • setQuote('"')
      • setRecordSeparator("\r\n")
      • setIgnoreSurroundingSpaces(true)
      See Also:

  • Method Details

    • 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:
      IllegalArgumentException - if the delimiter is a line break character
      See Also:

    • valueOf

      public static CSVFormat valueOf(String format)
      Gets one of the predefined formats from CSVFormat.Predefined.
      Parameters:
      format - name
      Returns:
      one of the predefined formats
      Since:
      1.2

    • builder

      public CSVFormat.Builder builder()
      Creates a new Builder for this instance.
      Returns:
      a new Builder.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • format

      public String format(Object... values)
      Formats the specified values.
      Parameters:
      values - the values to format
      Returns:
      the formatted values

    • getAllowDuplicateHeaderNames

      @Deprecated public boolean getAllowDuplicateHeaderNames()
      Deprecated.
      Use getDuplicateHeaderMode().
      Gets whether duplicate names are allowed in the headers.
      Returns:
      whether duplicate header names are allowed
      Since:
      1.7

    • getAllowMissingColumnNames

      public boolean getAllowMissingColumnNames()
      Gets 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.

    • getAutoFlush

      public boolean getAutoFlush()
      Gets whether to flush on close.
      Returns:
      whether to flush on close.
      Since:
      1.6

    • getCommentMarker

      public Character getCommentMarker()
      Gets the comment marker character, null disables comments.

      The comment start character is only recognized at the start of a line.

      Comments are printed first, before headers.

      Use CSVFormat.Builder.setCommentMarker(char) or CSVFormat.Builder.setCommentMarker(Character) to set the comment marker written at the start of each comment line.

      If the comment marker is not set, then the header comments are ignored.

      For example: 

       builder.setCommentMarker('#')
        .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));

      writes: 

       # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z
      Returns:
      the comment start marker, may be null

    • getDelimiter

      @Deprecated public char getDelimiter()
      Deprecated.
      Use getDelimiterString().
      Gets the first character delimiting the values (typically ';', ',' or '\t').
      Returns:
      the first delimiter character.

    • getDelimiterString

      public String getDelimiterString()
      Gets the character delimiting the values (typically ";", "," or "\t").
      Returns:
      the delimiter.
      Since:
      1.9.0

    • getDuplicateHeaderMode

      public DuplicateHeaderMode getDuplicateHeaderMode()
      Gets how duplicate headers are handled.
      Returns:
      if duplicate header values are allowed, allowed conditionally, or disallowed.
      Since:
      1.10.0

    • getEscapeCharacter

      public Character getEscapeCharacter()
      Gets the escape character.
      Returns:
      the escape character, may be null

    • getHeader

      public String[] getHeader()
      Gets 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 String[] getHeaderComments()
      Gets a copy of the header comment array to write before the CSV data.

      This setting is ignored by the parser.

      Comments are printed first, before headers.

      Use CSVFormat.Builder.setCommentMarker(char) or CSVFormat.Builder.setCommentMarker(Character) to set the comment marker written at the start of each comment line.

      If the comment marker is not set, then the header comments are ignored.

      For example: 

       builder.setCommentMarker('#')
        .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));

      writes: 

       # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z
      Returns:
      a copy of the header comment array; null if disabled.

    • getIgnoreEmptyLines

      public boolean getIgnoreEmptyLines()
      Gets 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()
      Gets whether header names will be accessed ignoring case when parsing input.
      Returns:
      true if header names cases are ignored, false if they are case-sensitive.
      Since:
      1.3

    • getIgnoreSurroundingSpaces

      public boolean getIgnoreSurroundingSpaces()
      Gets 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.

    • getLenientEof

      public boolean getLenientEof()
      Gets whether reading end-of-file is allowed even when input is malformed, helps Excel compatibility.
      Returns:
      whether reading end-of-file is allowed even when input is malformed, helps Excel compatibility.
      Since:
      1.11.0

    • getNullString

      public 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 Character getQuoteCharacter()
      Gets the character used to encapsulate values containing special characters.
      Returns:
      the quoteChar character, may be null

    • getQuoteMode

      public QuoteMode getQuoteMode()
      Gets the quote policy output fields.
      Returns:
      the quote policy

    • getRecordSeparator

      public String getRecordSeparator()
      Gets the record separator delimiting output records.
      Returns:
      the record separator

    • getSkipHeaderRecord

      public boolean getSkipHeaderRecord()
      Gets whether to skip the header record.
      Returns:
      whether to skip the header record.

    • getTrailingData

      public boolean getTrailingData()
      Gets whether reading trailing data is allowed in records, helps Excel compatibility.
      Returns:
      whether reading trailing data is allowed in records, helps Excel compatibility.
      Since:
      1.11.0

    • getTrailingDelimiter

      public boolean getTrailingDelimiter()
      Gets whether to add a trailing delimiter.
      Returns:
      whether to add a trailing delimiter.
      Since:
      1.3

    • getTrim

      public boolean getTrim()
      Gets whether to trim leading and trailing blanks. This is used by print(Object, Appendable, boolean) Also by {CSVParser#addRecordValue(boolean)}
      Returns:
      whether to trim leading and trailing blanks.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isCommentMarkerSet

      public boolean isCommentMarkerSet()
      Tests 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()
      Tests whether escapes are being processed.
      Returns:
      true if escapes are processed

    • isNullStringSet

      public boolean isNullStringSet()
      Tests whether a null string has been defined.
      Returns:
      true if a nullString is defined

    • isQuoteCharacterSet

      public boolean isQuoteCharacterSet()
      Tests whether a quoteChar has been defined.
      Returns:
      true if a quoteChar is defined

    • parse

      public CSVParser parse(Reader reader) throws IOException
      Parses the specified content.

      See also the various static parse methods on CSVParser.

      Parameters:
      reader - the input stream
      Returns:
      a parser over a stream of CSVRecords.
      Throws:
      IOException - If an I/O error occurs
      CSVException - Thrown on invalid input.

    • print

      public CSVPrinter print(Appendable out) throws IOException
      Prints to the specified output.

      See also CSVPrinter.

      Parameters:
      out - the output.
      Returns:
      a printer to an output.
      Throws:
      IOException - thrown if the optional header cannot be printed.

    • print

      public CSVPrinter print(File out, Charset charset) throws IOException
      Prints to the specified File with given Charset.

      See also CSVPrinter.

      Parameters:
      out - the output.
      charset - A charset.
      Returns:
      a printer to an output.
      Throws:
      IOException - thrown if the optional header cannot be printed.
      Since:
      1.5

    • print

      public void print(Object value, Appendable out, boolean newRecord) throws 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. Trims the value if getTrim() is true.
      Parameters:
      value - value to output.
      out - where to print the value.
      newRecord - if this a new record.
      Throws:
      IOException - If an I/O error occurs.
      Since:
      1.4

    • print

      public CSVPrinter print(Path out, Charset charset) throws IOException
      Prints to the specified Path with given Charset, returns a CSVPrinter which the caller MUST close.

      See also CSVPrinter.

      Parameters:
      out - the output.
      charset - A charset.
      Returns:
      a printer to an output.
      Throws:
      IOException - thrown if the optional header cannot be printed.
      Since:
      1.5

    • printer

      public CSVPrinter printer() throws IOException
      Prints to the System.out.

      See also CSVPrinter.

      Returns:
      a printer to System.out.
      Throws:
      IOException - thrown if the optional header cannot be printed.
      Since:
      1.5

    • println

      public void println(Appendable appendable) throws IOException
      Outputs the trailing delimiter (if set) followed by the record separator (if set).
      Parameters:
      appendable - where to write
      Throws:
      IOException - If an I/O error occurs.
      Since:
      1.4

    • printRecord

      public void printRecord(Appendable appendable, Object... values) throws 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:
      appendable - where to write.
      values - values to output.
      Throws:
      IOException - If an I/O error occurs.
      Since:
      1.4

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • withAllowDuplicateHeaderNames

      @Deprecated public CSVFormat withAllowDuplicateHeaderNames()
      Deprecated.
      Use Builder#setAllowDuplicateHeaderNames(true)
      Builds a new CSVFormat that allows duplicate header names.
      Returns:
      a new CSVFormat that allows duplicate header names
      Since:
      1.7

    • withAllowDuplicateHeaderNames

      @Deprecated public CSVFormat withAllowDuplicateHeaderNames(boolean allowDuplicateHeaderNames)
      Deprecated.
      Use CSVFormat.Builder.setAllowDuplicateHeaderNames(boolean)
      Builds a new CSVFormat with duplicate header names behavior set to the given value.
      Parameters:
      allowDuplicateHeaderNames - the duplicate header names behavior, true to allow, false to disallow.
      Returns:
      a new CSVFormat with duplicate header names behavior set to the given value.
      Since:
      1.7

    • withAllowMissingColumnNames

      @Deprecated public CSVFormat withAllowMissingColumnNames()
      Deprecated.
      Use Builder#setAllowMissingColumnNames(true)
      Builds 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

      @Deprecated public CSVFormat withAllowMissingColumnNames(boolean allowMissingColumnNames)
      Deprecated.
      Use CSVFormat.Builder.setAllowMissingColumnNames(boolean)
      Builds 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.

    • withAutoFlush

      @Deprecated public CSVFormat withAutoFlush(boolean autoFlush)
      Deprecated.
      Use CSVFormat.Builder.setAutoFlush(boolean)
      Builds a new CSVFormat with whether to flush on close.
      Parameters:
      autoFlush - whether to flush on close.
      Returns:
      A new CSVFormat that is equal to this but with the specified autoFlush setting.
      Since:
      1.6

    • withCommentMarker

      @Deprecated public CSVFormat withCommentMarker(char commentMarker)
      Deprecated.
      Use CSVFormat.Builder.setCommentMarker(char)
      Builds 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:
      IllegalArgumentException - thrown if the specified character is a line break

    • withCommentMarker

      @Deprecated public CSVFormat withCommentMarker(Character commentMarker)
      Deprecated.
      Use CSVFormat.Builder.setCommentMarker(Character)
      Builds 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:
      IllegalArgumentException - thrown if the specified character is a line break

    • withDelimiter

      @Deprecated public CSVFormat withDelimiter(char delimiter)
      Deprecated.
      Use CSVFormat.Builder.setDelimiter(char)
      Builds 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 a delimiter
      Throws:
      IllegalArgumentException - thrown if the specified character is a line break

    • withEscape

      @Deprecated public CSVFormat withEscape(char escape)
      Deprecated.
      Use CSVFormat.Builder.setEscape(char)
      Builds 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 this but with the specified character as the escape character
      Throws:
      IllegalArgumentException - thrown if the specified character is a line break

    • withEscape

      @Deprecated public CSVFormat withEscape(Character escape)
      Deprecated.
      Use CSVFormat.Builder.setEscape(Character)
      Builds 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:
      IllegalArgumentException - thrown if the specified character is a line break

    • withFirstRecordAsHeader

      @Deprecated public CSVFormat withFirstRecordAsHeader()
      Deprecated.
      Use Builder#setHeader().setSkipHeaderRecord(true).
      Builds 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:

    • withHeader

      @Deprecated public CSVFormat withHeader(Class<? extends Enum<?>> headerEnum)
      Deprecated.
      Use CSVFormat.Builder.setHeader(Class)
      Builds 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

      @Deprecated public CSVFormat withHeader(ResultSet resultSet) throws SQLException
      Deprecated.
      Use CSVFormat.Builder.setHeader(ResultSet)
      Builds 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:
      SQLException - SQLException if a database access error occurs or this method is called on a closed result set.
      Since:
      1.1

    • withHeader

      @Deprecated public CSVFormat withHeader(ResultSetMetaData resultSetMetaData) throws SQLException
      Deprecated.
      Use CSVFormat.Builder.setHeader(ResultSetMetaData)
      Builds 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:
      resultSetMetaData - 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:
      SQLException - SQLException if a database access error occurs or this method is called on a closed result set.
      Since:
      1.1

    • withHeader

      @Deprecated public CSVFormat withHeader(String... header)
      Deprecated.
      Use CSVFormat.Builder.setHeader(String...)
      Builds 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:

    • withHeaderComments

      @Deprecated public CSVFormat withHeaderComments(Object... headerComments)
      Deprecated.
      Use CSVFormat.Builder.setHeaderComments(Object...)
      Builds 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.", Instant.now());
      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:

    • withIgnoreEmptyLines

      @Deprecated public CSVFormat withIgnoreEmptyLines()
      Deprecated.
      Use Builder#setIgnoreEmptyLines(true)
      Builds 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:
      1.1
      See Also:

    • withIgnoreEmptyLines

      @Deprecated public CSVFormat withIgnoreEmptyLines(boolean ignoreEmptyLines)
      Deprecated.
      Use CSVFormat.Builder.setIgnoreEmptyLines(boolean)
      Builds 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

      @Deprecated public CSVFormat withIgnoreHeaderCase()
      Deprecated.
      Use Builder#setIgnoreHeaderCase(true)
      Builds a new CSVFormat with the header ignore case behavior set to true.
      Returns:
      A new CSVFormat that will ignore the new case header name behavior.
      Since:
      1.3
      See Also:

    • withIgnoreHeaderCase

      @Deprecated public CSVFormat withIgnoreHeaderCase(boolean ignoreHeaderCase)
      Deprecated.
      Use CSVFormat.Builder.setIgnoreHeaderCase(boolean)
      Builds 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

      @Deprecated public CSVFormat withIgnoreSurroundingSpaces()
      Deprecated.
      Use Builder#setIgnoreSurroundingSpaces(true)
      Builds a new CSVFormat with the parser trimming behavior of the format set to true.
      Returns:
      A new CSVFormat that is equal to this but with the specified parser trimming behavior.
      Since:
      1.1
      See Also:

    • withIgnoreSurroundingSpaces

      @Deprecated public CSVFormat withIgnoreSurroundingSpaces(boolean ignoreSurroundingSpaces)
      Deprecated.
      Use CSVFormat.Builder.setIgnoreSurroundingSpaces(boolean)
      Builds a new CSVFormat with the parser trimming behavior of the format set to the given value.
      Parameters:
      ignoreSurroundingSpaces - the parser 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

      @Deprecated public CSVFormat withNullString(String nullString)
      Deprecated.
      Use CSVFormat.Builder.setNullString(String)
      Builds 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

      @Deprecated public CSVFormat withQuote(char quoteChar)
      Deprecated.
      Use CSVFormat.Builder.setQuote(char)
      Builds a new CSVFormat with the quoteChar of the format set to the specified character.
      Parameters:
      quoteChar - the quote character
      Returns:
      A new CSVFormat that is equal to this but with the specified character as quoteChar
      Throws:
      IllegalArgumentException - thrown if the specified character is a line break

    • withQuote

      @Deprecated public CSVFormat withQuote(Character quoteChar)
      Deprecated.
      Use CSVFormat.Builder.setQuote(Character)
      Builds a new CSVFormat with the quoteChar of the format set to the specified character.
      Parameters:
      quoteChar - the quote character, use null to disable.
      Returns:
      A new CSVFormat that is equal to this but with the specified character as quoteChar
      Throws:
      IllegalArgumentException - thrown if the specified character is a line break

    • withQuoteMode

      @Deprecated public CSVFormat withQuoteMode(QuoteMode quoteMode)
      Deprecated.
      Use CSVFormat.Builder.setQuoteMode(QuoteMode)
      Builds a new CSVFormat with the output quote policy of the format set to the specified value.
      Parameters:
      quoteMode - the quote policy to use for output.
      Returns:
      A new CSVFormat that is equal to this but with the specified quote policy

    • withRecordSeparator

      @Deprecated public CSVFormat withRecordSeparator(char recordSeparator)
      Deprecated.
      Use CSVFormat.Builder.setRecordSeparator(char)
      Builds 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 specified output record separator

    • withRecordSeparator

      @Deprecated public CSVFormat withRecordSeparator(String recordSeparator)
      Deprecated.
      Use CSVFormat.Builder.setRecordSeparator(String)
      Builds 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 specified output record separator
      Throws:
      IllegalArgumentException - if recordSeparator is none of CR, LF or CRLF

    • withSkipHeaderRecord

      @Deprecated public CSVFormat withSkipHeaderRecord()
      Deprecated.
      Use Builder#setSkipHeaderRecord(true)
      Builds a new CSVFormat with skipping the header record set to true.
      Returns:
      A new CSVFormat that is equal to this but with the specified skipHeaderRecord setting.
      Since:
      1.1
      See Also:

    • withSkipHeaderRecord

      @Deprecated public CSVFormat withSkipHeaderRecord(boolean skipHeaderRecord)
      Deprecated.
      Use CSVFormat.Builder.setSkipHeaderRecord(boolean)
      Builds 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 specified skipHeaderRecord setting.
      See Also:

    • withSystemRecordSeparator

      @Deprecated public CSVFormat withSystemRecordSeparator()
      Deprecated.
      Use setRecordSeparator(System.lineSeparator())
      Builds a new CSVFormat with the record separator of the format set to the operating system's line separator string, typically CR+LF on Windows and LF on Linux.

      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"

      Returns:
      A new CSVFormat that is equal to this but with the operating system's line separator string.
      Since:
      1.6

    • withTrailingDelimiter

      @Deprecated public CSVFormat withTrailingDelimiter()
      Deprecated.
      Use Builder#setTrailingDelimiter(true)
      Builds 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

      @Deprecated public CSVFormat withTrailingDelimiter(boolean trailingDelimiter)
      Deprecated.
      Use CSVFormat.Builder.setTrailingDelimiter(boolean)
      Builds 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

      @Deprecated public CSVFormat withTrim()
      Deprecated.
      Use Builder#setTrim(true)
      Builds a new CSVFormat to trim leading and trailing blanks. See getTrim() for details of where this is used.
      Returns:
      A new CSVFormat that is equal to this but with the trim setting on.
      Since:
      1.3

    • withTrim

      @Deprecated public CSVFormat withTrim(boolean trim)
      Deprecated.
      Use CSVFormat.Builder.setTrim(boolean)
      Builds a new CSVFormat with whether to trim leading and trailing blanks. See getTrim() for details of where this is used.
      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