Javadoc

Author: garydgregory

src/main/java/org/apache/commons/lang3/StringUtils.java

@@ -1478,10 +1478,12 @@ public static int countMatches(final CharSequence str, final CharSequence sub) {
     }
 
     /**
-     * Returns either the passed in CharSequence, or if the CharSequence is
-     * whitespace, empty ("") or {@code null}, the value of {@code defaultStr}.
+     * Returns either the passed in CharSequence, or if the CharSequence is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or
+     * {@code null}), the value of {@code defaultStr}.
      *
-     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
+     * <p>
+     * Whitespace is defined by {@link Character#isWhitespace(char)}.
+     * </p>
      *
      * <pre>
      * StringUtils.defaultIfBlank(null, "NULL")  = "NULL"
@@ -1490,12 +1492,14 @@ public static int countMatches(final CharSequence str, final CharSequence sub) {
      * StringUtils.defaultIfBlank("bat", "NULL") = "bat"
      * StringUtils.defaultIfBlank("", null)      = null
      * </pre>
-     * @param <T> the specific kind of CharSequence
-     * @param str the CharSequence to check, may be null
-     * @param defaultStr  the default CharSequence to return
-     *  if {@code str} is whitespace, empty ("") or {@code null}, may be null
+     *
+     * @param <T>        the specific kind of CharSequence
+     * @param str        the CharSequence to check, may be null
+     * @param defaultStr the default CharSequence to return if {@code str} is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code""}) or
+     *                   {@code null}); may be null
      * @return the passed in CharSequence, or the default
      * @see StringUtils#defaultString(String, String)
+     * @see #isBlank(CharSequence)
      */
     public static <T extends CharSequence> T defaultIfBlank(final T str, final T defaultStr) {
         return isBlank(str) ? defaultStr : str;
@@ -2116,12 +2120,16 @@ public static int getFuzzyDistance(final CharSequence term, final CharSequence q
     }
 
     /**
-     * Returns either the passed in CharSequence, or if the CharSequence is
-     * whitespace, empty ("") or {@code null}, the value supplied by {@code defaultStrSupplier}.
+     * Returns either the passed in CharSequence, or if the CharSequence is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or
+     * {@code null}), the value supplied by {@code defaultStrSupplier}.
      *
-     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
+     * <p>
+     * Whitespace is defined by {@link Character#isWhitespace(char)}.
+     * </p>
      *
-     * <p>Caller responsible for thread-safety and exception handling of default value supplier</p>
+     * <p>
+     * Caller responsible for thread-safety and exception handling of default value supplier
+     * </p>
      *
      * <pre>
      * {@code
@@ -2132,12 +2140,14 @@ public static int getFuzzyDistance(final CharSequence term, final CharSequence q
      * StringUtils.getIfBlank("", () -> null)       = null
      * StringUtils.getIfBlank("", null)             = null
      * }</pre>
-     * @param <T> the specific kind of CharSequence
-     * @param str the CharSequence to check, may be null
-     * @param defaultSupplier the supplier of default CharSequence to return
-     *  if the input is whitespace, empty ("") or {@code null}, may be null
+     *
+     * @param <T>             the specific kind of CharSequence
+     * @param str             the CharSequence to check, may be null
+     * @param defaultSupplier the supplier of default CharSequence to return if the input is {@link #isBlank(CharSequence) blank} (whitespaces, empty
+     *                        ({@code ""}) or {@code null}); may be null
      * @return the passed in CharSequence, or the default
      * @see StringUtils#defaultString(String, String)
+     * @see #isBlank(CharSequence)
      * @since 3.10
      */
     public static <T extends CharSequence> T getIfBlank(final T str, final Supplier<T> defaultSupplier) {
@@ -3339,9 +3349,11 @@ public static boolean isAlphaSpace(final CharSequence cs) {
     }
 
     /**
-     * Tests if any of the CharSequences are empty ("") or null or whitespace only.
+     * Tests if any of the CharSequences are {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or {@code null}).
      *
-     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
+     * <p>
+     * Whitespace is defined by {@link Character#isWhitespace(char)}.
+     * </p>
      *
      * <pre>
      * StringUtils.isAnyBlank((String) null)    = true
@@ -3357,8 +3369,9 @@ public static boolean isAlphaSpace(final CharSequence cs) {
      * StringUtils.isAnyBlank("foo", "bar")     = false
      * </pre>
      *
-     * @param css  the CharSequences to check, may be null or empty
-     * @return {@code true} if any of the CharSequences are empty or null or whitespace only
+     * @param css the CharSequences to check, may be null or empty
+     * @return {@code true} if any of the CharSequences are {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or {@code null})
+     * @see #isBlank(CharSequence)
      * @since 3.2
      */
     public static boolean isAnyBlank(final CharSequence... css) {
@@ -3445,9 +3458,7 @@ public static boolean isAsciiPrintable(final CharSequence cs) {
     }
 
     /**
-     * Tests if a CharSequence is empty (""), null or whitespace only.
-     *
-     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
+     * Tests if a CharSequence is empty ({@code "")}, null, or contains only whitespace as defined by {@link Character#isWhitespace(char)}.
      *
      * <pre>
      * StringUtils.isBlank(null)      = true
@@ -3457,7 +3468,7 @@ public static boolean isAsciiPrintable(final CharSequence cs) {
      * StringUtils.isBlank("  bob  ") = false
      * </pre>
      *
-     * @param cs  the CharSequence to check, may be null
+     * @param cs the CharSequence to check, may be null
      * @return {@code true} if the CharSequence is null, empty or whitespace only
      * @since 2.0
      * @since 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
@@ -3594,9 +3605,11 @@ public static boolean isNoneEmpty(final CharSequence... css) {
     }
 
     /**
-     * Tests if a CharSequence is not empty (""), not null and not whitespace only.
+     * Tests if a CharSequence is not {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or {@code null}).
      *
-     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
+     * <p>
+     * Whitespace is defined by {@link Character#isWhitespace(char)}.
+     * </p>
      *
      * <pre>
      * StringUtils.isNotBlank(null)      = false
@@ -3606,9 +3619,9 @@ public static boolean isNoneEmpty(final CharSequence... css) {
      * StringUtils.isNotBlank("  bob  ") = true
      * </pre>
      *
-     * @param cs  the CharSequence to check, may be null
-     * @return {@code true} if the CharSequence is
-     *  not empty and not null and not whitespace only
+     * @param cs the CharSequence to check, may be null
+     * @return {@code true} if the CharSequence is not {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or {@code null})
+     * @see #isBlank(CharSequence)
      * @since 2.0
      * @since 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
      */

src/main/java/org/apache/commons/lang3/Validate.java

@@ -762,7 +762,7 @@ public static <T> T[] noNullElements(final T[] array, final String message, fina
     }
 
     /**
-     * <p>Validate that the specified argument character sequence is
+     * <p>Validates that the specified argument character sequence is
      * neither {@code null}, a length of zero (no characters), empty
      * nor whitespace; otherwise throwing an exception.
      *
@@ -784,21 +784,22 @@ public static <T extends CharSequence> T notBlank(final T chars) {
     }
 
     /**
-     * Validate that the specified argument character sequence is
-     * neither {@code null}, a length of zero (no characters), empty
-     * nor whitespace; otherwise throwing an exception with the specified
-     * message.
+     * Validates that the specified argument character sequence is not {@link StringUtils#isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or
+     * {@code null}); otherwise throwing an exception with the specified message.
      *
-     * <pre>Validate.notBlank(myString, "The string must not be blank");</pre>
+     * <pre>
+     * Validate.notBlank(myString, "The string must not be blank");
+     * </pre>
      *
-     * @param <T> the character sequence type
-     * @param chars  the character sequence to check, validated not null by this method
-     * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
+     * @param <T>     the character sequence type
+     * @param chars   the character sequence to check, validated not null by this method
+     * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated character sequence (never {@code null} method for chaining)
-     * @throws NullPointerException if the character sequence is {@code null}
+     * @throws NullPointerException     if the character sequence is {@code null}
      * @throws IllegalArgumentException if the character sequence is blank
      * @see #notBlank(CharSequence)
+     * @see StringUtils#isBlank(CharSequence)
      * @since 3.0
      */
     public static <T extends CharSequence> T notBlank(final T chars, final String message, final Object... values) {
@@ -810,7 +811,7 @@ public static <T extends CharSequence> T notBlank(final T chars, final String me
     }
 
     /**
-     * <p>Validate that the specified argument collection is neither {@code null}
+     * <p>Validates that the specified argument collection is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myCollection);</pre>
@@ -830,7 +831,7 @@ public static <T extends Collection<?>> T notEmpty(final T collection) {
     }
 
     /**
-     * <p>Validate that the specified argument map is neither {@code null}
+     * <p>Validates that the specified argument map is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myMap);</pre>
@@ -850,7 +851,7 @@ public static <T extends Collection<?>> T notEmpty(final T collection) {
     }
 
     /**
-     * <p>Validate that the specified argument character sequence is
+     * <p>Validates that the specified argument character sequence is
      * neither {@code null} nor a length of zero (no characters);
      * otherwise throwing an exception with the specified message.
      *
@@ -871,7 +872,7 @@ public static <T extends CharSequence> T notEmpty(final T chars) {
     }
 
     /**
-     * <p>Validate that the specified argument collection is neither {@code null}
+     * <p>Validates that the specified argument collection is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception
      * with the specified message.
      *
@@ -943,7 +944,7 @@ public static <T extends CharSequence> T notEmpty(final T chars, final String me
     }
 
     /**
-     * <p>Validate that the specified argument array is neither {@code null}
+     * <p>Validates that the specified argument array is neither {@code null}
      * nor a length of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myArray);</pre>
@@ -963,7 +964,7 @@ public static <T> T[] notEmpty(final T[] array) {
     }
 
     /**
-     * <p>Validate that the specified argument array is neither {@code null}
+     * <p>Validates that the specified argument array is neither {@code null}
      * nor a length of zero (no elements); otherwise throwing an exception
      * with the specified message.
      *