Apache
/
commons-csv
mirror of https://github.com/apache/commons-csv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CSV-231: Add more documentation to CSVPrinter

This commit is contained in:
Benedikt Ritter 2018-08-31 10:29:12 +02:00
parent e5b2413ca7
commit 71459b6d30
No known key found for this signature in database
GPG Key ID: 9DAADC1C9FCC82D0
2 changed files with 44 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/changes/changes.xml
View File

@ -39,6 +39,7 @@
</properties>
<body>
<release version="1.6" date="2018-MM-DD" description="Feature and bug fix release">
<action issue="CSV-231" type="update" dev="britter">Add more documentation to CSVPrinter.</action>
<action issue="CSV-217" type="add" dev="ggregory" due-to="Korolyov Alexei">Add autoFlush option for CsvPrinter. PR #24.</action>
<action issue="CSV-219" type="fix" dev="ggregory" due-to="Zhang Hongda">The behavior of quote char using is not similar as Excel does when the first string contains CJK char(s).</action>
<action issue="CSV-172" type="fix" dev="ggregory" due-to="Andrew Pennebaker">Don't quote cells just because they have UTF-8 encoded characters.</action>

45
src/main/java/org/apache/commons/csv/CSVPrinter.java
View File

@ -29,7 +29,42 @@ import java.sql.SQLException;
import java.util.Arrays;
/**
* Prints values in a CSV format.
* Prints values in a {@link CSVFormat CSV format}.
*
* <p>Values can be appended to the output by calling the {@link #print(Object)} method.
* Values are printed according to {@link String#valueOf(Object)}.
* To complete a record the {@link #println()} method has to be called.
* Comments can be appended by calling {@link #printComment(String)}.
* However a comment will only be written to the output if the {@link CSVFormat} supports comments.
* </p>
*
* <p>The printer also supports appending a complete record at once by calling {@link #printRecord(Object...)}
* or {@link #printRecord(Iterable)}.
* Furthermore {@link #printRecords(Object...)}, {@link #printRecords(Iterable)} and {@link #printRecords(ResultSet)}
* methods can be used to print several records at once.
* </p>
*
* <p>Example:</p>
*
* <pre>
* 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();
* }
* </pre>
*
* <p>This code will write the following to csv.txt:</p>
* <pre>
* id,userName,firstName,lastName,birthday
* 1,john73,John,Doe,1973-09-15
*
* 2,mary,Mary,Meyer,1985-03-29
* </pre>
* <p></p>
*/
public final class CSVPrinter implements Flushable, Closeable {
@ -141,11 +176,17 @@ public final class CSVPrinter implements Flushable, Closeable {
* Prints a comment on a new line among the delimiter separated values.
*
* <p>
* Comments will always begin on a new line and occupy a least one full line. The character specified to start
* 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.
* </p>
*
* <p>
* If comments are disabled in the current CSV format this method does nothing.
* </p>
*
* <p>This method detects line breaks inside the comment string and inserts {@link 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 separator.</p>
*
* @param comment
* the comment to output