From 194e21c283fa857bf1a121b8f37ba3346a11cf2e Mon Sep 17 00:00:00 2001 From: Emmanuel Bourg Date: Wed, 7 Mar 2012 22:34:51 +0000 Subject: [PATCH] More Javadoc for CSVFormat git-svn-id: https://svn.apache.org/repos/asf/commons/sandbox/csv/trunk@1298176 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/commons/csv/CSVFormat.java | 119 +++++++++++++++++- 1 file changed, 117 insertions(+), 2 deletions(-) diff --git a/src/main/java/org/apache/commons/csv/CSVFormat.java b/src/main/java/org/apache/commons/csv/CSVFormat.java index 398adf88..40e4b701 100644 --- a/src/main/java/org/apache/commons/csv/CSVFormat.java +++ b/src/main/java/org/apache/commons/csv/CSVFormat.java @@ -126,20 +126,42 @@ public class CSVFormat implements Cloneable, Serializable { this.emptyLinesIgnored = emptyLinesIgnored; } + /** + * Returns the character delimiting the values (typically ';', ',' or '\t'). + * + * @return the delimiter character + */ public char getDelimiter() { return delimiter; } + /** + * Returns a copy of this format using the specified delimiter character. + * + * @param delimiter the delimiter character + * @return A copy of this format using the specified delimiter character + */ public CSVFormat withDelimiter(char delimiter) { CSVFormat format = clone(); format.delimiter = delimiter; return format; } + /** + * Returns the character used to encapsulate values containing special characters. + * + * @return the encapsulator character + */ public char getEncapsulator() { return encapsulator; } + /** + * Returns a copy of this format using the specified encapsulator character. + * + * @param encapsulator the encapsulator character + * @return A copy of this format using the specified encapsulator character + */ public CSVFormat withEncapsulator(char encapsulator) { CSVFormat format = clone(); format.encapsulator = encapsulator; @@ -150,24 +172,51 @@ public class CSVFormat implements Cloneable, Serializable { return this.encapsulator != DISABLED; } + /** + * Returns the character marking the start of a line comment. + * + * @return the comment start marker. + */ public char getCommentStart() { return commentStart; } + /** + * Returns a copy of this format using the specified character as the comment start marker. + * + * @param commentStart the comment start marker + * @return A copy of this format using the specified character as the comment start marker + */ public CSVFormat withCommentStart(char commentStart) { CSVFormat format = clone(); format.commentStart = commentStart; return format; } + /** + * Tells if comments are supported by this format. + * + * @return true is comments are supported, false otherwise + */ public boolean isCommentingDisabled() { return this.commentStart == DISABLED; } + /** + * Returns the escape character. + * + * @return the escape character + */ public char getEscape() { return escape; } + /** + * Returns a copy of this format using the specified escape character. + * + * @param escape the escape character + * @return A copy of this format using the specified escape character + */ public CSVFormat withEscape(char escape) { CSVFormat format = clone(); format.escape = escape; @@ -178,57 +227,123 @@ public class CSVFormat implements Cloneable, Serializable { return this.escape != DISABLED; } + /** + * Tells if the spaces characters at the beginning of the values are ignored when parsing a file. + * + * @return true if leading spaces are removed, false if they are preserved. + */ public boolean isLeadingSpacesIgnored() { return leadingSpacesIgnored; } + /** + * Returns a copy of this format with the specified left trimming behavior. + * + * @param leadingSpacesIgnored the left trimming behavior, true to remove the leading spaces, + * false to leave the spaces as is. + * @return A copy of this format with the specified left trimming behavior. + */ public CSVFormat withLeadingSpacesIgnored(boolean leadingSpacesIgnored) { CSVFormat format = clone(); format.leadingSpacesIgnored = leadingSpacesIgnored; return format; } + /** + * Tells if the spaces characters at the end of the values are ignored when parsing a file. + * + * @return true if trailing spaces are removed, false if they are preserved. + */ public boolean isTrailingSpacesIgnored() { return trailingSpacesIgnored; } + /** + * Returns a copy of this format with the specified right trimming behavior. + * + * @param trailingSpacesIgnored the right trimming behavior, true to remove the trailing spaces, + * false to leave the spaces as is. + * @return A copy of this format with the specified right trimming behavior. + */ public CSVFormat withTrailingSpacesIgnored(boolean trailingSpacesIgnored) { CSVFormat format = clone(); format.trailingSpacesIgnored = trailingSpacesIgnored; return format; } + /** + * Returns a copy of this format with the specified trimming behavior. + * + * @param surroundingSpacesIgnored the trimming behavior, true to remove the surrounding spaces, + * false to leave the spaces as is. + * @return A copy of this format with the specified trimming behavior. + */ public CSVFormat withSurroundingSpacesIgnored(boolean surroundingSpacesIgnored) { CSVFormat format = clone(); format.leadingSpacesIgnored = surroundingSpacesIgnored; format.trailingSpacesIgnored = surroundingSpacesIgnored; return format; } - + + /** + * Tells if unicode escape sequences (i.e \u1234) are turned into their corresponding character. + * + * @return true if unicode escape sequences are interpreted, false if they are left as is. + */ public boolean isUnicodeEscapesInterpreted() { return unicodeEscapesInterpreted; } + /** + * Returns a copy of this format with the specified unicode escaping behavior. + * + * @param unicodeEscapesInterpreted the escaping behavior, true to interpret unicode escape sequences, + * false to leave the escape sequences as is. + * @return A copy of this format with the specified unicode escaping behavior. + */ public CSVFormat withUnicodeEscapesInterpreted(boolean unicodeEscapesInterpreted) { CSVFormat format = clone(); format.unicodeEscapesInterpreted = unicodeEscapesInterpreted; return format; } + /** + * Tells if the empty lines between the records are ignored. + * + * @return true if empty lines between records are ignore, false if they are turned into empty records. + */ public boolean isEmptyLinesIgnored() { return emptyLinesIgnored; } + /** + * Returns a copy of this format with the specified empty line skipping behavior. + * + * @param emptyLinesIgnored the empty line skipping behavior, true to ignore the empty lines + * between the records, false to translate empty lines to empty records. + * @return A copy of this format with the specified empty line skipping behavior. + */ public CSVFormat withEmptyLinesIgnored(boolean emptyLinesIgnored) { CSVFormat format = clone(); format.emptyLinesIgnored = emptyLinesIgnored; return format; } + /** + * Returns the line separator delimiting the records. + * + * @return the line separator + */ public String getLineSeparator() { return lineSeparator; } + /** + * Returns a copy of this format using the specified line separator. + * + * @param lineSeparator the line separator + * @return A copy of this format using the specified line separator + */ public CSVFormat withLineSeparator(String lineSeparator) { CSVFormat format = clone(); format.lineSeparator = lineSeparator; @@ -238,7 +353,7 @@ public class CSVFormat implements Cloneable, Serializable { /** * Parses the specified content. * - * @param in + * @param in the input stream */ public Iterable parse(Reader in) { return new CSVParser(in, this);