commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From brit...@apache.org
Subject [12/50] [lang] LANG-1300: Updating javadocs
Date Mon, 17 Apr 2017 12:19:35 GMT
LANG-1300: Updating javadocs


Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/9fe11e68
Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/9fe11e68
Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/9fe11e68

Branch: refs/heads/release
Commit: 9fe11e688e3562264350dcdd02730276ea233ed4
Parents: e9610cc
Author: Rob Tompkins <chtompki@gmail.com>
Authored: Wed Mar 15 08:39:22 2017 -0400
Committer: Rob Tompkins <chtompki@gmail.com>
Committed: Wed Mar 15 08:45:55 2017 -0400

----------------------------------------------------------------------
 .../apache/commons/lang3/CharSequenceUtils.java |  54 ++++++++-
 .../org/apache/commons/lang3/StringUtils.java   | 121 +++++++++++++++----
 2 files changed, 146 insertions(+), 29 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-lang/blob/9fe11e68/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java b/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
index 01cbca7..7be6573 100644
--- a/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
@@ -59,13 +59,42 @@ public class CharSequenceUtils {
 
     //-----------------------------------------------------------------------
     /**
-     * <p>Finds the first index in the {@code CharSequence} that matches the
-     * specified character.</p>
+     * Returns the index within <code>cs</code> of the first occurrence of the
+     * specified character, starting the search at the specified index.
+     * <p>
+     * If a character with value <code>searchChar</code> occurs in the
+     * character sequence represented by the <code>cs</code>
+     * object at an index no smaller than <code>start</code>, then
+     * the index of the first such occurrence is returned. For values
+     * of <code>searchChar</code> in the range from 0 to 0xFFFF (inclusive),
+     * this is the smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.charAt(<i>k</i>) == searchChar) && (<i>k</i>
&gt;= start)
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.codePointAt(<i>k</i>) == searchChar) && (<i>k</i>
&gt;= start)
+     * </pre></blockquote>
+     * is true. In either case, if no such character occurs inm <code>cs</code>
+     * at or after position <code>start</code>, then
+     * <code>-1</code> is returned.
+     *
+     * <p>
+     * There is no restriction on the value of <code>start</code>. If it
+     * is negative, it has the same effect as if it were zero: the entire
+     * <code>CharSequence</code> may be searched. If it is greater than
+     * the length of <code>cs</code>, it has the same effect as if it were
+     * equal to the length of <code>cs</code>: <code>-1</code> is
returned.
+     *
+     * <p>All indices are specified in <code>char</code> values
+     * (Unicode code units).
      *
      * @param cs  the {@code CharSequence} to be processed, not null
      * @param searchChar  the char to be searched for
      * @param start  the start index, negative starts at the string start
      * @return the index where the search char was found, -1 if not found
+     * @since 3.6 updated to behave more like <code>String</code>
      */
     static int indexOf(final CharSequence cs, final int searchChar, int start) {
         if (cs instanceof String) {
@@ -123,13 +152,30 @@ public class CharSequenceUtils {
     }
 
     /**
-     * <p>Finds the last index in the {@code CharSequence} that matches the
-     * specified character.</p>
+     * Returns the index within <code>cs</code> of the last occurrence of
+     * the specified character, searching backward starting at the
+     * specified index. For values of <code>searchChar</code> in the range
+     * from 0 to 0xFFFF (inclusive), the index returned is the largest
+     * value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.charAt(<i>k</i>) == searchChar) && (<i>k</i>
&lt;= start)
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * largest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.codePointAt(<i>k</i>) == searchChar) && (<i>k</i>
&lt;= start)
+     * </pre></blockquote>
+     * is true. In either case, if no such character occurs in <code>cs</code>
+     * at or before position <code>start</code>, then <code>-1</code>
is returned.
+     *
+     * <p>All indices are specified in <code>char</code> values
+     * (Unicode code units).
      *
      * @param cs  the {@code CharSequence} to be processed
      * @param searchChar  the char to be searched for
      * @param start  the start index, negative returns -1, beyond length starts at end
      * @return the index where the search char was found, -1 if not found
+     * @since 3.6 updated to behave more like <code>String</code>
      */
     static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
         if (cs instanceof String) {

http://git-wip-us.apache.org/repos/asf/commons-lang/blob/9fe11e68/src/main/java/org/apache/commons/lang3/StringUtils.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index 2250595..357e8c5 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/src/main/java/org/apache/commons/lang3/StringUtils.java
@@ -1276,10 +1276,26 @@ public class StringUtils {
     // IndexOf
     //-----------------------------------------------------------------------
     /**
-     * <p>Finds the first index within a CharSequence, handling {@code null}.
-     * This method uses {@link String#indexOf(int, int)} if possible.</p>
-     *
-     * <p>A {@code null} or empty ("") CharSequence will return {@code INDEX_NOT_FOUND
(-1)}.</p>
+     * Returns the index within <code>seq</code> of the first occurrence of
+     * the specified character. If a character with value
+     * <code>searchChar</code> occurs in the character sequence represented by
+     * <code>seq</code> <code>CharSequence</code> object, then the
index (in Unicode
+     * code units) of the first such occurrence is returned. For
+     * values of <code>searchChar</code> in the range from 0 to 0xFFFF
+     * (inclusive), this is the smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * this.charAt(<i>k</i>) == searchChar
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * this.codePointAt(<i>k</i>) == searchChar
+     * </pre></blockquote>
+     * is true. In either case, if no such character occurs in <code>seq</code>,
+     * then {@code INDEX_NOT_FOUND (-1)} is returned.
+     *
+     * <p>Furthermore, a {@code null} or empty ("") CharSequence will
+     * return {@code INDEX_NOT_FOUND (-1)}.</p>
      *
      * <pre>
      * StringUtils.indexOf(null, *)         = -1
@@ -1294,6 +1310,7 @@ public class StringUtils {
      *  -1 if no match or {@code null} string input
      * @since 2.0
      * @since 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int)
+     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like <code>String</code>
      */
     public static int indexOf(final CharSequence seq, final int searchChar) {
         if (isEmpty(seq)) {
@@ -1303,13 +1320,39 @@ public class StringUtils {
     }
 
     /**
-     * <p>Finds the first index within a CharSequence from a start position,
-     * handling {@code null}.
-     * This method uses {@link String#indexOf(int, int)} if possible.</p>
      *
-     * <p>A {@code null} or empty ("") CharSequence will return {@code (INDEX_NOT_FOUND)
-1}.
-     * A negative start position is treated as zero.
-     * A start position greater than the string length returns {@code -1}.</p>
+     * Returns the index within <code>seq</code> of the first occurrence of the
+     * specified character, starting the search at the specified index.
+     * <p>
+     * If a character with value <code>searchChar</code> occurs in the
+     * character sequence represented by the <code>seq</code> <code>CharSequence</code>
+     * object at an index no smaller than <code>startPos</code>, then
+     * the index of the first such occurrence is returned. For values
+     * of <code>searchChar</code> in the range from 0 to 0xFFFF (inclusive),
+     * this is the smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.charAt(<i>k</i>) == searchChar) && (<i>k</i>
&gt;= startPos)
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * smallest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.codePointAt(<i>k</i>) == searchChar) && (<i>k</i>
&gt;= startPos)
+     * </pre></blockquote>
+     * is true. In either case, if no such character occurs in <code>seq</code>
+     * at or after position <code>startPos</code>, then
+     * <code>-1</code> is returned.
+     *
+     * <p>
+     * There is no restriction on the value of <code>startPos</code>. If it
+     * is negative, it has the same effect as if it were zero: this entire
+     * string may be searched. If it is greater than the length of this
+     * string, it has the same effect as if it were equal to the length of
+     * this string: {@code (INDEX_NOT_FOUND) -1} is returned. Furthermore, a
+     * {@code null} or empty ("") CharSequence will
+     * return {@code (INDEX_NOT_FOUND) -1}.
+     *
+     * <p>All indices are specified in <code>char</code> values
+     * (Unicode code units).
      *
      * <pre>
      * StringUtils.indexOf(null, *, *)          = -1
@@ -1327,6 +1370,7 @@ public class StringUtils {
      *  -1 if no match or {@code null} string input
      * @since 2.0
      * @since 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence,
int, int)
+     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like <code>String</code>
      */
     public static int indexOf(final CharSequence seq, final int searchChar, final int startPos)
{
         if (isEmpty(seq)) {
@@ -1586,10 +1630,23 @@ public class StringUtils {
     // LastIndexOf
     //-----------------------------------------------------------------------
     /**
-     * <p>Finds the last index within a CharSequence, handling {@code null}.
-     * This method uses {@link String#lastIndexOf(int)} if possible.</p>
-     *
-     * <p>A {@code null} or empty ("") CharSequence will return {@code -1}.</p>
+     * Returns the index within <code>seq</code> of the last occurrence of
+     * the specified character. For values of <code>searchChar</code> in the
+     * range from 0 to 0xFFFF (inclusive), the index (in Unicode code
+     * units) returned is the largest value <i>k</i> such that:
+     * <blockquote><pre>
+     * this.charAt(<i>k</i>) == searchChar
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * largest value <i>k</i> such that:
+     * <blockquote><pre>
+     * this.codePointAt(<i>k</i>) == searchChar
+     * </pre></blockquote>
+     * is true.  In either case, if no such character occurs in this
+     * string, then <code>-1</code> is returned. Furthermore, a {@code null}
or empty ("")
+     * <code>CharSequence</code> will return {@code -1}. The
+     * <code>seq</code> <code>CharSequence</code> object is searched
backwards
+     * starting at the last character.
      *
      * <pre>
      * StringUtils.lastIndexOf(null, *)         = -1
@@ -1598,12 +1655,13 @@ public class StringUtils {
      * StringUtils.lastIndexOf("aabaabaa", 'b') = 5
      * </pre>
      *
-     * @param seq  the CharSequence to check, may be null
+     * @param seq  the <code>CharSequence</code> to check, may be null
      * @param searchChar  the character to find
      * @return the last index of the search character,
      *  -1 if no match or {@code null} string input
      * @since 2.0
      * @since 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence,
int)
+     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like <code>String</code>
      */
     public static int lastIndexOf(final CharSequence seq, final int searchChar) {
         if (isEmpty(seq)) {
@@ -1613,16 +1671,29 @@ public class StringUtils {
     }
 
     /**
-     * <p>Finds the last index within a CharSequence from a start position,
-     * handling {@code null}.
-     * This method uses {@link String#lastIndexOf(int, int)} if possible.</p>
-     *
-     * <p>A {@code null} or empty ("") CharSequence will return {@code -1}.
-     * A negative start position returns {@code -1}.
-     * A start position greater than the string length searches the whole string.
-     * The search starts at the startPos and works backwards; matches starting after the
start
-     * position are ignored.
-     * </p>
+     * Returns the index within <code>seq</code> of the last occurrence of
+     * the specified character, searching backward starting at the
+     * specified index. For values of <code>searchChar</code> in the range
+     * from 0 to 0xFFFF (inclusive), the index returned is the largest
+     * value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.charAt(<i>k</i>) == searchChar) && (<i>k</i>
&lt;= startPos)
+     * </pre></blockquote>
+     * is true. For other values of <code>searchChar</code>, it is the
+     * largest value <i>k</i> such that:
+     * <blockquote><pre>
+     * (this.codePointAt(<i>k</i>) == searchChar) && (<i>k</i>
&lt;= startPos)
+     * </pre></blockquote>
+     * is true. In either case, if no such character occurs in <code>seq</code>
+     * at or before position <code>startPos</code>, then
+     * <code>-1</code> is returned. Furthermore, a {@code null} or empty ("")
+     * <code>CharSequence</code> will return {@code -1}. A start position greater
+     * than the string length searches the whole string.
+     * The search starts at the <code>startPos</code> and works backwards;
+     * matches starting after the start position are ignored.
+     *
+     * <p>All indices are specified in <code>char</code> values
+     * (Unicode code units).
      *
      * <pre>
      * StringUtils.lastIndexOf(null, *, *)          = -1


Mime
View raw message