CSVPrinter (Apache Commons CSV 1.14.1 API)
Description: declaration: package: org.apache.commons.csv, class: CSVPrinter

Package org.apache.commons.csv

# Class CSVPrinter

java.lang.Object
org.apache.commons.csv.CSVPrinter

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`

public final class CSVPrinter extends Object implements Flushable, Closeable
Prints values in a `CSV format`.

Values can be appended to the output by calling the `print(Object)` method. Values are printed according to `String.valueOf(Object)`. To complete a record the `println()` method has to be called. Comments can be appended by calling `printComment(String)`. However a comment will only be written to the output if the `CSVFormat` supports comments.

The printer also supports appending a complete record at once by calling `printRecord(Object...)` or `printRecord(Iterable)`. Furthermore `printRecords(Object...)`, `printRecords(Iterable)` and `printRecords(ResultSet)` methods can be used to print several records at once.

Example:

     try (CSVPrinter printer = new CSVPrinter(new FileWriter("csv.txt"), CSVFormat.EXCEL)) {
         printer.printRecord("id", "userName", "firstName", "lastName", "birthday");
         printer.printRecord(1, "john73", "John", "Doe", LocalDate.of(1973, 9, 15));
         printer.println();
         printer.printRecord(2, "mary", "Mary", "Meyer", LocalDate.of(1985, 3, 29));
     } catch (IOException ex) {
         ex.printStackTrace();
     }

This code will write the following to csv.txt:

     id,userName,firstName,lastName,birthday
     1,john73,John,Doe,1973-09-15

     2,mary,Mary,Meyer,1985-03-29

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CSVPrinter(Appendable appendable, CSVFormat format)`
  Creates a printer that will print values to the given stream following the CSVFormat.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  `void`
  `close(boolean flush)`
  Closes the underlying stream with an optional flush first.
  `void`
  `flush()`
  Flushes the underlying stream.
  `Appendable`
  `getOut()`
  Gets the target Appendable.
  `long`
  `getRecordCount()`
  Gets the record count printed, this does not include comments or headers.
  `void`
  `print(Object value)`
  Prints the string as the next value on the line.
  `void`
  `printComment(String comment)`
  Prints a comment on a new line among the delimiter-separated values.
  `void`
  `printHeaders(ResultSet resultSet)`
  Prints headers for a result set based on its metadata.
  `void`
  `println()`
  Prints the record separator.
  `void`
  `printRecord(Iterable<?> values)`
  Prints the given values as a single record of delimiter-separated values followed by the record separator.
  `void`
  `printRecord(Object... values)`
  Prints the given values as a single record of delimiter-separated values followed by the record separator.
  `void`
  `printRecord(Stream<?> stream)`
  Prints the given values as a single record of delimiter-separated values followed by the record separator.
  `void`
  `printRecords(Iterable<?> values)`
  Prints all the objects in the given `Iterable` handling nested collections/arrays as records.
  `void`
  `printRecords(Object... values)`
  Prints all the objects in the given array handling nested collections/arrays as records.
  `void`
  `printRecords(ResultSet resultSet)`
  Prints all the objects in the given JDBC result set.
  `void`
  `printRecords(ResultSet resultSet, boolean printHeader)`
  Prints all the objects with metadata in the given JDBC result set based on the header boolean.
  `void`
  `printRecords(Stream<?> values)`
  Prints all the objects in the given `Stream` handling nested collections/arrays as records.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CSVPrinter

    public CSVPrinter(Appendable appendable, CSVFormat format) throws IOException
    Creates a printer that will print values to the given stream following the CSVFormat.

    Currently, only a pure encapsulation format or a pure escaping format is supported. Hybrid formats (encapsulation and escaping with a different character) are not supported.

    Parameters:
      `appendable` - stream to which to print. Must not be null.
      `format` - the CSV format. Must not be null.
    Throws:
      `IOException` - thrown if the optional header cannot be printed.
      `IllegalArgumentException` - thrown if the parameters of the format are inconsistent.
      `NullPointerException` - thrown if either parameters are null.

