You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by br...@apache.org on 2018/09/19 09:04:59 UTC
[42/48] commons-csv git commit: CSV-231: Add more documentation to
CSVPrinter
CSV-231: Add more documentation to CSVPrinter
Project: http://git-wip-us.apache.org/repos/asf/commons-csv/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-csv/commit/71459b6d
Tree: http://git-wip-us.apache.org/repos/asf/commons-csv/tree/71459b6d
Diff: http://git-wip-us.apache.org/repos/asf/commons-csv/diff/71459b6d
Branch: refs/heads/release
Commit: 71459b6d30135723608b06c6ee7a9307b34edaea
Parents: e5b2413
Author: Benedikt Ritter <br...@apache.org>
Authored: Fri Aug 31 10:29:12 2018 +0200
Committer: Benedikt Ritter <br...@apache.org>
Committed: Fri Aug 31 10:29:12 2018 +0200
----------------------------------------------------------------------
src/changes/changes.xml | 1 +
.../java/org/apache/commons/csv/CSVPrinter.java | 45 +++++++++++++++++++-
2 files changed, 44 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-csv/blob/71459b6d/src/changes/changes.xml
----------------------------------------------------------------------
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index dd56857..607b979 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -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>
http://git-wip-us.apache.org/repos/asf/commons-csv/blob/71459b6d/src/main/java/org/apache/commons/csv/CSVPrinter.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/csv/CSVPrinter.java b/src/main/java/org/apache/commons/csv/CSVPrinter.java
index 3ae5971..ccf4bff 100644
--- a/src/main/java/org/apache/commons/csv/CSVPrinter.java
+++ b/src/main/java/org/apache/commons/csv/CSVPrinter.java
@@ -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