Class 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:

    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.

    Notes

    This class is immutable.

    See Also:
    Serialized Form
    • Field Detail

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

        The CSVFormat.Builder settings are:

        • setDelimiter(',')
        • setQuote('"')
        • setRecordSeparator("\r\n")
        • setIgnoreEmptyLines(false)
        • setAllowMissingColumnNames(true)
        • setAllowDuplicateHeaderNames(true)

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

        See Also:
        CSVFormat.Predefined.Excel
      • 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.

        The CSVFormat.Builder settings are:

        • setDelimiter(',')
        • setEscape('"')
        • setQuote('"')
        • setQuoteMode(QuoteMode.ALL_NON_NULL)
        • setSkipHeaderRecord(false)
        Since:
        1.7
        See Also:
        CSVFormat.Predefined.MongoDBCsv, MongoDB mongoexport command documentation
      • 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:
        CSVFormat.Predefined.MongoDBCsv, MongoDB mongoexport command documentation
      • 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".

        The CSVFormat.Builder settings are:

        • setDelimiter('\t')
        • setEscape('\\')
        • setIgnoreEmptyLines(false)
        • setQuote(null)
        • setRecordSeparator('\n')
        • setNullString("\\N")
        • setQuoteMode(QuoteMode.ALL_NON_NULL)
        See Also:
        CSVFormat.Predefined.MySQL, http://dev.mysql.com/doc/refman/5.1/en/load -data.html
      • 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:
        CSVFormat.Predefined.Oracle, Oracle CSV Format Specification
      • 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 "".

        The CSVFormat.Builder settings are:

        • setDelimiter(',')
        • setEscape('"')
        • setIgnoreEmptyLines(false)
        • setQuote('"')
        • setRecordSeparator('\n')
        • setNullString("")
        • setQuoteMode(QuoteMode.ALL_NON_NULL)
        Since:
        1.5
        See Also:
        CSVFormat.Predefined.MySQL, PostgreSQL COPY command documentation
      • 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".

        The CSVFormat.Builder settings are:

        • setDelimiter('\t')
        • setEscape('\\')
        • setIgnoreEmptyLines(false)
        • setQuote('"')
        • setRecordSeparator('\n')
        • setNullString("\\N")
        • setQuoteMode(QuoteMode.ALL_NON_NULL)
        Since:
        1.5
        See Also:
        CSVFormat.Predefined.MySQL, PostgreSQL COPY command documentation
      • allowDuplicateHeaderNames

        private final boolean allowDuplicateHeaderNames
      • allowMissingColumnNames

        private final boolean allowMissingColumnNames
      • autoFlush

        private final boolean autoFlush
      • commentMarker

        private final java.lang.Character commentMarker
      • delimiter

        private final java.lang.String 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
      • quotedNullString

        private final java.lang.String quotedNullString
      • 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​(java.lang.String 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,
                          boolean autoFlush,
                          boolean allowDuplicateHeaderNames)
        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 Doc me.
        allowMissingColumnNames - TODO Doc me.
        ignoreHeaderCase - TODO Doc me.
        trim - TODO Doc me.
        trailingDelimiter - TODO Doc me.
        autoFlush - TODO Doc me.
        Throws:
        java.lang.IllegalArgumentException - if the delimiter is a line break character.
    • Method Detail

      • clone

        @SafeVarargs
        static <T> T[] clone​(T... values)
        Null-safe clone of an array.
        Type Parameters:
        T - The array element type.
        Parameters:
        values - the source array
        Returns:
        the cloned array.
      • contains

        private static boolean contains​(java.lang.String source,
                                        char searchCh)
        Returns true if the given string contains the search char.
        Parameters:
        source - the string to check.
        Returns:
        true if c contains a line break character
      • containsLineBreak

        private static boolean containsLineBreak​(java.lang.String source)
        Returns true if the given string contains a line break character.
        Parameters:
        source - the string to check.
        Returns:
        true if c contains a line break character.
      • 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
      • toStringArray

        static java.lang.String[] toStringArray​(java.lang.Object[] values)
      • trim

        static java.lang.CharSequence trim​(java.lang.CharSequence charSequence)
      • 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
      • append

        private void append​(char c,
                            java.lang.Appendable appendable)
                     throws java.io.IOException
        Throws:
        java.io.IOException
      • append

        private void append​(java.lang.CharSequence csq,
                            java.lang.Appendable appendable)
                     throws java.io.IOException
        Throws:
        java.io.IOException
      • builder

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

        CSVFormat copy()
        Creates a copy of this instance.
        Returns:
        a copy of this instance.
      • 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
      • getAllowDuplicateHeaderNames

        public boolean getAllowDuplicateHeaderNames()
        Returns true if and only if duplicate names are allowed in the headers.
        Returns:
        whether duplicate header names are allowed
        Since:
        1.7
      • 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.
      • getAutoFlush

        public boolean getAutoFlush()
        Returns whether to flush on close.
        Returns:
        whether to flush on close.
        Since:
        1.6
      • 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

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

        public java.lang.String getDelimiterString()
        Returns the character delimiting the values (typically ";", "," or "\t").
        Returns:
        the delimiter.
      • 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. 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 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
      • isDelimiter

        private boolean isDelimiter​(char ch,
                                    java.lang.CharSequence charSeq,
                                    int startIndex,
                                    char[] delimiter,
                                    int delimiterLength)
        Matches whether the next characters constitute a delimiter
        Parameters:
        ch - the current char
        charSeq - the match char sequence
        startIndex - where start to match
        delimiter - the delimiter
        delimiterLength - the delimiter length
        Returns:
        true if the match is successful
      • 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 reader)
                        throws java.io.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:
        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.
      • 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 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. 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:
        java.io.IOException - If an I/O error occurs.
        Since:
        1.4
      • print

        private void print​(java.lang.Object object,
                           java.lang.CharSequence value,
                           java.lang.Appendable out,
                           boolean newRecord)
                    throws java.io.IOException
        Throws:
        java.io.IOException
      • print

        public CSVPrinter print​(java.nio.file.Path out,
                                java.nio.charset.Charset charset)
                         throws java.io.IOException
        Prints to the specified output, 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:
        java.io.IOException - thrown if the optional header cannot be printed.
        Since:
        1.5
      • print

        private void print​(java.io.Reader reader,
                           java.lang.Appendable out,
                           boolean newRecord)
                    throws java.io.IOException
        Throws:
        java.io.IOException
      • 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
      • println

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

        public void printRecord​(java.lang.Appendable appendable,
                                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:
        appendable - where to write.
        values - values to output.
        Throws:
        java.io.IOException - If an I/O error occurs.
        Since:
        1.4
      • printWithEscapes

        private void printWithEscapes​(java.lang.CharSequence charSeq,
                                      java.lang.Appendable appendable)
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • printWithEscapes

        private void printWithEscapes​(java.io.Reader reader,
                                      java.lang.Appendable appendable)
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • printWithQuotes

        private void printWithQuotes​(java.lang.Object object,
                                     java.lang.CharSequence charSeq,
                                     java.lang.Appendable out,
                                     boolean newRecord)
                              throws java.io.IOException
        Throws:
        java.io.IOException
      • printWithQuotes

        private void printWithQuotes​(java.io.Reader reader,
                                     java.lang.Appendable appendable)
                              throws java.io.IOException
        Always use quotes unless QuoteMode is NONE, so we not have to look ahead.
        Throws:
        java.io.IOException - If an I/O error occurs
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • validate

        private void validate()
                       throws java.lang.IllegalArgumentException
        Verifies the validity and consistency of the attributes, and throws an IllegalArgumentException if necessary.
        Throws:
        java.lang.IllegalArgumentException - Throw when any attribute is invalid or inconsistent with other attributes.
      • withAllowDuplicateHeaderNames

        @Deprecated
        public CSVFormat withAllowDuplicateHeaderNames()
        Returns 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)
        Returns 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​(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.
      • withAutoFlush

        @Deprecated
        public CSVFormat withAutoFlush​(boolean autoFlush)
        Returns 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)
        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

        @Deprecated
        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

        @Deprecated
        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

        @Deprecated
        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

        @Deprecated
        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
      • withHeader

        @Deprecated
        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:
        CSVFormat.Builder.setHeader(String...), CSVFormat.Builder.setSkipHeaderRecord(boolean)
      • withHeader

        @Deprecated
        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

        @Deprecated
        public CSVFormat withHeader​(java.sql.ResultSetMetaData resultSetMetaData)
                             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:
        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:
        java.sql.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​(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:
        CSVFormat.Builder.setSkipHeaderRecord(boolean)
      • withHeaderComments

        @Deprecated
        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.", 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:
        CSVFormat.Builder.setSkipHeaderRecord(boolean)
      • withIgnoreEmptyLines

        @Deprecated
        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

        @Deprecated
        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

        @Deprecated
        public CSVFormat withIgnoreSurroundingSpaces​(boolean ignoreSurroundingSpaces)
        Returns 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​(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

        @Deprecated
        public CSVFormat withQuote​(char quoteChar)
        Returns 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:
        java.lang.IllegalArgumentException - thrown if the specified character is a line break
      • withQuote

        @Deprecated
        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 quote 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

        @Deprecated
        public CSVFormat withQuoteMode​(QuoteMode quoteMode)
        Returns 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)
        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 specified output record separator
      • withRecordSeparator

        @Deprecated
        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 specified output record separator
        Throws:
        java.lang.IllegalArgumentException - if recordSeparator is none of CR, LF or CRLF
      • withSystemRecordSeparator

        @Deprecated
        public CSVFormat withSystemRecordSeparator()
        Returns 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()
        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

        @Deprecated
        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

        @Deprecated
        public CSVFormat withTrim()
        Deprecated.
        Returns 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)
        Returns 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