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 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
    --- | ---
    `static CSVFormat` | `DEFAULT` Standard comma separated format, as for `RFC4180` but allowing empty lines.
    `static CSVFormat` | `EXCEL` Excel file format (using a comma as the value delimiter).
    `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.
    `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.
    `static CSVFormat` | `RFC4180` Comma separated format as defined by RFC 4180.
    `static CSVFormat` | `TDF` Tab-delimited format.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object obj)`
    `String` | `format(Object... values)` Formats the specified values.
    `boolean` | `getAllowMissingColumnNames()` Specifies whether missing column names are allowed when parsing the header line.
    `Character` | `getCommentMarker()` Returns the character marking the start of a line comment.
    `char` | `getDelimiter()` Returns the character delimiting the values (typically ';', ',' or '\t').
    `Character` | `getEscapeCharacter()` Returns the escape character.
    `String[]` | `getHeader()` Returns a copy of the header array.
    `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.
    `String` | `getNullString()` Gets the String to convert to and from `null`.
    `Character` | `getQuoteCharacter()` Returns the character used to encapsulate values containing special characters.
    `QuoteMode` | `getQuoteMode()` Returns the quote policy output fields.
    `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.
    `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(Reader in)` Parses the specified content.
    `CSVPrinter` | `print(Appendable out)` Prints to the specified output.
    `CSVPrinter` | `print(File out, Charset charset)` Prints to the specified output.
    `void` | `print(Object value, Appendable out, boolean newRecord)` Prints the `value` as the next value on the line to `out`.
    `CSVPrinter` | `print(Path out, Charset charset)` Prints to the specified output.
    `CSVPrinter` | `printer()` Prints to the `System.out`.
    `void` | `println(Appendable out)` Outputs the trailing delimiter (if set) followed by the record separator (if set).
    `void` | `printRecord(Appendable out, Object... values)` Prints the given `values` to `out` as a single record of delimiter separated values followed by the record separator.
    `String` | `toString()`
    `static CSVFormat` | `valueOf(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(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(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(Class<? extends Enum<?>> headerEnum)` Returns a new `CSVFormat` with the header of the format defined by the enum class.
    `CSVFormat` | `withHeader(ResultSet resultSet)` Returns a new `CSVFormat` with the header of the format set from the result set metadata.
    `CSVFormat` | `withHeader(ResultSetMetaData metaData)` Returns a new `CSVFormat` with the header of the format set from the result set metadata.
    `CSVFormat` | `withHeader(String... header)` Returns a new `CSVFormat` with the header of the format set to the given values.
    `CSVFormat` | `withHeaderComments(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(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(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(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`

    - #### TDF

          public static final CSVFormat TDF

      Tab-delimited format.

      Settings are:

      - withDelimiter('\t')
      - withQuote('"')
      - withRecordSeparator("\r\n")
      - withIgnoreSurroundingSpaces(true)
      See Also:
        `CSVFormat.Predefined.TDF`

  - ### Method Detail

    - #### 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:
        `DEFAULT`, `RFC4180`, `MYSQL`, `EXCEL`, `TDF`

    - #### 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

    - #### 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

    - #### 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 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 Character getEscapeCharacter()

      Returns the escape character.
      Returns:
        the escape character, may be `null`

    - #### getHeader

          public 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 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 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()

      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 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 `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(Reader in)
                          throws 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 `CSVRecord`s.
      Throws:
        `IOException` - If an I/O error occurs

    - #### 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.

    - #### 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

    - #### print

          public CSVPrinter print(File out,
                                  Charset charset)
                           throws IOException

      Prints to the specified output.

      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 CSVPrinter print(Path out,
                                  Charset charset)
                           throws IOException

      Prints to the specified output.

      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.
      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

    - #### println

          public void println(Appendable out)
                       throws IOException

      Outputs the trailing delimiter (if set) followed by the record separator (if set).
      Parameters:
        `out` - where to write
      Throws:
        `IOException` - If an I/O error occurs
      Since:
        1.4

    - #### printRecord

          public void printRecord(Appendable out,
                                  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:
        `out` - 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`

    - #### 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:
        `IllegalArgumentException` - thrown if the specified character is a line break

    - #### withCommentMarker

          public CSVFormat withCommentMarker(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:
        `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:
        `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:
        `IllegalArgumentException` - thrown if the specified character is a line break

    - #### withEscape

          public CSVFormat withEscape(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:
        `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(Class<? extends 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(ResultSet resultSet)
                               throws 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:
        `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(ResultSetMetaData metaData)
                               throws 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:
        `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(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(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(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:
        `IllegalArgumentException` - thrown if the specified character is a line break

    - #### withQuote

          public CSVFormat withQuote(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:
        `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(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:
        `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

Copyright © 2017 The Apache Software Foundation. All rights reserved.