- ## Method Details

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException`

  - ### close

    public void close(boolean flush) throws IOException
    Closes the underlying stream with an optional flush first.
    Parameters:
      `flush` - whether to flush before the actual close.
    Throws:
      `IOException` - If an I/O error occurs
    Since:
      1.6
    See Also:
      - `CSVFormat.getAutoFlush()`

  - ### flush

    public void flush() throws IOException
    Flushes the underlying stream.
    Specified by:
      `flush` in interface `Flushable`
    Throws:
      `IOException` - If an I/O error occurs

  - ### getOut

    public Appendable getOut()
    Gets the target Appendable.
    Returns:
      the target Appendable.

  - ### getRecordCount

    public long getRecordCount()
    Gets the record count printed, this does not include comments or headers.
    Returns:
      the record count, this does not include comments or headers.
    Since:
      1.13.0

  - ### print

    public void print(Object value) throws IOException
    Prints the string as the next value on the line. The value will be escaped or encapsulated as needed.
    Parameters:
      `value` - value to be output.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printComment

    public void printComment(String comment) throws IOException
    Prints a comment on a new line among the delimiter-separated values.

    Comments will always begin on a new line and occupy at least one full line. The character specified to start comments and a space will be inserted at the beginning of each new line in the comment.

    If comments are disabled in the current CSV format this method does nothing.

    This method detects line breaks inside the comment string and inserts `CSVFormat.getRecordSeparator()` to start a new line of the comment. Note that this might produce unexpected results for formats that do not use line breaks as record separators.

    Parameters:
      `comment` - the comment to output
    Throws:
      `IOException` - If an I/O error occurs

  - ### printHeaders

    public void printHeaders(ResultSet resultSet) throws IOException, SQLException
    Prints headers for a result set based on its metadata.
    Parameters:
      `resultSet` - The ResultSet to query for metadata.
    Throws:
      `IOException` - If an I/O error occurs.
      `SQLException` - If a database access error occurs or this method is called on a closed result set.
    Since:
      1.9.0

  - ### println

    public void println() throws IOException
    Prints the record separator.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printRecord

    public void printRecord(Iterable<?> values) throws IOException
    Prints the given values as a single record of delimiter-separated values followed by the record separator.

    The values will be quoted if needed. Quotes and newLine 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()`.

    Parameters:
      `values` - values to output.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printRecord

    public void printRecord(Object... values) throws IOException
    Prints the given values as a single record of delimiter-separated values followed by the record separator.

    The values will be quoted if needed. Quotes and newLine 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()`.

    Parameters:
      `values` - values to output.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printRecord

    public void printRecord(Stream<?> stream) throws IOException
    Prints the given values as a single record of delimiter-separated values followed by the record separator.

    The values will be quoted if needed. Quotes and newLine 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()`.

    Parameters:
      `stream` - values to output.
    Throws:
      `IOException` - If an I/O error occurs
    Since:
      1.10.0

  - ### printRecords

    public void printRecords(Iterable<?> values) throws IOException
    Prints all the objects in the given `Iterable` handling nested collections/arrays as records.

    If the given Iterable only contains simple objects, this method will print a single record like `printRecord(Iterable)`. If the given Iterable contains nested collections/arrays those nested elements will each be printed as records using `printRecord(Object...)`.

    Given the following data structure:

         List<String[]> data = new ArrayList<>();
         data.add(new String[]{ "A", "B", "C" });
         data.add(new String[]{ "1", "2", "3" });
         data.add(new String[]{ "A1", "B2", "C3" });

    Calling this method will print:

         A, B, C
         1, 2, 3
         A1, B2, C3

    Parameters:
      `values` - the values to print.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printRecords

    public void printRecords(Object... values) throws IOException
    Prints all the objects in the given array handling nested collections/arrays as records.

    If the given array only contains simple objects, this method will print a single record like `printRecord(Object...)`. If the given collections contain nested collections or arrays, those nested elements will each be printed as records using `printRecord(Object...)`.

    Given the following data structure:

         String[][] data = new String[3][]
         data[0] = String[]{ "A", "B", "C" };
         data[1] = new String[]{ "1", "2", "3" };
         data[2] = new String[]{ "A1", "B2", "C3" };

    Calling this method will print:

         A, B, C
         1, 2, 3
         A1, B2, C3

    Parameters:
      `values` - the values to print.
    Throws:
      `IOException` - If an I/O error occurs

  - ### printRecords

    public void printRecords(ResultSet resultSet) throws SQLException, IOException
    Prints all the objects in the given JDBC result set.

    You can use `CSVFormat.Builder.setMaxRows(long)` to limit how many rows a result set produces. This is most useful when you cannot limit rows through `Statement.setLargeMaxRows(long)` or `Statement.setMaxRows(int)`.

    Parameters:
      `resultSet` - The values to print.
    Throws:
      `IOException` - If an I/O error occurs.
      `SQLException` - Thrown when a database access error occurs.

  - ### printRecords

    public void printRecords(ResultSet resultSet, boolean printHeader) throws SQLException, IOException
    Prints all the objects with metadata in the given JDBC result set based on the header boolean.

    You can use `CSVFormat.Builder.setMaxRows(long)` to limit how many rows a result set produces. This is most useful when you cannot limit rows through `Statement.setLargeMaxRows(long)` or `Statement.setMaxRows(int)`.

    Parameters:
      `resultSet` - source of row data.
      `printHeader` - whether to print headers.
    Throws:
      `IOException` - If an I/O error occurs
      `SQLException` - if a database access error occurs
    Since:
      1.9.0

  - ### printRecords

    public void printRecords(Stream<?> values) throws IOException
    Prints all the objects in the given `Stream` handling nested collections/arrays as records.

    If the given Stream only contains simple objects, this method will print a single record like `printRecord(Iterable)`. If the given Stream contains nested collections/arrays those nested elements will each be printed as records using `printRecord(Object...)`.

    Given the following data structure:

         List<String[]> data = new ArrayList<>();
         data.add(new String[]{ "A", "B", "C" });
         data.add(new String[]{ "1", "2", "3" });
         data.add(new String[]{ "A1", "B2", "C3" });
         Stream<String[]> stream = data.stream();

    Calling this method will print:

         A, B, C
         1, 2, 3
         A1, B2, C3

    Parameters:
      `values` - the values to print.
    Throws:
      `IOException` - If an I/O error occurs
    Since:
      1.10.0