Author: desruisseaux
Date: Thu Nov 29 17:02:43 2012
New Revision: 1415272
URL: http://svn.apache.org/viewvc?rev=1415272&view=rev
Log:
Minor javadoc clarification.
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java?rev=1415272&r1=1415271&r2=1415272&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
Thu Nov 29 17:02:43 2012
@@ -42,22 +42,24 @@ import static org.apache.sis.util.String
* no-break spaces}, tabulations and line feeds. The general policy in the SIS
library is:
*
* <ul>
- * <li>Use {@code isWhitespace(â¦)} when separating entities (words,
numbers, tokens).
+ * <li><p>Use {@code isWhitespace(â¦)} when separating entities (words,
numbers, tokens).
* Using this method, characters separated by a no-break space are
considered as
* part of the same entity (e.g. the French locale uses no-break space
instead of
* coma as group separator in number representations), while line feeds
and
- * tabulations are accepted as valid entity separator.</li>
- * <li>Use {@code isSpaceChar(â¦)} when parsing a single entity. Using this
method,
+ * tabulations are accepted as valid entity separator.
+ * This {@code CharSequences} class consistently uses {@code
isWhitespace(â¦)}.</p></li>
+ *
+ * <li><p>Use {@code isSpaceChar(â¦)} when parsing a single entity. Using
this method,
* no-break spaces are considered as part of the entity (e.g. the
above-cited
- * group separator), while line feeds or tabulation mark entity
boundaries.</li>
+ * group separator), while line feeds or tabulation mark entity
boundaries.
+ * For this reason, the {@link java.text.Format} implementations in the
SIS
+ * library typically use {@code isSpaceChar(â¦)}.</p></li>
* </ul>
*
- * This {@code CharSequences} class consistently uses {@code
isWhitespace(â¦)}, while
- * {@link java.text.Format} implementations in SIS typically use {@code
isSpaceChar(â¦)}.
- *
- * <p>Note that the {@link String#trim()} method doesn't follow any of those
politics and should
+ * Note that the {@link String#trim()} method doesn't follow any of those
policies and should
* generally be avoided. That {@code trim()} method removes every ISO control
characters without
- * distinction about whether the characters are space or not, and ignore all
Unicode spaces.</p>
+ * distinction about whether the characters are space or not, and ignore all
Unicode spaces.
+ * The {@link #trimWhitespaces(String) method defined in this class can be
used as an alternative.
*
* {@section Handling of null values}
* Most methods in this class accept a {@code null} {@code CharSequence}
argument. In such cases
@@ -908,8 +910,14 @@ search: for (; fromIndex <= toIndex;
/**
* Returns a string with leading and trailing whitespace characters
omitted.
- * This method performs the same work than {@link
#trimWhitespaces(CharSequence)},
- * but is overloaded for the {@code String} type because very often used.
+ * This method is similar in purpose to {@link String#trim()}, except that
the later considers
+ * every {@linkplain Character#isISOControl(int) ISO control codes} below
32 to be a whitespace.
+ * That {@code String.trim()} behavior has the side effect of removing the
heading of ANSI escape
+ * sequences (a.k.a. X3.64), and to ignore Unicode spaces. This {@code
trimWhitespaces(â¦)} method
+ * is built on the more accurate {@link Character#isWhitespace(int)}
method instead.
+ *
+ * <p>This method performs the same work than {@link
#trimWhitespaces(CharSequence)},
+ * but is overloaded for the {@code String} type because of its frequent
use.</p>
*
* @param text The text from which to remove leading and trailing
whitespaces, or {@code null}.
* @return A string with leading and trailing whitespaces removed, or
{@code null} is the given
@@ -928,11 +936,7 @@ search: for (; fromIndex <= toIndex;
* Returns a text with leading and trailing whitespace characters omitted.
* Space characters are identified by the {@link
Character#isWhitespace(int)} method.
*
- * <p>This method is similar in purpose to {@link String#trim()}, except
that the later considers
- * every ASCII control codes below 32 to be a whitespace. This have the
side effect of removing
- * ANSI escape sequences (a.k.a. X3.64) as well. Users should invoke this
- * {@code CharSequences.trimWhitespaces(â¦)} method instead if they need
to preserve
- * those ANSI escape sequences.</p>
+ * <p>This method is the generic version of {@link
#trimWhitespaces(String)}.</p>
*
* @param text The text from which to remove leading and trailing
whitespaces, or {@code null}.
* @return A characters sequence with leading and trailing whitespaces
removed,
@@ -952,9 +956,13 @@ search: for (; fromIndex <= toIndex;
* Returns a sub-sequence with leading and trailing whitespace characters
omitted.
* Space characters are identified by the {@link
Character#isWhitespace(int)} method.
*
- * <p>Invoking this method is functionally equivalent to invoking
- * <code>{@linkplain #trimWhitespaces(CharSequence)
trimWhitespaces}(text.subSequence(lower, upper))</code>,
- * except that only one call to {@link CharSequence#subSequence(int, int)}
is performed instead of two.</p>
+ * <p>Invoking this method is functionally equivalent to the following
code snippet,
+ * except that the {@link CharSequence#subSequence(int, int) subSequence}
method is
+ * invoked only once instead of two times:</p>
+ *
+ * {@preformat java
+ * text = trimWhitespaces(text.subSequence(lower, upper));
+ * }
*
* @param text The text from which to remove leading and trailing white
spaces.
* @param lower Index of the first character to consider for inclusion in
the sub-sequence.
