You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2025/04/27 15:01:17 UTC
(commons-lang) branch master updated: Javadoc
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 1ab3b3f0b Javadoc
1ab3b3f0b is described below
commit 1ab3b3f0bfb63df775cbde39b98abee376d3fcfb
Author: Gary D. Gregory <ga...@gmail.com>
AuthorDate: Sun Apr 27 11:01:11 2025 -0400
Javadoc
---
.../java/org/apache/commons/lang3/StringUtils.java | 69 +++++++++++++---------
.../java/org/apache/commons/lang3/Validate.java | 33 ++++++-----
2 files changed, 58 insertions(+), 44 deletions(-)
diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index b2a310288..03cbeb04b 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/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)
*/
diff --git a/src/main/java/org/apache/commons/lang3/Validate.java b/src/main/java/org/apache/commons/lang3/Validate.java
index 51743d8ac..30b0d309a 100644
--- a/src/main/java/org/apache/commons/lang3/Validate.java
+++ b/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.
*