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

LANG-1300: Updating javadocs

This commit is contained in:
Rob Tompkins 2017-03-15 08:39:22 -04:00
parent e9610ccf30
commit 9fe11e688e
2 changed files with 144 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
View File

@ -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) {

117
src/main/java/org/apache/commons/lang3/StringUtils.java
View File

@ -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>
* 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>A {@code null} or empty ("") CharSequence will return {@code INDEX_NOT_FOUND (-1)}.</p>
* <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>
* 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>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>
* <p>All indices are specified in <code>char</code> values
* (Unicode code units).
*
* <pre>
* StringUtils.lastIndexOf(null, *, *) = -1