{@code BooleanUtils} instances should NOT be constructed in standard programming.
- * Instead, the class should be used as {@code BooleanUtils.negate(true);}.
+ * The false String {@code "false"}.
*
- * This constructor is public to permit tools that require a JavaBean instance
- * to operate.
+ * @since 3.12.0
*/
- public BooleanUtils() {
- super();
- }
+ public static final String FALSE = "false";
- // Boolean utilities
- //--------------------------------------------------------------------------
/**
- * Negates the specified boolean.
+ * The no String {@code "no"}.
*
- * If {@code null} is passed in, {@code null} will be returned.
+ * @since 3.12.0
+ */
+ public static final String NO = "no";
+
+ /**
+ * The off String {@code "off"}.
+ *
+ * @since 3.12.0
+ */
+ public static final String OFF = "off";
+
+ /**
+ * The on String {@code "on"}.
+ *
+ * @since 3.12.0
+ */
+ public static final String ON = "on";
+
+ /**
+ * The true String {@code "true"}.
+ *
+ * @since 3.12.0
+ */
+ public static final String TRUE = "true";
+
+ /**
+ * The yes String {@code "yes"}.
*
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ * @since 3.12.0
+ */
+ public static final String YES = "yes";
+
+ /**
+ * Performs an 'and' operation on a set of booleans.
*
* Checks if a {@code Boolean} value is {@code true},
- * handling {@code null} by returning {@code false}.
- *
+ * Performs an 'and' operation on an array of Booleans.
*
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
+ *
+ *
+ * @param array an array of {@link Boolean}s
+ * @return the result of the logical 'and' operation. That is {@code false}
+ * if any of the parameters is {@code false} and {@code true} otherwise.
+ * @throws NullPointerException if {@code array} is {@code null}
+ * @throws IllegalArgumentException if {@code array} is empty.
+ * @since 3.0.1
+ */
+ public static Boolean and(final Boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ return and(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
+ }
+
+ /**
+ * Returns a new array of possible values (like an enum would).
*
- * @param bool the boolean to check, null returns {@code false}
- * @return {@code true} only if the input is non-null and true
- * @since 2.1
+ * @return a new array of possible values (like an enum would).
+ * @since 3.12.0
*/
- public static boolean isTrue(final Boolean bool) {
- return Boolean.TRUE.equals(bool);
+ public static Boolean[] booleanValues() {
+ return new Boolean[] {Boolean.FALSE, Boolean.TRUE};
}
/**
- * action) {
+ values().forEach(action);
}
/**
- * Checks if a {@code Boolean} value is {@code false},
- * handling {@code null} by returning {@code false}.
+ * Checks if a {@link Boolean} value is {@code false},
+ * handling {@code null} by returning {@code false}.
*
*
* BooleanUtils.isFalse(Boolean.TRUE) = false
@@ -115,7 +183,7 @@ public static boolean isNotTrue(final Boolean bool) {
*
*
* @param bool the boolean to check, null returns {@code false}
- * @return {@code true} only if the input is non-null and false
+ * @return {@code true} only if the input is non-{@code null} and {@code false}
* @since 2.1
*/
public static boolean isFalse(final Boolean bool) {
@@ -123,8 +191,8 @@ public static boolean isFalse(final Boolean bool) {
}
/**
- * Checks if a {@code Boolean} value is not {@code false},
- * handling {@code null} by returning {@code true}.
+ * Checks if a {@link Boolean} value is not {@code false},
+ * handling {@code null} by returning {@code true}.
*
*
* BooleanUtils.isNotFalse(Boolean.TRUE) = true
@@ -133,129 +201,243 @@ public static boolean isFalse(final Boolean bool) {
*
*
* @param bool the boolean to check, null returns {@code true}
- * @return {@code true} if the input is null or true
+ * @return {@code true} if the input is {@code null} or {@code true}
* @since 2.3
*/
public static boolean isNotFalse(final Boolean bool) {
return !isFalse(bool);
}
- //-----------------------------------------------------------------------
/**
- * Converts a Boolean to a boolean handling {@code null}
- * by returning {@code false}.
+ * Checks if a {@link Boolean} value is not {@code true},
+ * handling {@code null} by returning {@code true}.
*
*
- * BooleanUtils.toBoolean(Boolean.TRUE) = true
- * BooleanUtils.toBoolean(Boolean.FALSE) = false
- * BooleanUtils.toBoolean(null) = false
+ * BooleanUtils.isNotTrue(Boolean.TRUE) = false
+ * BooleanUtils.isNotTrue(Boolean.FALSE) = true
+ * BooleanUtils.isNotTrue(null) = true
*
*
- * @param bool the boolean to convert
- * @return {@code true} or {@code false}, {@code null} returns {@code false}
+ * @param bool the boolean to check, null returns {@code true}
+ * @return {@code true} if the input is null or false
+ * @since 2.3
*/
- public static boolean toBoolean(final Boolean bool) {
- return bool != null && bool.booleanValue();
+ public static boolean isNotTrue(final Boolean bool) {
+ return !isTrue(bool);
}
/**
- * Converts a Boolean to a boolean handling {@code null}.
+ * Checks if a {@link Boolean} value is {@code true},
+ * handling {@code null} by returning {@code false}.
*
*
- * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
- * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
- * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
+ * BooleanUtils.isTrue(Boolean.TRUE) = true
+ * BooleanUtils.isTrue(Boolean.FALSE) = false
+ * BooleanUtils.isTrue(null) = false
*
*
- * @param bool the boolean to convert
- * @param valueIfNull the boolean value to return if {@code null}
- * @return {@code true} or {@code false}
+ * @param bool the boolean to check, {@code null} returns {@code false}
+ * @return {@code true} only if the input is non-null and true
+ * @since 2.1
*/
- public static boolean toBooleanDefaultIfNull(final Boolean bool, final boolean valueIfNull) {
+ public static boolean isTrue(final Boolean bool) {
+ return Boolean.TRUE.equals(bool);
+ }
+
+ /**
+ * Negates the specified boolean.
+ *
+ * If {@code null} is passed in, {@code null} will be returned.
+ *
+ * NOTE: This returns {@code null} and will throw a {@link NullPointerException}
+ * if unboxed to a boolean.
+ *
+ *
+ * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
+ * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
+ * BooleanUtils.negate(null) = null;
+ *
+ *
+ * @param bool the Boolean to negate, may be null
+ * @return the negated Boolean, or {@code null} if {@code null} input
+ */
+ public static Boolean negate(final Boolean bool) {
if (bool == null) {
- return valueIfNull;
+ return null;
}
- return bool.booleanValue();
+ return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
+ }
+
+ /**
+ * Performs a one-hot on an array of booleans.
+ *
+ * This implementation returns true if one, and only one, of the supplied values is true.
+ *
+ *
+ * See also One-hot.
+ *
+ *
+ * @param array an array of {@code boolean}s
+ * @return the result of the one-hot operations
+ * @throws NullPointerException if {@code array} is {@code null}
+ * @throws IllegalArgumentException if {@code array} is empty.
+ */
+ public static boolean oneHot(final boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ boolean result = false;
+ for (final boolean element: array) {
+ if (element) {
+ if (result) {
+ return false;
+ }
+ result = true;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Performs a one-hot on an array of booleans.
+ *
+ * This implementation returns true if one, and only one, of the supplied values is true.
+ *
+ *
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
+ *
+ *
+ * See also One-hot.
+ *
+ *
+ * @param array an array of {@code boolean}s
+ * @return the result of the one-hot operations
+ * @throws NullPointerException if {@code array} is {@code null}
+ * @throws IllegalArgumentException if {@code array} is empty.
+ */
+ public static Boolean oneHot(final Boolean... array) {
+ return Boolean.valueOf(oneHot(ArrayUtils.toPrimitive(array)));
}
- // Integer to Boolean methods
- //-----------------------------------------------------------------------
/**
- * Converts an int to a boolean using the convention that {@code zero}
- * is {@code false}.
+ * Performs an 'or' operation on a set of booleans.
*
*
- * BooleanUtils.toBoolean(0) = false
- * BooleanUtils.toBoolean(1) = true
- * BooleanUtils.toBoolean(2) = true
+ * BooleanUtils.or(true, true) = true
+ * BooleanUtils.or(false, false) = false
+ * BooleanUtils.or(true, false) = true
+ * BooleanUtils.or(true, true, false) = true
+ * BooleanUtils.or(true, true, true) = true
+ * BooleanUtils.or(false, false, false) = false
*
*
- * @param value the int to convert
- * @return {@code true} if non-zero, {@code false}
- * if zero
+ * @param array an array of {@code boolean}s
+ * @return {@code true} if any of the arguments is {@code true}, and it returns {@code false} otherwise.
+ * @throws NullPointerException if {@code array} is {@code null}
+ * @throws IllegalArgumentException if {@code array} is empty.
+ * @since 3.0.1
*/
- public static boolean toBoolean(final int value) {
- return value != 0;
+ public static boolean or(final boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ for (final boolean element : array) {
+ if (element) {
+ return true;
+ }
+ }
+ return false;
}
/**
- * Converts an int to a Boolean using the convention that {@code zero}
- * is {@code false}.
- *
+ * Performs an 'or' operation on an array of Booleans.
*
- * BooleanUtils.toBoolean(0) = Boolean.FALSE
- * BooleanUtils.toBoolean(1) = Boolean.TRUE
- * BooleanUtils.toBoolean(2) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
+ * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
+ * BooleanUtils.or(Boolean.TRUE, null) = Boolean.TRUE
+ * BooleanUtils.or(Boolean.FALSE, null) = Boolean.FALSE
*
+ *
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
+ *
*
- * @param value the int to convert
- * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
- * {@code null} if {@code null}
+ * @param array an array of {@link Boolean}s
+ * @return {@code true} if any of the arguments is {@code true}, and it returns {@code false} otherwise.
+ * @throws NullPointerException if {@code array} is {@code null}
+ * @throws IllegalArgumentException if {@code array} is empty.
+ * @since 3.0.1
*/
- public static Boolean toBooleanObject(final int value) {
- return value == 0 ? Boolean.FALSE : Boolean.TRUE;
+ public static Boolean or(final Boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ return or(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
}
/**
- * Converts an Integer to a Boolean using the convention that {@code zero}
- * is {@code false}.
+ * Returns a new array of possible values (like an enum would).
*
- * {@code null} will be converted to {@code null}.
+ * @return a new array of possible values (like an enum would).
+ * @since 3.12.0
+ */
+ public static boolean[] primitiveValues() {
+ return new boolean[] {false, true};
+ }
+
+ /**
+ * Converts a Boolean to a boolean handling {@code null}
+ * by returning {@code false}.
*
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ *
+ * BooleanUtils.toBoolean(Boolean.TRUE) = true
+ * BooleanUtils.toBoolean(Boolean.FALSE) = false
+ * BooleanUtils.toBoolean(null) = false
+ *
+ *
+ * @param bool the boolean to convert
+ * @return {@code true} or {@code false}, {@code null} returns {@code false}
+ */
+ public static boolean toBoolean(final Boolean bool) {
+ return bool != null && bool.booleanValue();
+ }
+
+ /**
+ * Converts an int to a boolean using the convention that {@code zero}
+ * is {@code false}, everything else is {@code true}.
*
*
- * BooleanUtils.toBoolean(Integer.valueOf(0)) = Boolean.FALSE
- * BooleanUtils.toBoolean(Integer.valueOf(1)) = Boolean.TRUE
- * BooleanUtils.toBoolean(Integer.valueOf(null)) = null
+ * BooleanUtils.toBoolean(0) = false
+ * BooleanUtils.toBoolean(1) = true
+ * BooleanUtils.toBoolean(2) = true
*
*
- * @param value the Integer to convert
- * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
- * {@code null} if {@code null} input
+ * @param value the int to convert
+ * @return {@code true} if non-zero, {@code false}
+ * if zero
*/
- public static Boolean toBooleanObject(final Integer value) {
- if (value == null) {
- return null;
- }
- return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
+ public static boolean toBoolean(final int value) {
+ return value != 0;
}
/**
- * Converts an int to a boolean specifying the conversion values.
+ * Converts an int to a boolean specifying the conversion values.
+ *
+ * If the {@code trueValue} and {@code falseValue} are the same number then
+ * the return value will be {@code true} in case {@code value} matches it.
*
*
* BooleanUtils.toBoolean(0, 1, 0) = false
* BooleanUtils.toBoolean(1, 1, 0) = true
+ * BooleanUtils.toBoolean(1, 1, 1) = true
* BooleanUtils.toBoolean(2, 1, 2) = false
* BooleanUtils.toBoolean(2, 2, 0) = true
*
*
- * @param value the Integer to convert
+ * @param value the {@link Integer} to convert
* @param trueValue the value to match for {@code true}
* @param falseValue the value to match for {@code false}
* @return {@code true} or {@code false}
- * @throws IllegalArgumentException if no match
+ * @throws IllegalArgumentException if {@code value} does not match neither
+ * {@code trueValue} no {@code falseValue}
*/
public static boolean toBoolean(final int value, final int trueValue, final int falseValue) {
if (value == trueValue) {
@@ -264,12 +446,11 @@ public static boolean toBoolean(final int value, final int trueValue, final int
if (value == falseValue) {
return false;
}
- // no match
throw new IllegalArgumentException("The Integer did not match either specified value");
}
/**
- * Converts an Integer to a boolean specifying the conversion values.
+ * Converts an Integer to a boolean specifying the conversion values.
*
*
* BooleanUtils.toBoolean(Integer.valueOf(0), Integer.valueOf(1), Integer.valueOf(0)) = false
@@ -298,230 +479,239 @@ public static boolean toBoolean(final Integer value, final Integer trueValue, fi
} else if (value.equals(falseValue)) {
return false;
}
- // no match
throw new IllegalArgumentException("The Integer did not match either specified value");
}
/**
- * Converts an int to a Boolean specifying the conversion values.
+ * Converts a String to a boolean (optimized for performance).
*
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ * {@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
+ * (case insensitive) will return {@code true}. Otherwise,
+ * {@code false} is returned.
*
- *
- * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
- * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
- * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
- *
+ * This method performs 4 times faster (JDK1.4) than
+ * {@code Boolean.valueOf(String)}. However, this method accepts
+ * 'on' and 'yes', 't', 'y' as true values.
*
- * @param value the Integer to convert
- * @param trueValue the value to match for {@code true}
- * @param falseValue the value to match for {@code false}
- * @param nullValue the value to to match for {@code null}
- * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
- * @throws IllegalArgumentException if no match
+ *
+ * BooleanUtils.toBoolean(null) = false
+ * BooleanUtils.toBoolean("true") = true
+ * BooleanUtils.toBoolean("TRUE") = true
+ * BooleanUtils.toBoolean("tRUe") = true
+ * BooleanUtils.toBoolean("on") = true
+ * BooleanUtils.toBoolean("yes") = true
+ * BooleanUtils.toBoolean("false") = false
+ * BooleanUtils.toBoolean("x gti") = false
+ * BooleanUtils.toBoolean("y") = true
+ * BooleanUtils.toBoolean("n") = false
+ * BooleanUtils.toBoolean("t") = true
+ * BooleanUtils.toBoolean("f") = false
+ *
+ *
+ * @param str the String to check
+ * @return the boolean value of the string, {@code false} if no match or the String is null
*/
- public static Boolean toBooleanObject(final int value, final int trueValue, final int falseValue, final int nullValue) {
- if (value == trueValue) {
- return Boolean.TRUE;
- }
- if (value == falseValue) {
- return Boolean.FALSE;
- }
- if (value == nullValue) {
- return null;
- }
- // no match
- throw new IllegalArgumentException("The Integer did not match any specified value");
+ public static boolean toBoolean(final String str) {
+ return toBooleanObject(str) == Boolean.TRUE;
}
/**
- * Converts an Integer to a Boolean specifying the conversion values.
- *
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ * Converts a String to a Boolean throwing an exception if no match found.
*
*
- * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
- * BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
- * BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = null
+ * BooleanUtils.toBoolean("true", "true", "false") = true
+ * BooleanUtils.toBoolean("false", "true", "false") = false
*
*
- * @param value the Integer to convert
- * @param trueValue the value to match for {@code true}, may be {@code null}
- * @param falseValue the value to match for {@code false}, may be {@code null}
- * @param nullValue the value to to match for {@code null}, may be {@code null}
- * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
- * @throws IllegalArgumentException if no match
+ * @param str the String to check
+ * @param trueString the String to match for {@code true} (case-sensitive), may be {@code null}
+ * @param falseString the String to match for {@code false} (case-sensitive), may be {@code null}
+ * @return the boolean value of the string
+ * @throws IllegalArgumentException if the String doesn't match
*/
- public static Boolean toBooleanObject(final Integer value, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
- if (value == null) {
- if (trueValue == null) {
- return Boolean.TRUE;
- }
- if (falseValue == null) {
- return Boolean.FALSE;
+ public static boolean toBoolean(final String str, final String trueString, final String falseString) {
+ if (str == trueString) {
+ return true;
+ }
+ if (str == falseString) {
+ return false;
+ }
+ if (str != null) {
+ if (str.equals(trueString)) {
+ return true;
}
- if (nullValue == null) {
- return null;
+ if (str.equals(falseString)) {
+ return false;
}
- } else if (value.equals(trueValue)) {
- return Boolean.TRUE;
- } else if (value.equals(falseValue)) {
- return Boolean.FALSE;
- } else if (value.equals(nullValue)) {
- return null;
}
- // no match
- throw new IllegalArgumentException("The Integer did not match any specified value");
+ throw new IllegalArgumentException("The String did not match either specified value");
}
- // Boolean to Integer methods
- //-----------------------------------------------------------------------
/**
- * Converts a boolean to an int using the convention that
- * {@code zero} is {@code false}.
+ * Converts a Boolean to a boolean handling {@code null}.
*
*
- * BooleanUtils.toInteger(true) = 1
- * BooleanUtils.toInteger(false) = 0
+ * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
+ * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, true) = true
+ * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
+ * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, false) = false
+ * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
+ * BooleanUtils.toBooleanDefaultIfNull(null, false) = false
*
*
- * @param bool the boolean to convert
- * @return one if {@code true}, zero if {@code false}
+ * @param bool the boolean object to convert to primitive
+ * @param valueIfNull the boolean value to return if the parameter {@code bool} is {@code null}
+ * @return {@code true} or {@code false}
*/
- public static int toInteger(final boolean bool) {
- return bool ? 1 : 0;
+ public static boolean toBooleanDefaultIfNull(final Boolean bool, final boolean valueIfNull) {
+ if (bool == null) {
+ return valueIfNull;
+ }
+ return bool.booleanValue();
}
/**
- * Converts a boolean to an Integer using the convention that
- * {@code zero} is {@code false}.
+ * Converts an int to a Boolean using the convention that {@code zero}
+ * is {@code false}, everything else is {@code true}.
*
*
- * BooleanUtils.toIntegerObject(true) = Integer.valueOf(1)
- * BooleanUtils.toIntegerObject(false) = Integer.valueOf(0)
+ * BooleanUtils.toBoolean(0) = Boolean.FALSE
+ * BooleanUtils.toBoolean(1) = Boolean.TRUE
+ * BooleanUtils.toBoolean(2) = Boolean.TRUE
*
*
- * @param bool the boolean to convert
- * @return one if {@code true}, zero if {@code false}
+ * @param value the int to convert
+ * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
+ * {@code null} if {@code null}
*/
- public static Integer toIntegerObject(final boolean bool) {
- return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
+ public static Boolean toBooleanObject(final int value) {
+ return value == 0 ? Boolean.FALSE : Boolean.TRUE;
}
/**
- * Converts a Boolean to a Integer using the convention that
- * {@code zero} is {@code false}.
+ * Converts an int to a Boolean specifying the conversion values.
*
- * {@code null} will be converted to {@code null}.
+ * NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
+ * if unboxed to a {@code boolean}.
+ *
+ * The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
+ * finally for the {@code nullValue}.
*
*
- * BooleanUtils.toIntegerObject(Boolean.TRUE) = Integer.valueOf(1)
- * BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(0)
+ * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(0, 0, 0, 3) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(0, 0, 0, 0) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(2, 1, 2, 2) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
*
*
- * @param bool the Boolean to convert
- * @return one if Boolean.TRUE, zero if Boolean.FALSE, {@code null} if {@code null}
+ * @param value the Integer to convert
+ * @param trueValue the value to match for {@code true}
+ * @param falseValue the value to match for {@code false}
+ * @param nullValue the value to match for {@code null}
+ * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
+ * @throws IllegalArgumentException if no match
*/
- public static Integer toIntegerObject(final Boolean bool) {
- if (bool == null) {
+ public static Boolean toBooleanObject(final int value, final int trueValue, final int falseValue, final int nullValue) {
+ if (value == trueValue) {
+ return Boolean.TRUE;
+ }
+ if (value == falseValue) {
+ return Boolean.FALSE;
+ }
+ if (value == nullValue) {
return null;
}
- return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
+ throw new IllegalArgumentException("The Integer did not match any specified value");
}
/**
- * Converts a boolean to an int specifying the conversion values.
+ * Converts an Integer to a Boolean using the convention that {@code zero}
+ * is {@code false}, every other numeric value is {@code true}.
*
- *
- * BooleanUtils.toInteger(true, 1, 0) = 1
- * BooleanUtils.toInteger(false, 1, 0) = 0
- *
+ * {@code null} will be converted to {@code null}.
*
- * @param bool the to convert
- * @param trueValue the value to return if {@code true}
- * @param falseValue the value to return if {@code false}
- * @return the appropriate value
- */
- public static int toInteger(final boolean bool, final int trueValue, final int falseValue) {
- return bool ? trueValue : falseValue;
- }
-
- /**
- * Converts a Boolean to an int specifying the conversion values.
+ * NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
+ * if unboxed to a {@code boolean}.
*
*
- * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
- * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
- * BooleanUtils.toInteger(null, 1, 0, 2) = 2
+ * BooleanUtils.toBooleanObject(Integer.valueOf(0)) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(1)) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(null)) = null
*
*
- * @param bool the Boolean to convert
- * @param trueValue the value to return if {@code true}
- * @param falseValue the value to return if {@code false}
- * @param nullValue the value to return if {@code null}
- * @return the appropriate value
+ * @param value the Integer to convert
+ * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
+ * {@code null} if {@code null} input
*/
- public static int toInteger(final Boolean bool, final int trueValue, final int falseValue, final int nullValue) {
- if (bool == null) {
- return nullValue;
+ public static Boolean toBooleanObject(final Integer value) {
+ if (value == null) {
+ return null;
}
- return bool.booleanValue() ? trueValue : falseValue;
+ return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
}
/**
- * Converts a boolean to an Integer specifying the conversion values.
+ * Converts an Integer to a Boolean specifying the conversion values.
*
- *
- * BooleanUtils.toIntegerObject(true, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(1)
- * BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(0)
- *
- *
- * @param bool the to convert
- * @param trueValue the value to return if {@code true}, may be {@code null}
- * @param falseValue the value to return if {@code false}, may be {@code null}
- * @return the appropriate value
- */
- public static Integer toIntegerObject(final boolean bool, final Integer trueValue, final Integer falseValue) {
- return bool ? trueValue : falseValue;
- }
-
- /**
- * Converts a Boolean to an Integer specifying the conversion values.
+ * NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
+ * if unboxed to a {@code boolean}.
*
+ * The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
+ * finally for the {@code nullValue}.
+ **
*
- * BooleanUtils.toIntegerObject(Boolean.TRUE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(1)
- * BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
- * BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(2)
+ * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(3)) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0)) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(2)) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = null
*
*
- * @param bool the Boolean to convert
- * @param trueValue the value to return if {@code true}, may be {@code null}
- * @param falseValue the value to return if {@code false}, may be {@code null}
- * @param nullValue the value to return if {@code null}, may be {@code null}
- * @return the appropriate value
+ * @param value the Integer to convert
+ * @param trueValue the value to match for {@code true}, may be {@code null}
+ * @param falseValue the value to match for {@code false}, may be {@code null}
+ * @param nullValue the value to match for {@code null}, may be {@code null}
+ * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
+ * @throws IllegalArgumentException if no match
*/
- public static Integer toIntegerObject(final Boolean bool, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
- if (bool == null) {
- return nullValue;
+ public static Boolean toBooleanObject(final Integer value, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
+ if (value == null) {
+ if (trueValue == null) {
+ return Boolean.TRUE;
+ }
+ if (falseValue == null) {
+ return Boolean.FALSE;
+ }
+ if (nullValue == null) {
+ return null;
+ }
+ } else if (value.equals(trueValue)) {
+ return Boolean.TRUE;
+ } else if (value.equals(falseValue)) {
+ return Boolean.FALSE;
+ } else if (value.equals(nullValue)) {
+ return null;
}
- return bool.booleanValue() ? trueValue : falseValue;
+ throw new IllegalArgumentException("The Integer did not match any specified value");
}
- // String to Boolean methods
- //-----------------------------------------------------------------------
/**
- * Converts a String to a Boolean.
+ * Converts a String to a Boolean.
*
- * {@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
- * (case insensitive) will return {@code true}.
- * {@code 'false'}, {@code 'off'}, {@code 'n'}, {@code 'f'} or {@code 'no'}
- * (case insensitive) will return {@code false}.
+ *
{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'}, {@code 'yes'}
+ * or {@code '1'} (case insensitive) will return {@code true}.
+ * {@code 'false'}, {@code 'off'}, {@code 'n'}, {@code 'f'}, {@code 'no'}
+ * or {@code '0'} (case insensitive) will return {@code false}.
* Otherwise, {@code null} is returned.
*
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ * NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
+ * if unboxed to a {@code boolean}.
*
*
- * // N.B. case is not significant
+ * // Case is not significant
* BooleanUtils.toBooleanObject(null) = null
* BooleanUtils.toBooleanObject("true") = Boolean.TRUE
* BooleanUtils.toBooleanObject("T") = Boolean.TRUE // i.e. T[RUE]
@@ -535,6 +725,8 @@ public static Integer toIntegerObject(final Boolean bool, final Integer trueValu
* BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
* BooleanUtils.toBooleanObject("yes") = Boolean.TRUE
* BooleanUtils.toBooleanObject("Y") = Boolean.TRUE // i.e. Y[ES]
+ * BooleanUtils.toBooleanObject("1") = Boolean.TRUE
+ * BooleanUtils.toBooleanObject("0") = Boolean.FALSE
* BooleanUtils.toBooleanObject("blue") = null
* BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
* BooleanUtils.toBooleanObject("ono") = null // does not match on or no
@@ -547,10 +739,10 @@ public static Boolean toBooleanObject(final String str) {
// Previously used equalsIgnoreCase, which was fast for interned 'true'.
// Non interned 'true' matched 15 times slower.
//
- // Optimisation provides same performance as before for interned 'true'.
+ // Optimization provides same performance as before for interned 'true'.
// Similar performance for null, 'false', and other strings not length 2/3/4.
// 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
- if (str == "true") {
+ if (str == TRUE) {
return Boolean.TRUE;
}
if (str == null) {
@@ -560,11 +752,13 @@ public static Boolean toBooleanObject(final String str) {
case 1: {
final char ch0 = str.charAt(0);
if (ch0 == 'y' || ch0 == 'Y' ||
- ch0 == 't' || ch0 == 'T') {
+ ch0 == 't' || ch0 == 'T' ||
+ ch0 == '1') {
return Boolean.TRUE;
}
if (ch0 == 'n' || ch0 == 'N' ||
- ch0 == 'f' || ch0 == 'F') {
+ ch0 == 'f' || ch0 == 'F' ||
+ ch0 == '0') {
return Boolean.FALSE;
}
break;
@@ -573,11 +767,11 @@ public static Boolean toBooleanObject(final String str) {
final char ch0 = str.charAt(0);
final char ch1 = str.charAt(1);
if ((ch0 == 'o' || ch0 == 'O') &&
- (ch1 == 'n' || ch1 == 'N') ) {
+ (ch1 == 'n' || ch1 == 'N')) {
return Boolean.TRUE;
}
if ((ch0 == 'n' || ch0 == 'N') &&
- (ch1 == 'o' || ch1 == 'O') ) {
+ (ch1 == 'o' || ch1 == 'O')) {
return Boolean.FALSE;
}
break;
@@ -588,12 +782,12 @@ public static Boolean toBooleanObject(final String str) {
final char ch2 = str.charAt(2);
if ((ch0 == 'y' || ch0 == 'Y') &&
(ch1 == 'e' || ch1 == 'E') &&
- (ch2 == 's' || ch2 == 'S') ) {
+ (ch2 == 's' || ch2 == 'S')) {
return Boolean.TRUE;
}
if ((ch0 == 'o' || ch0 == 'O') &&
(ch1 == 'f' || ch1 == 'F') &&
- (ch2 == 'f' || ch2 == 'F') ) {
+ (ch2 == 'f' || ch2 == 'F')) {
return Boolean.FALSE;
}
break;
@@ -606,7 +800,7 @@ public static Boolean toBooleanObject(final String str) {
if ((ch0 == 't' || ch0 == 'T') &&
(ch1 == 'r' || ch1 == 'R') &&
(ch2 == 'u' || ch2 == 'U') &&
- (ch3 == 'e' || ch3 == 'E') ) {
+ (ch3 == 'e' || ch3 == 'E')) {
return Boolean.TRUE;
}
break;
@@ -621,7 +815,7 @@ public static Boolean toBooleanObject(final String str) {
(ch1 == 'a' || ch1 == 'A') &&
(ch2 == 'l' || ch2 == 'L') &&
(ch3 == 's' || ch3 == 'S') &&
- (ch4 == 'e' || ch4 == 'E') ) {
+ (ch4 == 'e' || ch4 == 'E')) {
return Boolean.FALSE;
}
break;
@@ -634,20 +828,27 @@ public static Boolean toBooleanObject(final String str) {
}
/**
- * Converts a String to a Boolean throwing an exception if no match.
+ * Converts a String to a Boolean throwing an exception if no match.
*
- * NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean.
+ * NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
+ * if unboxed to a {@code boolean}.
*
*
- * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
- * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
- * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
+ * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(null, null, "false", "null") = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(null, null, null, "null") = Boolean.TRUE
+ * BooleanUtils.toBooleanObject(null, null, null, null) = Boolean.TRUE
+ * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
+ * BooleanUtils.toBooleanObject("false", "true", "false", "false") = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(null, "true", null, "false") = Boolean.FALSE
+ * BooleanUtils.toBooleanObject(null, "true", null, null) = Boolean.FALSE
+ * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
*
*
* @param str the String to check
- * @param trueString the String to match for {@code true} (case sensitive), may be {@code null}
- * @param falseString the String to match for {@code false} (case sensitive), may be {@code null}
- * @param nullString the String to match for {@code null} (case sensitive), may be {@code null}
+ * @param trueString the String to match for {@code true} (case-sensitive), may be {@code null}
+ * @param falseString the String to match for {@code false} (case-sensitive), may be {@code null}
+ * @param nullString the String to match for {@code null} (case-sensitive), may be {@code null}
* @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
* or if {@code null} input and {@code nullString} is {@code null}
* @throws IllegalArgumentException if the String doesn't match
@@ -674,126 +875,156 @@ public static Boolean toBooleanObject(final String str, final String trueString,
throw new IllegalArgumentException("The String did not match any specified value");
}
- // String to boolean methods
- //-----------------------------------------------------------------------
/**
- * Converts a String to a boolean (optimised for performance).
+ * Converts a boolean to an int using the convention that
+ * {@code true} is {@code 1} and {@code false} is {@code 0}.
*
- * {@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
- * (case insensitive) will return {@code true}. Otherwise,
- * {@code false} is returned.
+ *
+ * BooleanUtils.toInteger(true) = 1
+ * BooleanUtils.toInteger(false) = 0
+ *
*
- * This method performs 4 times faster (JDK1.4) than
- * {@code Boolean.valueOf(String)}. However, this method accepts
- * 'on' and 'yes', 't', 'y' as true values.
+ * @param bool the boolean to convert
+ * @return one if {@code true}, zero if {@code false}
+ */
+ public static int toInteger(final boolean bool) {
+ return bool ? 1 : 0;
+ }
+
+ /**
+ * Converts a boolean to an int specifying the conversion values.
*
*
- * BooleanUtils.toBoolean(null) = false
- * BooleanUtils.toBoolean("true") = true
- * BooleanUtils.toBoolean("TRUE") = true
- * BooleanUtils.toBoolean("tRUe") = true
- * BooleanUtils.toBoolean("on") = true
- * BooleanUtils.toBoolean("yes") = true
- * BooleanUtils.toBoolean("false") = false
- * BooleanUtils.toBoolean("x gti") = false
- * BooleanUtils.toBooleanObject("y") = true
- * BooleanUtils.toBooleanObject("n") = false
- * BooleanUtils.toBooleanObject("t") = true
- * BooleanUtils.toBooleanObject("f") = false
+ * BooleanUtils.toInteger(true, 1, 0) = 1
+ * BooleanUtils.toInteger(false, 1, 0) = 0
*
*
- * @param str the String to check
- * @return the boolean value of the string, {@code false} if no match or the String is null
+ * @param bool the to convert
+ * @param trueValue the value to return if {@code true}
+ * @param falseValue the value to return if {@code false}
+ * @return the appropriate value
*/
- public static boolean toBoolean(final String str) {
- return toBooleanObject(str) == Boolean.TRUE;
+ public static int toInteger(final boolean bool, final int trueValue, final int falseValue) {
+ return bool ? trueValue : falseValue;
}
/**
- * Converts a String to a Boolean throwing an exception if no match found.
+ * Converts a Boolean to an int specifying the conversion values.
*
*
- * BooleanUtils.toBoolean("true", "true", "false") = true
- * BooleanUtils.toBoolean("false", "true", "false") = false
+ * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
+ * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
+ * BooleanUtils.toInteger(null, 1, 0, 2) = 2
*
*
- * @param str the String to check
- * @param trueString the String to match for {@code true} (case sensitive), may be {@code null}
- * @param falseString the String to match for {@code false} (case sensitive), may be {@code null}
- * @return the boolean value of the string
- * @throws IllegalArgumentException if the String doesn't match
+ * @param bool the Boolean to convert
+ * @param trueValue the value to return if {@code true}
+ * @param falseValue the value to return if {@code false}
+ * @param nullValue the value to return if {@code null}
+ * @return the appropriate value
*/
- public static boolean toBoolean(final String str, final String trueString, final String falseString) {
- if (str == trueString) {
- return true;
- } else if (str == falseString) {
- return false;
- } else if (str != null) {
- if (str.equals(trueString)) {
- return true;
- } else if (str.equals(falseString)) {
- return false;
- }
+ public static int toInteger(final Boolean bool, final int trueValue, final int falseValue, final int nullValue) {
+ if (bool == null) {
+ return nullValue;
}
- // no match
- throw new IllegalArgumentException("The String did not match either specified value");
+ return bool.booleanValue() ? trueValue : falseValue;
}
- // Boolean to String methods
- //-----------------------------------------------------------------------
/**
- * Converts a Boolean to a String returning {@code 'true'},
- * {@code 'false'}, or {@code null}.
+ * Converts a boolean to an Integer using the convention that
+ * {@code true} is {@code 1} and {@code false} is {@code 0}.
*
*
- * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
- * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
- * BooleanUtils.toStringTrueFalse(null) = null;
+ * BooleanUtils.toIntegerObject(true) = Integer.valueOf(1)
+ * BooleanUtils.toIntegerObject(false) = Integer.valueOf(0)
*
*
- * @param bool the Boolean to check
- * @return {@code 'true'}, {@code 'false'}, or {@code null}
+ * @param bool the boolean to convert
+ * @return one if {@code true}, zero if {@code false}
*/
- public static String toStringTrueFalse(final Boolean bool) {
- return toString(bool, "true", "false", null);
+ public static Integer toIntegerObject(final boolean bool) {
+ return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
}
/**
- * Converts a Boolean to a String returning {@code 'on'},
- * {@code 'off'}, or {@code null}.
+ * Converts a boolean to an Integer specifying the conversion values.
*
*
- * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
- * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
- * BooleanUtils.toStringOnOff(null) = null;
+ * BooleanUtils.toIntegerObject(true, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(1)
+ * BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(0)
*
*
- * @param bool the Boolean to check
- * @return {@code 'on'}, {@code 'off'}, or {@code null}
+ * @param bool the to convert
+ * @param trueValue the value to return if {@code true}, may be {@code null}
+ * @param falseValue the value to return if {@code false}, may be {@code null}
+ * @return the appropriate value
*/
- public static String toStringOnOff(final Boolean bool) {
- return toString(bool, "on", "off", null);
+ public static Integer toIntegerObject(final boolean bool, final Integer trueValue, final Integer falseValue) {
+ return bool ? trueValue : falseValue;
}
/**
- * Converts a Boolean to a String returning {@code 'yes'},
- * {@code 'no'}, or {@code null}.
+ * Converts a Boolean to an Integer using the convention that
+ * {@code zero} is {@code false}.
+ *
+ * {@code null} will be converted to {@code null}.
*
*
- * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
- * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
- * BooleanUtils.toStringYesNo(null) = null;
+ * BooleanUtils.toIntegerObject(Boolean.TRUE) = Integer.valueOf(1)
+ * BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(0)
+ *
+ *
+ * @param bool the Boolean to convert
+ * @return one if Boolean.TRUE, zero if Boolean.FALSE, {@code null} if {@code null}
+ */
+ public static Integer toIntegerObject(final Boolean bool) {
+ if (bool == null) {
+ return null;
+ }
+ return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
+ }
+
+ /**
+ * Converts a Boolean to an Integer specifying the conversion values.
+ *
+ *
+ * BooleanUtils.toIntegerObject(Boolean.TRUE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(1)
+ * BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
+ * BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(2)
+ *
+ *
+ * @param bool the Boolean to convert
+ * @param trueValue the value to return if {@code true}, may be {@code null}
+ * @param falseValue the value to return if {@code false}, may be {@code null}
+ * @param nullValue the value to return if {@code null}, may be {@code null}
+ * @return the appropriate value
+ */
+ public static Integer toIntegerObject(final Boolean bool, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
+ if (bool == null) {
+ return nullValue;
+ }
+ return bool.booleanValue() ? trueValue : falseValue;
+ }
+
+ /**
+ * Converts a boolean to a String returning one of the input Strings.
+ *
+ *
+ * BooleanUtils.toString(true, "true", "false") = "true"
+ * BooleanUtils.toString(false, "true", "false") = "false"
*
*
* @param bool the Boolean to check
- * @return {@code 'yes'}, {@code 'no'}, or {@code null}
+ * @param trueString the String to return if {@code true}, may be {@code null}
+ * @param falseString the String to return if {@code false}, may be {@code null}
+ * @return one of the two input Strings
*/
- public static String toStringYesNo(final Boolean bool) {
- return toString(bool, "yes", "no", null);
+ public static String toString(final boolean bool, final String trueString, final String falseString) {
+ return bool ? trueString : falseString;
}
/**
- * Converts a Boolean to a String returning one of the input Strings.
+ * Converts a Boolean to a String returning one of the input Strings.
*
*
* BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
@@ -814,27 +1045,9 @@ public static String toString(final Boolean bool, final String trueString, final
return bool.booleanValue() ? trueString : falseString;
}
- // boolean to String methods
- //-----------------------------------------------------------------------
- /**
- * Converts a boolean to a String returning {@code 'true'}
- * or {@code 'false'}.
- *
- *
- * BooleanUtils.toStringTrueFalse(true) = "true"
- * BooleanUtils.toStringTrueFalse(false) = "false"
- *
- *
- * @param bool the Boolean to check
- * @return {@code 'true'}, {@code 'false'}, or {@code null}
- */
- public static String toStringTrueFalse(final boolean bool) {
- return toString(bool, "true", "false");
- }
-
/**
- * Converts a boolean to a String returning {@code 'on'}
- * or {@code 'off'}.
+ * Converts a boolean to a String returning {@code 'on'}
+ * or {@code 'off'}.
*
*
* BooleanUtils.toStringOnOff(true) = "on"
@@ -845,206 +1058,126 @@ public static String toStringTrueFalse(final boolean bool) {
* @return {@code 'on'}, {@code 'off'}, or {@code null}
*/
public static String toStringOnOff(final boolean bool) {
- return toString(bool, "on", "off");
+ return toString(bool, ON, OFF);
}
/**
- * Converts a boolean to a String returning {@code 'yes'}
- * or {@code 'no'}.
+ * Converts a Boolean to a String returning {@code 'on'},
+ * {@code 'off'}, or {@code null}.
*
*
- * BooleanUtils.toStringYesNo(true) = "yes"
- * BooleanUtils.toStringYesNo(false) = "no"
+ * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
+ * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
+ * BooleanUtils.toStringOnOff(null) = null;
*
*
* @param bool the Boolean to check
- * @return {@code 'yes'}, {@code 'no'}, or {@code null}
+ * @return {@code 'on'}, {@code 'off'}, or {@code null}
*/
- public static String toStringYesNo(final boolean bool) {
- return toString(bool, "yes", "no");
+ public static String toStringOnOff(final Boolean bool) {
+ return toString(bool, ON, OFF, null);
}
/**
- * Converts a boolean to a String returning one of the input Strings.
+ * Converts a boolean to a String returning {@code 'true'}
+ * or {@code 'false'}.
*
*
- * BooleanUtils.toString(true, "true", "false") = "true"
- * BooleanUtils.toString(false, "true", "false") = "false"
+ * BooleanUtils.toStringTrueFalse(true) = "true"
+ * BooleanUtils.toStringTrueFalse(false) = "false"
*
*
* @param bool the Boolean to check
- * @param trueString the String to return if {@code true}, may be {@code null}
- * @param falseString the String to return if {@code false}, may be {@code null}
- * @return one of the two input Strings
+ * @return {@code 'true'}, {@code 'false'}, or {@code null}
*/
- public static String toString(final boolean bool, final String trueString, final String falseString) {
- return bool ? trueString : falseString;
+ public static String toStringTrueFalse(final boolean bool) {
+ return toString(bool, TRUE, FALSE);
}
- // logical operations
- // ----------------------------------------------------------------------
/**
- * Performs an and on a set of booleans.
+ * Converts a Boolean to a String returning {@code 'true'},
+ * {@code 'false'}, or {@code null}.
*
*
- * BooleanUtils.and(true, true) = true
- * BooleanUtils.and(false, false) = false
- * BooleanUtils.and(true, false) = false
- * BooleanUtils.and(true, true, false) = false
- * BooleanUtils.and(true, true, true) = true
+ * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
+ * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
+ * BooleanUtils.toStringTrueFalse(null) = null;
*
*
- * @param array an array of {@code boolean}s
- * @return {@code true} if the and is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
- * @throws IllegalArgumentException if {@code array} is empty.
- * @since 3.0.1
+ * @param bool the Boolean to check
+ * @return {@code 'true'}, {@code 'false'}, or {@code null}
*/
- public static boolean and(final boolean... array) {
- // Validates input
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
- for (final boolean element : array) {
- if (!element) {
- return false;
- }
- }
- return true;
+ public static String toStringTrueFalse(final Boolean bool) {
+ return toString(bool, TRUE, FALSE, null);
}
/**
- * Performs an and on an array of Booleans.
+ * Converts a boolean to a String returning {@code 'yes'}
+ * or {@code 'no'}.
*
*
- * BooleanUtils.and(Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.and(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
- * BooleanUtils.and(Boolean.TRUE, Boolean.FALSE) = Boolean.FALSE
- * BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
- * BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
+ * BooleanUtils.toStringYesNo(true) = "yes"
+ * BooleanUtils.toStringYesNo(false) = "no"
*
*
- * @param array an array of {@code Boolean}s
- * @return {@code true} if the and is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
- * @throws IllegalArgumentException if {@code array} is empty.
- * @throws IllegalArgumentException if {@code array} contains a {@code null}
- * @since 3.0.1
+ * @param bool the Boolean to check
+ * @return {@code 'yes'}, {@code 'no'}, or {@code null}
*/
- public static Boolean and(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
- try {
- final boolean[] primitive = ArrayUtils.toPrimitive(array);
- return and(primitive) ? Boolean.TRUE : Boolean.FALSE;
- } catch (final NullPointerException ex) {
- throw new IllegalArgumentException("The array must not contain any null elements");
- }
+ public static String toStringYesNo(final boolean bool) {
+ return toString(bool, YES, NO);
}
/**
- * Performs an or on a set of booleans.
+ * Converts a Boolean to a String returning {@code 'yes'},
+ * {@code 'no'}, or {@code null}.
*
*
- * BooleanUtils.or(true, true) = true
- * BooleanUtils.or(false, false) = false
- * BooleanUtils.or(true, false) = true
- * BooleanUtils.or(true, true, false) = true
- * BooleanUtils.or(true, true, true) = true
- * BooleanUtils.or(false, false, false) = false
+ * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
+ * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
+ * BooleanUtils.toStringYesNo(null) = null;
*
*
- * @param array an array of {@code boolean}s
- * @return {@code true} if the or is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
- * @throws IllegalArgumentException if {@code array} is empty.
- * @since 3.0.1
+ * @param bool the Boolean to check
+ * @return {@code 'yes'}, {@code 'no'}, or {@code null}
*/
- public static boolean or(final boolean... array) {
- // Validates input
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
- for (final boolean element : array) {
- if (element) {
- return true;
- }
- }
- return false;
+ public static String toStringYesNo(final Boolean bool) {
+ return toString(bool, YES, NO, null);
}
/**
- * Performs an or on an array of Booleans.
+ * Returns an unmodifiable list of Booleans {@code [false, true]}.
*
- *
- * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
- * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE) = Boolean.TRUE
- * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
- * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
- *
- *
- * @param array an array of {@code Boolean}s
- * @return {@code true} if the or is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
- * @throws IllegalArgumentException if {@code array} is empty.
- * @throws IllegalArgumentException if {@code array} contains a {@code null}
- * @since 3.0.1
+ * @return an unmodifiable list of Booleans {@code [false, true]}.
+ * @since 3.13.0
*/
- public static Boolean or(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
- try {
- final boolean[] primitive = ArrayUtils.toPrimitive(array);
- return or(primitive) ? Boolean.TRUE : Boolean.FALSE;
- } catch (final NullPointerException ex) {
- throw new IllegalArgumentException("The array must not contain any null elements");
- }
+ public static List values() {
+ return BOOLEAN_LIST;
}
/**
- * Performs an xor on a set of booleans.
+ * Performs an xor on a set of booleans.
+ *
+ * This behaves like an XOR gate;
+ * it returns true if the number of true values is odd,
+ * and false if the number of true values is zero or even.
+ *
*
*
- * BooleanUtils.xor(true, true) = false
- * BooleanUtils.xor(false, false) = false
- * BooleanUtils.xor(true, false) = true
- * BooleanUtils.xor(true, true) = false
- * BooleanUtils.xor(false, false) = false
- * BooleanUtils.xor(true, false) = true
+ * BooleanUtils.xor(true, true) = false
+ * BooleanUtils.xor(false, false) = false
+ * BooleanUtils.xor(true, false) = true
+ * BooleanUtils.xor(true, false, false) = true
+ * BooleanUtils.xor(true, true, true) = true
+ * BooleanUtils.xor(true, true, true, true) = false
*
*
* @param array an array of {@code boolean}s
- * @return {@code true} if the xor is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @return true if the number of true values in the array is odd; otherwise returns false.
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
*/
public static boolean xor(final boolean... array) {
- // Validates input
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
-
+ ObjectUtils.requireNonEmpty(array, "array");
// false if the neutral element of the xor operator
boolean result = false;
for (final boolean element : array) {
@@ -1055,54 +1188,41 @@ public static boolean xor(final boolean... array) {
}
/**
- * Performs an xor on an array of Booleans.
- *
+ * Performs an xor on an array of Booleans.
*
- * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
- * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
- * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
+ * BooleanUtils.xor(Boolean.TRUE, Boolean.TRUE) = Boolean.FALSE
+ * BooleanUtils.xor(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
+ * BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE) = Boolean.TRUE
+ * BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE, Boolean.FALSE) = Boolean.TRUE
+ * BooleanUtils.xor(Boolean.FALSE, null) = Boolean.FALSE
+ * BooleanUtils.xor(Boolean.TRUE, null) = Boolean.TRUE
*
+ *
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
+ *
*
- * @param array an array of {@code Boolean}s
- * @return {@code true} if the xor is successful.
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @param array an array of {@link Boolean}s
+ * @return the result of the xor operations
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
- * @throws IllegalArgumentException if {@code array} contains a {@code null}
*/
public static Boolean xor(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
- try {
- final boolean[] primitive = ArrayUtils.toPrimitive(array);
- return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
- } catch (final NullPointerException ex) {
- throw new IllegalArgumentException("The array must not contain any null elements");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
+ return xor(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
}
/**
- * Compares two {@code boolean} values. This is the same functionality as provided in Java 7.
+ * {@link BooleanUtils} instances should NOT be constructed in standard programming.
+ * Instead, the class should be used as {@code BooleanUtils.negate(true);}.
*
- * @param x the first {@code boolean} to compare
- * @param y the second {@code boolean} to compare
- * @return the value {@code 0} if {@code x == y};
- * a value less than {@code 0} if {@code !x && y}; and
- * a value greater than {@code 0} if {@code x && !y}
- * @since 3.4
+ * This constructor is public to permit tools that require a JavaBean instance
+ * to operate.
+ *
+ * @deprecated TODO Make private in 4.0.
*/
- public static int compare(boolean x, boolean y) {
- if (x == y) {
- return 0;
- }
- if (x) {
- return 1;
- } else {
- return -1;
- }
+ @Deprecated
+ public BooleanUtils() {
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/CachedRandomBits.java b/src/main/java/org/apache/commons/lang3/CachedRandomBits.java
new file mode 100644
index 00000000000..62904c34627
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/CachedRandomBits.java
@@ -0,0 +1,139 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3;
+
+import java.util.Objects;
+import java.util.Random;
+
+/**
+ * Generates random integers of specific bit length.
+ *
+ *
+ * It is more efficient than calling Random.nextInt(1 << nbBits). It uses a cache of cacheSize random bytes that it replenishes when it gets empty. This is
+ * especially beneficial for SecureRandom Drbg implementations, which incur a constant cost at each randomness generation.
+ *
+ *
+ *
+ * Used internally by RandomStringUtils.
+ *
+ *
+ *
+ * #NotThreadSafe#
+ *
+ */
+final class CachedRandomBits {
+
+ /**
+ * The maximum size of the cache.
+ *
+ *
+ * This is to prevent the possibility of overflow in the {@code if (bitIndex >> 3 >= cache.length)} in the {@link #nextBits(int)} method.
+ *
+ */
+ private static final int MAX_CACHE_SIZE = Integer.MAX_VALUE >> 3;
+
+ /** Maximum number of bits that can be generated (size of an int) */
+ private static final int MAX_BITS = 32;
+
+ /** Mask to extract the bit offset within a byte (0-7) */
+ private static final int BIT_INDEX_MASK = 0x7;
+
+ /** Number of bits in a byte */
+ private static final int BITS_PER_BYTE = 8;
+ private final Random random;
+ private final byte[] cache;
+
+ /**
+ * Index of the next bit in the cache to be used.
+ *
+ *
+ * - bitIndex=0 means the cache is fully random and none of the bits have been used yet.
+ * - bitIndex=1 means that only the LSB of cache[0] has been used and all other bits can be used.
+ * - bitIndex=8 means that only the 8 bits of cache[0] has been used.
+ *
+ */
+ private int bitIndex;
+
+ /**
+ * Creates a new instance.
+ *
+ * @param cacheSize number of bytes cached (only affects performance)
+ * @param random random source
+ */
+ CachedRandomBits(final int cacheSize, final Random random) {
+ if (cacheSize <= 0) {
+ throw new IllegalArgumentException("cacheSize must be positive");
+ }
+ this.cache = cacheSize <= MAX_CACHE_SIZE ? new byte[cacheSize] : new byte[MAX_CACHE_SIZE];
+ this.random = Objects.requireNonNull(random, "random");
+ this.random.nextBytes(this.cache);
+ this.bitIndex = 0;
+ }
+
+ /**
+ * Generates a random integer with the specified number of bits.
+ *
+ * This method efficiently generates random bits by using a byte cache and bit manipulation:
+ *
+ * - Uses a byte array cache to avoid frequent calls to the underlying random number generator
+ * - Extracts bits from each byte using bit shifting and masking
+ * - Handles partial bytes to avoid wasting random bits
+ * - Accumulates bits until the requested number is reached
+ *
+ *
+ *
+ * @param bits number of bits to generate, MUST be between 1 and 32 (inclusive)
+ * @return random integer containing exactly the requested number of random bits
+ * @throws IllegalArgumentException if bits is not between 1 and 32
+ */
+ public int nextBits(final int bits) {
+ if (bits > MAX_BITS || bits <= 0) {
+ throw new IllegalArgumentException("number of bits must be between 1 and " + MAX_BITS);
+ }
+ int result = 0;
+ int generatedBits = 0; // number of generated bits up to now
+ while (generatedBits < bits) {
+ // Check if we need to refill the cache
+ // Convert bitIndex to byte index by dividing by 8 (right shift by 3)
+ if (bitIndex >> 3 >= cache.length) {
+ // We exhausted the number of bits in the cache
+ // This should only happen if the bitIndex is exactly matching the cache length
+ assert bitIndex == cache.length * BITS_PER_BYTE;
+ random.nextBytes(cache);
+ bitIndex = 0;
+ }
+ // Calculate how many bits we can extract from the current byte
+ // 1. Get current position within byte (0-7) using bitIndex & 0x7
+ // 2. Calculate remaining bits in byte: 8 - (position within byte)
+ // 3. Take minimum of remaining bits in byte and bits still needed
+ final int generatedBitsInIteration = Math.min(
+ BITS_PER_BYTE - (bitIndex & BIT_INDEX_MASK),
+ bits - generatedBits);
+ // Shift existing result left to make room for new bits
+ result = result << generatedBitsInIteration;
+ // Extract and append new bits:
+ // 1. Get byte from cache (bitIndex >> 3 converts bit index to byte index)
+ // 2. Shift right by bit position within byte (bitIndex & 0x7)
+ // 3. Mask to keep only the bits we want ((1 << generatedBitsInIteration) - 1)
+ result |= cache[bitIndex >> 3] >> (bitIndex & BIT_INDEX_MASK) & ((1 << generatedBitsInIteration) - 1);
+ // Update counters
+ generatedBits += generatedBitsInIteration;
+ bitIndex += generatedBitsInIteration;
+ }
+ return result;
+ }
+}
diff --git a/src/main/java/org/apache/commons/lang3/CharEncoding.java b/src/main/java/org/apache/commons/lang3/CharEncoding.java
index ea682847c90..072e94fec90 100644
--- a/src/main/java/org/apache/commons/lang3/CharEncoding.java
+++ b/src/main/java/org/apache/commons/lang3/CharEncoding.java
@@ -6,7 +6,7 @@
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@@ -19,77 +19,84 @@
import java.nio.charset.Charset;
import java.nio.charset.IllegalCharsetNameException;
+import java.nio.charset.StandardCharsets;
/**
- * Character encoding names required of every implementation of the Java platform.
+ * Character encoding names required of every implementation of the Java platform.
*
- * According to JRE character
+ * According to JRE character
* encoding names:
*
* Every implementation of the Java platform is required to support the following character encodings.
* Consult the release documentation for your implementation to see if any other encodings are supported.
*
*
- * @see JRE character encoding names
+ * @see JRE character encoding names
* @since 2.1
+ * @deprecated Java 7 introduced {@link java.nio.charset.StandardCharsets}, which defines these constants as
+ * {@link Charset} objects. Use {@link Charset#name()} to get the string values provided in this class.
+ * This class will be removed in a future release.
*/
+@Deprecated
public class CharEncoding {
/**
- *
ISO Latin Alphabet #1, also known as ISO-LATIN-1.
+ * ISO Latin Alphabet #1, also known as ISO-LATIN-1.
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String ISO_8859_1 = "ISO-8859-1";
+ public static final String ISO_8859_1 = StandardCharsets.ISO_8859_1.name();
/**
- * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block
- * of the Unicode character set.
+ * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block
+ * of the Unicode character set.
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String US_ASCII = "US-ASCII";
+ public static final String US_ASCII = StandardCharsets.US_ASCII.name();
/**
- * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial
- * byte-order mark (either order accepted on input, big-endian used on output).
+ * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial
+ * byte-order mark (either order accepted on input, big-endian used on output).
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String UTF_16 = "UTF-16";
+ public static final String UTF_16 = StandardCharsets.UTF_16.name();
/**
- * Sixteen-bit Unicode Transformation Format, big-endian byte order.
+ * Sixteen-bit Unicode Transformation Format, big-endian byte order.
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String UTF_16BE = "UTF-16BE";
+ public static final String UTF_16BE = StandardCharsets.UTF_16BE.name();
/**
- * Sixteen-bit Unicode Transformation Format, little-endian byte order.
+ * Sixteen-bit Unicode Transformation Format, little-endian byte order.
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String UTF_16LE = "UTF-16LE";
+ public static final String UTF_16LE = StandardCharsets.UTF_16LE.name();
/**
- * Eight-bit Unicode Transformation Format.
+ * Eight-bit Unicode Transformation Format.
*
* Every implementation of the Java platform is required to support this character encoding.
*/
- public static final String UTF_8 = "UTF-8";
+ public static final String UTF_8 = StandardCharsets.UTF_8.name();
- //-----------------------------------------------------------------------
/**
- * Returns whether the named charset is supported.
+ * Tests whether the named charset is supported.
*
* This is similar to
+ * href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html#isSupported%28java.lang.String%29">
* java.nio.charset.Charset.isSupported(String) but handles more formats
*
* @param name the name of the requested charset; may be either a canonical name or an alias, null returns false
* @return {@code true} if the charset is available in the current Java virtual machine
+ * @deprecated Please use {@link Charset#isSupported(String)} instead, although be aware that {@code null}
+ * values are not accepted by that method and an {@link IllegalCharsetNameException} may be thrown.
*/
+ @Deprecated
public static boolean isSupported(final String name) {
if (name == null) {
return false;
@@ -101,4 +108,13 @@ public static boolean isSupported(final String name) {
}
}
+ /**
+ * Constructs a new instance.
+ *
+ * @deprecated Will be removed in 4.0.0.
+ */
+ @Deprecated
+ public CharEncoding() {
+ // empty
+ }
}
diff --git a/src/main/java/org/apache/commons/lang3/CharRange.java b/src/main/java/org/apache/commons/lang3/CharRange.java
index 2ccda7c4eac..e38efeb3246 100644
--- a/src/main/java/org/apache/commons/lang3/CharRange.java
+++ b/src/main/java/org/apache/commons/lang3/CharRange.java
@@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -19,69 +19,135 @@
import java.io.Serializable;
import java.util.Iterator;
import java.util.NoSuchElementException;
+import java.util.Objects;
/**
- * A contiguous range of characters, optionally negated.
- *
+ * A contiguous range of characters, optionally negated.
+ *
* Instances are immutable.
*
* #ThreadSafe#
+ *
* @since 1.0
+ * @since 3.21.0 {@code serialVersionUID} changed from {@code 8270183163158333422L} to {@code 2L}.
*/
-// TODO: This is no longer public and will be removed later as CharSet is moved
+// TODO: This is no longer public and will be removed later as CharSet is moved
// to depend on Range.
final class CharRange implements Iterable, Serializable {
/**
- * Required for serialization support. Lang version 2.0.
- *
- * @see java.io.Serializable
+ * Character {@link Iterator}.
+ * #NotThreadSafe#
*/
- private static final long serialVersionUID = 8270183163158333422L;
-
- /** The first character, inclusive, in the range. */
- private final char start;
- /** The last character, inclusive, in the range. */
- private final char end;
- /** True if the range is everything except the characters specified. */
- private final boolean negated;
-
- /** Cached toString. */
- private transient String iToString;
+ private static final class CharacterIterator implements Iterator {
+
+ /** The current character */
+ private char current;
+
+ private final CharRange range;
+ private boolean hasNext;
+
+ /**
+ * Constructs a new iterator for the character range.
+ *
+ * @param r The character range.
+ */
+ private CharacterIterator(final CharRange r) {
+ range = r;
+ hasNext = true;
+
+ if (range.negated) {
+ if (range.start == 0) {
+ if (range.end == Character.MAX_VALUE) {
+ // This range is an empty set
+ hasNext = false;
+ } else {
+ current = (char) (range.end + 1);
+ }
+ } else {
+ current = 0;
+ }
+ } else {
+ current = range.start;
+ }
+ }
+
+ /**
+ * Tests whether this iterator reached the end character.
+ *
+ * @return {@code true} if the iterator has yet to reach the character date.
+ */
+ @Override
+ public boolean hasNext() {
+ return hasNext;
+ }
+
+ /**
+ * Returns the next character in the iteration.
+ *
+ * @return {@link Character} for the next character.
+ */
+ @Override
+ public Character next() {
+ if (!hasNext) {
+ throw new NoSuchElementException();
+ }
+ final char cur = current;
+ prepareNext();
+ return Character.valueOf(cur);
+ }
+
+ /**
+ * Prepares the next character in the range.
+ */
+ private void prepareNext() {
+ if (range.negated) {
+ if (current == Character.MAX_VALUE) {
+ hasNext = false;
+ } else if (current + 1 == range.start) {
+ if (range.end == Character.MAX_VALUE) {
+ hasNext = false;
+ } else {
+ current = (char) (range.end + 1);
+ }
+ } else {
+ current = (char) (current + 1);
+ }
+ } else if (current < range.end) {
+ current = (char) (current + 1);
+ } else {
+ hasNext = false;
+ }
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException Always thrown.
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
/**
- * Constructs a {@code CharRange} over a set of characters,
- * optionally negating the range.
- *
- * A negated range includes everything except that defined by the
- * start and end characters.
- *
- * If start and end are in the wrong order, they are reversed.
- * Thus {@code a-e} is the same as {@code e-a}.
+ * Required for serialization support. Lang version 2.0.
*
- * @param start first character, inclusive, in this range
- * @param end last character, inclusive, in this range
- * @param negated true to express everything except the range
+ * @see java.io.Serializable
+ * @since 3.21.0 {@code serialVersionUID} changed from {@code 8270183163158333422L} to {@value}.
*/
- private CharRange(char start, char end, final boolean negated) {
- super();
- if (start > end) {
- final char temp = start;
- start = end;
- end = temp;
- }
-
- this.start = start;
- this.end = end;
- this.negated = negated;
- }
+ private static final long serialVersionUID = 2L;
+
+ /** Empty array. */
+ static final CharRange[] EMPTY_ARRAY = {};
/**
- * Constructs a {@code CharRange} over a single character.
+ * Constructs a {@link CharRange} over a single character.
*
- * @param ch only character in this range
- * @return the new CharRange object
- * @see CharRange#CharRange(char, char, boolean)
+ * @param ch only character in this range.
+ * @return the new CharRange object.
* @since 2.5
*/
public static CharRange is(final char ch) {
@@ -89,99 +155,110 @@ public static CharRange is(final char ch) {
}
/**
- * Constructs a negated {@code CharRange} over a single character.
+ * Constructs a {@link CharRange} over a set of characters.
*
- * @param ch only character in this range
- * @return the new CharRange object
- * @see CharRange#CharRange(char, char, boolean)
+ * If start and end are in the wrong order, they are reversed.
+ * Thus {@code a-e} is the same as {@code e-a}.
+ *
+ * @param start first character, inclusive, in this range.
+ * @param end last character, inclusive, in this range.
+ * @return the new CharRange object.
* @since 2.5
*/
- public static CharRange isNot(final char ch) {
- return new CharRange(ch, ch, true);
+ public static CharRange isIn(final char start, final char end) {
+ return new CharRange(start, end, false);
}
/**
- * Constructs a {@code CharRange} over a set of characters.
+ * Constructs a negated {@link CharRange} over a single character.
*
- * @param start first character, inclusive, in this range
- * @param end last character, inclusive, in this range
- * @return the new CharRange object
- * @see CharRange#CharRange(char, char, boolean)
+ * A negated range includes everything except that defined by the
+ * single character.
+ *
+ * @param ch only character in this range.
+ * @return the new CharRange object.
* @since 2.5
*/
- public static CharRange isIn(final char start, final char end) {
- return new CharRange(start, end, false);
+ public static CharRange isNot(final char ch) {
+ return new CharRange(ch, ch, true);
}
/**
- * Constructs a negated {@code CharRange} over a set of characters.
+ * Constructs a negated {@link CharRange} over a set of characters.
+ *
+ * A negated range includes everything except that defined by the
+ * start and end characters.
+ *
+ * If start and end are in the wrong order, they are reversed.
+ * Thus {@code a-e} is the same as {@code e-a}.
*
- * @param start first character, inclusive, in this range
- * @param end last character, inclusive, in this range
- * @return the new CharRange object
- * @see CharRange#CharRange(char, char, boolean)
+ * @param start first character, inclusive, in this range.
+ * @param end last character, inclusive, in this range.
+ * @return the new CharRange object.
* @since 2.5
*/
public static CharRange isNotIn(final char start, final char end) {
return new CharRange(start, end, true);
}
- // Accessors
- //-----------------------------------------------------------------------
- /**
- * Gets the start character for this character range.
- *
- * @return the start char (inclusive)
- */
- public char getStart() {
- return this.start;
- }
+ /** The first character, inclusive, in the range. */
+ private final char start;
- /**
- * Gets the end character for this character range.
- *
- * @return the end char (inclusive)
- */
- public char getEnd() {
- return this.end;
- }
+ /** The last character, inclusive, in the range. */
+ private final char end;
+
+ /** True if the range is everything except the characters specified. */
+ private final boolean negated;
+
+ /** Cached toString. */
+ private transient String iToString;
/**
- * Is this {@code CharRange} negated.
- *
+ * Constructs a {@link CharRange} over a set of characters,
+ * optionally negating the range.
+ *
* A negated range includes everything except that defined by the
* start and end characters.
*
- * @return {@code true} if negated
+ * If start and end are in the wrong order, they are reversed.
+ * Thus {@code a-e} is the same as {@code e-a}.
+ *
+ * @param start first character, inclusive, in this range.
+ * @param end last character, inclusive, in this range.
+ * @param negated true to express everything except the range.
*/
- public boolean isNegated() {
- return negated;
+ private CharRange(char start, char end, final boolean negated) {
+ if (start > end) {
+ final char temp = start;
+ start = end;
+ end = temp;
+ }
+
+ this.start = start;
+ this.end = end;
+ this.negated = negated;
}
- // Contains
- //-----------------------------------------------------------------------
/**
- * Is the character specified contained in this range.
+ * Is the character specified contained in this range.
*
- * @param ch the character to check
- * @return {@code true} if this range contains the input character
+ * @param ch the character to check.
+ * @return {@code true} if this range contains the input character.
*/
public boolean contains(final char ch) {
return (ch >= start && ch <= end) != negated;
}
/**
- * Are all the characters of the passed in range contained in
- * this range.
+ * Are all the characters of the passed in range contained in
+ * this range.
*
- * @param range the range to check against
- * @return {@code true} if this range entirely contains the input range
- * @throws IllegalArgumentException if {@code null} input
+ * @param range the range to check against.
+ * @return {@code true} if this range entirely contains the input range.
+ * @throws NullPointerException if {@code null} input.
*/
public boolean contains(final CharRange range) {
- if (range == null) {
- throw new IllegalArgumentException("The Range must not be null");
- }
+ Objects.requireNonNull(range, "range");
if (negated) {
if (range.negated) {
return start >= range.start && end <= range.end;
@@ -194,21 +271,19 @@ public boolean contains(final CharRange range) {
return start <= range.start && end >= range.end;
}
- // Basics
- //-----------------------------------------------------------------------
/**
- * Compares two CharRange objects, returning true if they represent
- * exactly the same range of characters defined in the same way.
- *
- * @param obj the object to compare to
- * @return true if equal
+ * Compares two CharRange objects, returning true if they represent
+ * exactly the same range of characters defined in the same way.
+ *
+ * @param obj the object to compare to.
+ * @return true if equal.
*/
@Override
public boolean equals(final Object obj) {
if (obj == this) {
return true;
}
- if (obj instanceof CharRange == false) {
+ if (!(obj instanceof CharRange)) {
return false;
}
final CharRange other = (CharRange) obj;
@@ -216,43 +291,50 @@ public boolean equals(final Object obj) {
}
/**
- * Gets a hashCode compatible with the equals method.
- *
- * @return a suitable hashCode
+ * Gets the end character for this character range.
+ *
+ * @return the end char (inclusive).
+ */
+ public char getEnd() {
+ return this.end;
+ }
+
+ /**
+ * Gets the start character for this character range.
+ *
+ * @return the start char (inclusive).
+ */
+ public char getStart() {
+ return this.start;
+ }
+
+ /**
+ * Gets a hashCode compatible with the equals method.
+ *
+ * @return a suitable hashCode.
*/
@Override
public int hashCode() {
- return 83 + start + 7 * end + (negated ? 1 : 0);
+ return Objects.hash(end, negated, start);
}
-
+
/**
- * Gets a string representation of the character range.
- *
- * @return string representation of this range
+ * Is this {@link CharRange} negated.
+ *
+ * A negated range includes everything except that defined by the
+ * start and end characters.
+ *
+ * @return {@code true} if negated.
*/
- @Override
- public String toString() {
- if (iToString == null) {
- final StringBuilder buf = new StringBuilder(4);
- if (isNegated()) {
- buf.append('^');
- }
- buf.append(start);
- if (start != end) {
- buf.append('-');
- buf.append(end);
- }
- iToString = buf.toString();
- }
- return iToString;
+ public boolean isNegated() {
+ return negated;
}
- // Expansions
- //-----------------------------------------------------------------------
/**
- * Returns an iterator which can be used to walk through the characters described by this range.
+ * Returns an iterator which can be used to walk through the characters described by this range.
*
* #NotThreadSafe# the iterator is not thread-safe
+ *
* @return an iterator to the chars represented by this range
* @since 2.5
*/
@@ -262,98 +344,24 @@ public Iterator iterator() {
}
/**
- * Character {@link Iterator}.
- * #NotThreadSafe#
+ * Gets a string representation of the character range.
+ *
+ * @return string representation of this range.
*/
- private static class CharacterIterator implements Iterator {
- /** The current character */
- private char current;
-
- private final CharRange range;
- private boolean hasNext;
-
- /**
- * Construct a new iterator for the character range.
- *
- * @param r The character range
- */
- private CharacterIterator(final CharRange r) {
- range = r;
- hasNext = true;
-
- if (range.negated) {
- if (range.start == 0) {
- if (range.end == Character.MAX_VALUE) {
- // This range is an empty set
- hasNext = false;
- } else {
- current = (char) (range.end + 1);
- }
- } else {
- current = 0;
- }
- } else {
- current = range.start;
- }
- }
-
- /**
- * Prepare the next character in the range.
- */
- private void prepareNext() {
- if (range.negated) {
- if (current == Character.MAX_VALUE) {
- hasNext = false;
- } else if (current + 1 == range.start) {
- if (range.end == Character.MAX_VALUE) {
- hasNext = false;
- } else {
- current = (char) (range.end + 1);
- }
- } else {
- current = (char) (current + 1);
- }
- } else if (current < range.end) {
- current = (char) (current + 1);
- } else {
- hasNext = false;
+ @Override
+ public String toString() {
+ if (iToString == null) {
+ final StringBuilder buf = new StringBuilder(4);
+ if (isNegated()) {
+ buf.append('^');
}
- }
-
- /**
- * Has the iterator not reached the end character yet?
- *
- * @return {@code true} if the iterator has yet to reach the character date
- */
- @Override
- public boolean hasNext() {
- return hasNext;
- }
-
- /**
- * Return the next character in the iteration
- *
- * @return {@code Character} for the next character
- */
- @Override
- public Character next() {
- if (hasNext == false) {
- throw new NoSuchElementException();
+ buf.append(start);
+ if (start != end) {
+ buf.append('-');
+ buf.append(end);
}
- final char cur = current;
- prepareNext();
- return Character.valueOf(cur);
- }
-
- /**
- * Always throws UnsupportedOperationException.
- *
- * @throws UnsupportedOperationException
- * @see java.util.Iterator#remove()
- */
- @Override
- public void remove() {
- throw new UnsupportedOperationException();
+ iToString = buf.toString();
}
+ return iToString;
}
}
diff --git a/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java b/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
index a5112d9d017..9fc1fd84afd 100644
--- a/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharSequenceUtils.java
@@ -6,7 +6,7 @@
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@@ -17,8 +17,8 @@
package org.apache.commons.lang3;
/**
- * Operations on {@link CharSequence} that are
- * {@code null} safe.
+ * Operations on {@link CharSequence} that are
+ * {@code null} safe.
*
* @see CharSequence
* @since 3.0
@@ -27,71 +27,38 @@ public class CharSequenceUtils {
private static final int NOT_FOUND = -1;
- /**
- * {@code CharSequenceUtils} instances should NOT be constructed in
- * standard programming.
- *
- * This constructor is public to permit tools that require a JavaBean
- * instance to operate.
- */
- public CharSequenceUtils() {
- super();
- }
-
- //-----------------------------------------------------------------------
- /**
- * Returns a new {@code CharSequence} that is a subsequence of this
- * sequence starting with the {@code char} value at the specified index.
- *
- * This provides the {@code CharSequence} equivalent to {@link String#substring(int)}.
- * The length (in {@code char}) of the returned sequence is {@code length() - start},
- * so if {@code start == end} then an empty sequence is returned.
- *
- * @param cs the specified subsequence, null returns null
- * @param start the start index, inclusive, valid
- * @return a new subsequence, may be null
- * @throws IndexOutOfBoundsException if {@code start} is negative or if
- * {@code start} is greater than {@code length()}
- */
- public static CharSequence subSequence(final CharSequence cs, final int start) {
- return cs == null ? null : cs.subSequence(start, cs.length());
- }
+ static final int TO_STRING_LIMIT = 16;
- //-----------------------------------------------------------------------
- /**
- * Finds the first index in the {@code CharSequence} that matches the
- * specified character.
- *
- * @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
- */
- static int indexOf(final CharSequence cs, final int searchChar, int start) {
- if (cs instanceof String) {
- return ((String) cs).indexOf(searchChar, start);
- }
- final int sz = cs.length();
- if (start < 0) {
- start = 0;
- }
- for (int i = start; i < sz; i++) {
- if (cs.charAt(i) == searchChar) {
- return i;
+ private static boolean checkLaterThan1(final CharSequence cs, final CharSequence searchChar, final int len2, final int start1) {
+ for (int i = 1, j = len2 - 1; i <= j; i++, j--) {
+ if (cs.charAt(start1 + i) != searchChar.charAt(i) || cs.charAt(start1 + j) != searchChar.charAt(j)) {
+ return false;
}
}
- return NOT_FOUND;
+ return true;
}
/**
* Used by the indexOf(CharSequence methods) as a green implementation of indexOf.
*
- * @param cs the {@code CharSequence} to be processed
- * @param searchChar the {@code CharSequence} to be searched for
- * @param start the start index
- * @return the index where the search sequence was found
+ * @param cs the {@link CharSequence} to be processed.
+ * @param searchChar the {@link CharSequence} to be searched for.
+ * @param start the start index.
+ * @return the index where the search sequence was found, or {@code -1} if there is no such occurrence.
*/
static int indexOf(final CharSequence cs, final CharSequence searchChar, final int start) {
+ if (cs == null || searchChar == null) {
+ return StringUtils.INDEX_NOT_FOUND;
+ }
+ if (cs instanceof String) {
+ return ((String) cs).indexOf(searchChar.toString(), start);
+ }
+ if (cs instanceof StringBuilder) {
+ return ((StringBuilder) cs).indexOf(searchChar.toString(), start);
+ }
+ if (cs instanceof StringBuffer) {
+ return ((StringBuffer) cs).indexOf(searchChar.toString(), start);
+ }
return cs.toString().indexOf(searchChar.toString(), start);
// if (cs instanceof String && searchChar instanceof String) {
// // TODO: Do we assume searchChar is usually relatively small;
@@ -105,28 +72,66 @@ static int indexOf(final CharSequence cs, final CharSequence searchChar, final i
}
/**
- * Finds the last index in the {@code CharSequence} that matches the
- * specified character.
+ * Returns the index within {@code cs} of the first occurrence of the specified character, starting the search at the specified index.
+ *
+ * If a character with value {@code searchChar} occurs in the character sequence represented by the {@code cs} object at an index no smaller than
+ * {@code start}, then the index of the first such occurrence is returned. For values of {@code searchChar} in the range from 0 to 0xFFFF (inclusive), this
+ * is the smallest value k such that:
+ *
+ *
+ *
+ * (this.charAt(k) == searchChar) && (k >= start)
+ *
+ *
+ * is true. For other values of {@code searchChar}, it is the smallest value k such that:
+ *
*
- * @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
+ *
+ * (this.codePointAt(k) == searchChar) && (k >= start)
+ *
+ *
+ * is true. In either case, if no such character occurs inm {@code cs} at or after position {@code start}, then {@code -1} is returned.
+ *
+ *
+ * There is no restriction on the value of {@code start}. If it is negative, it has the same effect as if it were zero: the entire {@link CharSequence} may
+ * be searched. If it is greater than the length of {@code cs}, it has the same effect as if it were equal to the length of {@code cs}: {@code -1} is
+ * returned.
+ *
+ *
+ * All indices are specified in {@code char} values (Unicode code units).
+ *
+ *
+ * @param cs the {@link 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 {@link String}.
*/
- static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
+ static int indexOf(final CharSequence cs, final int searchChar, int start) {
if (cs instanceof String) {
- return ((String) cs).lastIndexOf(searchChar, start);
+ return ((String) cs).indexOf(searchChar, start);
}
final int sz = cs.length();
if (start < 0) {
- return NOT_FOUND;
+ start = 0;
}
- if (start >= sz) {
- start = sz - 1;
+ if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
+ for (int i = start; i < sz; i++) {
+ if (cs.charAt(i) == searchChar) {
+ return i;
+ }
+ }
+ return NOT_FOUND;
}
- for (int i = start; i >= 0; --i) {
- if (cs.charAt(i) == searchChar) {
- return i;
+ //supplementary characters (LANG1300)
+ if (searchChar <= Character.MAX_CODE_POINT) {
+ final char[] chars = Character.toChars(searchChar);
+ for (int i = start; i < sz - 1; i++) {
+ final char high = cs.charAt(i);
+ final char low = cs.charAt(i + 1);
+ if (high == chars[0] && low == chars[1]) {
+ return i;
+ }
}
}
return NOT_FOUND;
@@ -135,95 +140,256 @@ static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
/**
* Used by the lastIndexOf(CharSequence methods) as a green implementation of lastIndexOf
*
- * @param cs the {@code CharSequence} to be processed
- * @param searchChar the {@code CharSequence} to be searched for
- * @param start the start index
- * @return the index where the search sequence was found
+ * @param cs the {@link CharSequence} to be processed.
+ * @param searchChar the {@link CharSequence} to find.
+ * @param start the start index.
+ * @return the index where the search sequence was found.
*/
- static int lastIndexOf(final CharSequence cs, final CharSequence searchChar, final int start) {
- return cs.toString().lastIndexOf(searchChar.toString(), start);
-// if (cs instanceof String && searchChar instanceof String) {
-// // TODO: Do we assume searchChar is usually relatively small;
-// // If so then calling toString() on it is better than reverting to
-// // the green implementation in the else block
-// return ((String) cs).lastIndexOf((String) searchChar, start);
-// } else {
-// // TODO: Implement rather than convert to String
-// return cs.toString().lastIndexOf(searchChar.toString(), start);
-// }
+ static int lastIndexOf(final CharSequence cs, final CharSequence searchChar, int start) {
+ if (searchChar == null || cs == null) {
+ return NOT_FOUND;
+ }
+ if (searchChar instanceof String) {
+ if (cs instanceof String) {
+ return ((String) cs).lastIndexOf((String) searchChar, start);
+ }
+ if (cs instanceof StringBuilder) {
+ return ((StringBuilder) cs).lastIndexOf((String) searchChar, start);
+ }
+ if (cs instanceof StringBuffer) {
+ return ((StringBuffer) cs).lastIndexOf((String) searchChar, start);
+ }
+ }
+
+ final int len1 = cs.length();
+ final int len2 = searchChar.length();
+
+ if (start > len1) {
+ start = len1;
+ }
+
+ if (start < 0 || len2 > len1) {
+ return NOT_FOUND;
+ }
+
+ if (len2 == 0) {
+ return start;
+ }
+
+ if (len2 <= TO_STRING_LIMIT) {
+ if (cs instanceof String) {
+ return ((String) cs).lastIndexOf(searchChar.toString(), start);
+ }
+ if (cs instanceof StringBuilder) {
+ return ((StringBuilder) cs).lastIndexOf(searchChar.toString(), start);
+ }
+ if (cs instanceof StringBuffer) {
+ return ((StringBuffer) cs).lastIndexOf(searchChar.toString(), start);
+ }
+ }
+
+ if (start + len2 > len1) {
+ start = len1 - len2;
+ }
+
+ final char char0 = searchChar.charAt(0);
+
+ int i = start;
+ while (true) {
+ while (cs.charAt(i) != char0) {
+ i--;
+ if (i < 0) {
+ return NOT_FOUND;
+ }
+ }
+ if (checkLaterThan1(cs, searchChar, len2, i)) {
+ return i;
+ }
+ i--;
+ if (i < 0) {
+ return NOT_FOUND;
+ }
+ }
}
/**
- * Green implementation of toCharArray.
+ * Returns the index within {@code cs} of the last occurrence of the specified character, searching backward starting at the specified index. For values of
+ * {@code searchChar} in the range from 0 to 0xFFFF (inclusive), the index returned is the largest value k such that:
+ *
+ *
+ * (this.charAt(k) == searchChar) && (k <= start)
+ *
+ *
+ * is true. For other values of {@code searchChar}, it is the largest value k such that:
+ *
*
- * @param cs the {@code CharSequence} to be processed
- * @return the resulting char array
+ *
+ * (this.codePointAt(k) == searchChar) && (k <= start)
+ *
+ *
+ * is true. In either case, if no such character occurs in {@code cs} at or before position {@code start}, then {@code -1} is returned.
+ *
+ *
+ * All indices are specified in {@code char} values (Unicode code units).
+ *
+ *
+ * @param cs the {@link 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 {@link String}.
*/
- static char[] toCharArray(final CharSequence cs) {
+ static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
if (cs instanceof String) {
- return ((String) cs).toCharArray();
+ return ((String) cs).lastIndexOf(searchChar, start);
}
final int sz = cs.length();
- final char[] array = new char[cs.length()];
- for (int i = 0; i < sz; i++) {
- array[i] = cs.charAt(i);
+ if (start < 0) {
+ return NOT_FOUND;
}
- return array;
+ if (start >= sz) {
+ start = sz - 1;
+ }
+ if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
+ for (int i = start; i >= 0; --i) {
+ if (cs.charAt(i) == searchChar) {
+ return i;
+ }
+ }
+ return NOT_FOUND;
+ }
+ //supplementary characters (LANG1300)
+ //NOTE - we must do a forward traversal for this to avoid duplicating code points
+ if (searchChar <= Character.MAX_CODE_POINT) {
+ final char[] chars = Character.toChars(searchChar);
+ //make sure it's not the last index
+ if (start == sz - 1) {
+ return NOT_FOUND;
+ }
+ for (int i = start; i >= 0; i--) {
+ final char high = cs.charAt(i);
+ final char low = cs.charAt(i + 1);
+ if (chars[0] == high && chars[1] == low) {
+ return i;
+ }
+ }
+ }
+ return NOT_FOUND;
}
/**
- * Green implementation of regionMatches.
+ * Tests if two string regions are equal.
*
- * @param cs the {@code CharSequence} to be processed
- * @param ignoreCase whether or not to be case insensitive
- * @param thisStart the index to start on the {@code cs} CharSequence
- * @param substring the {@code CharSequence} to be looked for
- * @param start the index to start on the {@code substring} CharSequence
- * @param length character length of the region
- * @return whether the region matched
+ * @param cs the {@link CharSequence} to be processed.
+ * @param ignoreCase whether or not to be case-insensitive.
+ * @param thisStart the index to start on the {@code cs} CharSequence.
+ * @param substring the {@link CharSequence} to be looked for.
+ * @param start the index to start on the {@code substring} CharSequence.
+ * @param length character length of the region.
+ * @return whether the region matched.
+ * @see String#regionMatches(boolean, int, String, int, int)
*/
- static boolean regionMatches(final CharSequence cs, final boolean ignoreCase, final int thisStart,
- final CharSequence substring, final int start, final int length) {
+ static boolean regionMatches(final CharSequence cs, final boolean ignoreCase, final int thisStart, final CharSequence substring, final int start,
+ final int length) {
+ // Green implementation of regionMatches.
if (cs instanceof String && substring instanceof String) {
return ((String) cs).regionMatches(ignoreCase, thisStart, (String) substring, start, length);
}
int index1 = thisStart;
int index2 = start;
int tmpLen = length;
-
// Extract these first so we detect NPEs the same as the java.lang.String version
final int srcLen = cs.length() - thisStart;
final int otherLen = substring.length() - start;
-
// Check for invalid parameters
if (thisStart < 0 || start < 0 || length < 0) {
return false;
}
-
// Check that the regions are long enough
if (srcLen < length || otherLen < length) {
return false;
}
-
while (tmpLen-- > 0) {
final char c1 = cs.charAt(index1++);
final char c2 = substring.charAt(index2++);
-
if (c1 == c2) {
continue;
}
-
if (!ignoreCase) {
return false;
}
-
- // The same check as in String.regionMatches():
- if (Character.toUpperCase(c1) != Character.toUpperCase(c2)
- && Character.toLowerCase(c1) != Character.toLowerCase(c2)) {
+ // The real same check as in String#regionMatches(boolean, int, String, int, int):
+ final char u1 = Character.toUpperCase(c1);
+ final char u2 = Character.toUpperCase(c2);
+ if (u1 != u2 && Character.toLowerCase(u1) != Character.toLowerCase(u2)) {
return false;
}
}
-
return true;
}
+
+ /**
+ * Returns a new {@link CharSequence} that is a subsequence of this
+ * sequence starting with the {@code char} value at the specified index.
+ *
+ * This provides the {@link CharSequence} equivalent to {@link String#substring(int)}.
+ * The length (in {@code char}) of the returned sequence is {@code length() - start},
+ * so if {@code start == end} then an empty sequence is returned.
+ *
+ * @param cs the specified subsequence, null returns null.
+ * @param start the start index, inclusive, valid.
+ * @return a new subsequence, may be null.
+ * @throws IndexOutOfBoundsException if {@code start} is negative or if
+ * {@code start} is greater than {@code length()}.
+ */
+ public static CharSequence subSequence(final CharSequence cs, final int start) {
+ return cs == null ? null : cs.subSequence(start, cs.length());
+ }
+
+ /**
+ * Converts the given CharSequence to a char[].
+ *
+ * @param source the {@link CharSequence} to be processed.
+ * @return the resulting char array, never null.
+ * @since 3.11
+ */
+ public static char[] toCharArray(final CharSequence source) {
+ // See CharSequenceUtilsBenchmark
+ final int len = StringUtils.length(source);
+ if (len == 0) {
+ return ArrayUtils.EMPTY_CHAR_ARRAY;
+ }
+ if (source instanceof String) {
+ return ((String) source).toCharArray();
+ }
+ if (source instanceof StringBuilder) {
+ final char[] array = new char[len];
+ ((StringBuilder) source).getChars(0, len, array, 0);
+ return array;
+ }
+ if (source instanceof StringBuffer) {
+ final char[] array = new char[len];
+ ((StringBuffer) source).getChars(0, len, array, 0);
+ return array;
+ }
+ final char[] array = new char[len];
+ for (int i = 0; i < len; i++) {
+ array[i] = source.charAt(i);
+ }
+ return array;
+ }
+
+ /**
+ * {@link CharSequenceUtils} instances should NOT be constructed in
+ * standard programming.
+ *
+ * This constructor is public to permit tools that require a JavaBean
+ * instance to operate.
+ *
+ * @deprecated TODO Make private in 4.0.
+ */
+ @Deprecated
+ public CharSequenceUtils() {
+ // empty
+ }
}
diff --git a/src/main/java/org/apache/commons/lang3/CharSet.java b/src/main/java/org/apache/commons/lang3/CharSet.java
index 2cd4c7bdeb4..bdbffc4c48f 100644
--- a/src/main/java/org/apache/commons/lang3/CharSet.java
+++ b/src/main/java/org/apache/commons/lang3/CharSet.java
@@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -19,67 +19,77 @@
import java.io.Serializable;
import java.util.Collections;
import java.util.HashMap;
-import java.util.HashSet;
+import java.util.LinkedHashSet;
import java.util.Map;
import java.util.Set;
+import java.util.stream.Stream;
/**
- * A set of characters.
+ * A set of characters.
*
* Instances are immutable, but instances of subclasses may not be.
*
* #ThreadSafe#
+ *
* @since 1.0
*/
public class CharSet implements Serializable {
/**
- * Required for serialization support. Lang version 2.0.
- *
+ * Required for serialization support. Lang version 2.0.
+ *
* @see java.io.Serializable
*/
private static final long serialVersionUID = 5947847346149275958L;
- /**
- * A CharSet defining no characters.
+ /**
+ * A CharSet defining no characters.
+ *
* @since 2.0
*/
public static final CharSet EMPTY = new CharSet((String) null);
- /**
+ /**
* A CharSet defining ASCII alphabetic characters "a-zA-Z".
+ *
* @since 2.0
*/
public static final CharSet ASCII_ALPHA = new CharSet("a-zA-Z");
- /**
+ /**
* A CharSet defining ASCII alphabetic characters "a-z".
+ *
* @since 2.0
*/
public static final CharSet ASCII_ALPHA_LOWER = new CharSet("a-z");
- /**
+ /**
* A CharSet defining ASCII alphabetic characters "A-Z".
+ *
* @since 2.0
*/
public static final CharSet ASCII_ALPHA_UPPER = new CharSet("A-Z");
- /**
+ /**
* A CharSet defining ASCII alphabetic characters "0-9".
+ *
* @since 2.0
*/
public static final CharSet ASCII_NUMERIC = new CharSet("0-9");
/**
* A Map of the common cases used in the factory.
- * Subclasses can add more common patterns if desired
+ *
+ * Subclasses can add more common patterns if desired.
+ *
+ *
* @since 2.0
*/
- protected static final Map COMMON = Collections.synchronizedMap(new HashMap());
-
+ protected static final Map COMMON = Collections.synchronizedMap(new HashMap<>());
+
static {
COMMON.put(null, EMPTY);
- COMMON.put("", EMPTY);
+ COMMON.put(StringUtils.EMPTY, EMPTY);
COMMON.put("a-zA-Z", ASCII_ALPHA);
COMMON.put("A-Za-z", ASCII_ALPHA);
COMMON.put("a-z", ASCII_ALPHA_LOWER);
@@ -87,12 +97,8 @@ public class CharSet implements Serializable {
COMMON.put("0-9", ASCII_NUMERIC);
}
- /** The set of CharRange objects. */
- private final Set set = Collections.synchronizedSet(new HashSet());
-
- //-----------------------------------------------------------------------
/**
- * Factory method to create a new CharSet using a special syntax.
+ * Creates a new CharSet using the syntax described below.
*
*
* - {@code null} or empty string ("")
@@ -109,12 +115,12 @@ public class CharSet implements Serializable {
*
*
The matching order is:
*
- * - Negated multi character range, such as "^a-e"
- *
- Ordinary multi character range, such as "a-e"
- *
- Negated single character, such as "^a"
- *
- Ordinary single character, such as "a"
+ *
- Negated multi character range, such as "^a-e"
+ * - Ordinary multi character range, such as "a-e"
+ * - Negated single character, such as "^a"
+ * - Ordinary single character, such as "a"
*
- *
+ *
* Matching works left to right. Once a match is found the
* search starts again from the next character.
*
@@ -128,11 +134,11 @@ public class CharSet implements Serializable {
* as the "a-e" and "e-a" are the same.
*
* The set of characters represented is the union of the specified ranges.
- *
+ *
* There are two ways to add a literal negation character ({@code ^}):
*
* - As the last character in a string, e.g. {@code CharSet.getInstance("a-z^")}
- * - As a separate element, e.g. {@code CharSet.getInstance("^","a-z")}
+ * - As a separate element, e.g. {@code CharSet.getInstance("^", "a-z")}
*
*
* Examples using the negation character:
@@ -141,20 +147,20 @@ public class CharSet implements Serializable {
* CharSet.getInstance("^a-c").contains('d') = true
* CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is negated)
* CharSet.getInstance("^^a-c").contains('^') = false
- * CharSet.getInstance("^a-cd-f").contains('d') = true
+ * CharSet.getInstance("^a-cd-f").contains('d') = true
* CharSet.getInstance("a-c^").contains('^') = true
* CharSet.getInstance("^", "a-c").contains('^') = true
*
- *
+ *
* All CharSet objects returned by this method will be immutable.
*
- * @param setStrs Strings to merge into the set, may be null
- * @return a CharSet instance
+ * @param setStrs Strings to merge into the set, may be null.
+ * @return a CharSet instance.
* @since 2.4
*/
public static CharSet getInstance(final String... setStrs) {
if (setStrs == null) {
- return null;
+ return EMPTY;
}
if (setStrs.length == 1) {
final CharSet common = COMMON.get(setStrs[0]);
@@ -162,28 +168,25 @@ public static CharSet getInstance(final String... setStrs) {
return common;
}
}
- return new CharSet(setStrs);
+ return new CharSet(setStrs);
}
- //-----------------------------------------------------------------------
+ /** The set of CharRange objects. */
+ private final Set set = Collections.synchronizedSet(new LinkedHashSet<>());
+
/**
- * Constructs a new CharSet using the set syntax.
- * Each string is merged in with the set.
+ * Constructs a new CharSet using the set syntax.
+ * Each string is merged in with the set.
*
- * @param set Strings to merge into the initial set
- * @throws NullPointerException if set is {@code null}
+ * @param set Strings to merge into the initial set.
+ * @throws NullPointerException if set is {@code null}.
*/
protected CharSet(final String... set) {
- super();
- final int sz = set.length;
- for (int i = 0; i < sz; i++) {
- add(set[i]);
- }
+ Stream.of(set).forEach(this::add);
}
- //-----------------------------------------------------------------------
/**
- * Add a set definition string to the {@code CharSet}.
+ * Add a set definition string to the {@link CharSet}.
*
* @param str set definition string
*/
@@ -191,7 +194,6 @@ protected void add(final String str) {
if (str == null) {
return;
}
-
final int len = str.length();
int pos = 0;
while (pos < len) {
@@ -216,47 +218,39 @@ protected void add(final String str) {
}
}
- //-----------------------------------------------------------------------
/**
- * Gets the internal set as an array of CharRange objects.
- *
- * @return an array of immutable CharRange objects
- * @since 2.0
- */
-// NOTE: This is no longer public as CharRange is no longer a public class.
-// It may be replaced when CharSet moves to Range.
- /*public*/ CharRange[] getCharRanges() {
- return set.toArray(new CharRange[set.size()]);
- }
-
- //-----------------------------------------------------------------------
- /**
- * Does the {@code CharSet} contain the specified
- * character {@code ch}.
+ * Tests whether this {@link CharSet} contain the specified character {@code ch}.
+ *
+ * Examples using the negation character:
+ *
+ *
+ * CharSet.getInstance("^a-c").contains('a') = false
+ * CharSet.getInstance("^a-c").contains('d') = true
+ * CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is negated)
+ * CharSet.getInstance("^^a-c").contains('^') = false
+ * CharSet.getInstance("^a-cd-f").contains('d') = true
+ * CharSet.getInstance("a-c^").contains('^') = true
+ * CharSet.getInstance("^", "a-c").contains('^') = true
+ *
*
- * @param ch the character to check for
- * @return {@code true} if the set contains the characters
+ * @param ch the character to check.
+ * @return {@code true} if the set contains the characters.
*/
public boolean contains(final char ch) {
- for (final CharRange range : set) {
- if (range.contains(ch)) {
- return true;
- }
+ synchronized (set) {
+ return set.stream().anyMatch(range -> range.contains(ch));
}
- return false;
}
- // Basics
- //-----------------------------------------------------------------------
/**
- * Compares two {@code CharSet} objects, returning true if they represent
- * exactly the same set of characters defined in the same way.
+ * Compares two {@link CharSet} objects, returning true if they represent
+ * exactly the same set of characters defined in the same way.
*
- * The two sets {@code abc} and {@code a-c} are not
+ *
The two sets {@code abc} and {@code a-c} are not
* equal according to this method.
*
- * @param obj the object to compare to
- * @return true if equal
+ * @param obj the object to compare.
+ * @return true if equal.
* @since 2.0
*/
@Override
@@ -264,7 +258,7 @@ public boolean equals(final Object obj) {
if (obj == this) {
return true;
}
- if (obj instanceof CharSet == false) {
+ if (!(obj instanceof CharSet)) {
return false;
}
final CharSet other = (CharSet) obj;
@@ -272,9 +266,21 @@ public boolean equals(final Object obj) {
}
/**
- * Gets a hash code compatible with the equals method.
+ * Gets the set of character ranges.
+ *
+ * Package private for testing.
+ *
+ *
+ * @return the set of character ranges.
+ */
+ Set getCharRanges() {
+ return set;
+ }
+
+ /**
+ * Gets a hash code compatible with the equals method.
*
- * @return a suitable hash code
+ * @return a suitable hash code.
* @since 2.0
*/
@Override
@@ -283,9 +289,9 @@ public int hashCode() {
}
/**
- * Gets a string representation of the set.
+ * Gets a string representation of the set.
*
- * @return string representation of the set
+ * @return string representation of the set.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/lang3/CharSetUtils.java b/src/main/java/org/apache/commons/lang3/CharSetUtils.java
index 859967410fd..d8dd4aa2124 100644
--- a/src/main/java/org/apache/commons/lang3/CharSetUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharSetUtils.java
@@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -16,77 +16,25 @@
*/
package org.apache.commons.lang3;
+import org.apache.commons.lang3.stream.Streams;
+
/**
- * Operations on {@code CharSet} instances.
+ * Operations on {@link CharSet} instances.
*
* This class handles {@code null} input gracefully.
* An exception will not be thrown for a {@code null} input.
- * Each method documents its behaviour in more detail.
- *
+ * Each method documents its behavior in more detail.
+ *
* #ThreadSafe#
+ *
* @see CharSet
* @since 1.0
*/
public class CharSetUtils {
/**
- * CharSetUtils instances should NOT be constructed in standard programming.
- * Instead, the class should be used as {@code CharSetUtils.evaluateSet(null);}.
- *
- * This constructor is public to permit tools that require a JavaBean instance
- * to operate.
- */
- public CharSetUtils() {
- super();
- }
-
- // Squeeze
- //-----------------------------------------------------------------------
- /**
- * Squeezes any repetitions of a character that is mentioned in the
- * supplied set.
- *
- *
- * CharSetUtils.squeeze(null, *) = null
- * CharSetUtils.squeeze("", *) = ""
- * CharSetUtils.squeeze(*, null) = *
- * CharSetUtils.squeeze(*, "") = *
- * CharSetUtils.squeeze("hello", "k-p") = "helo"
- * CharSetUtils.squeeze("hello", "a-e") = "hello"
- *
- *
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
- * @param str the string to squeeze, may be null
- * @param set the character set to use for manipulation, may be null
- * @return the modified String, {@code null} if null string input
- */
- public static String squeeze(final String str, final String... set) {
- if (StringUtils.isEmpty(str) || deepEmpty(set)) {
- return str;
- }
- final CharSet chars = CharSet.getInstance(set);
- final StringBuilder buffer = new StringBuilder(str.length());
- final char[] chrs = str.toCharArray();
- final int sz = chrs.length;
- char lastChar = ' ';
- char ch = ' ';
- for (int i = 0; i < sz; i++) {
- ch = chrs[i];
- // Compare with contains() last for performance.
- if (ch == lastChar && i != 0 && chars.contains(ch)) {
- continue;
- }
- buffer.append(ch);
- lastChar = ch;
- }
- return buffer.toString();
- }
-
- // ContainsAny
- //-----------------------------------------------------------------------
- /**
- * Takes an argument in set-syntax, see evaluateSet,
- * and identifies whether any of the characters are present in the specified string.
+ * Takes an argument in set-syntax, see evaluateSet,
+ * and identifies whether any of the characters are present in the specified string.
*
*
* CharSetUtils.containsAny(null, *) = false
@@ -97,14 +45,14 @@ public static String squeeze(final String str, final String... set) {
* CharSetUtils.containsAny("hello", "a-d") = false
*
*
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
+ * @see CharSet#getInstance(String...) for set-syntax.
* @param str String to look for characters in, may be null
* @param set String[] set of characters to identify, may be null
* @return whether or not the characters in the set are in the primary string
* @since 3.2
*/
public static boolean containsAny(final String str, final String... set) {
- if (StringUtils.isEmpty(str) || deepEmpty(set)) {
+ if (isEmpty(str, set)) {
return false;
}
final CharSet chars = CharSet.getInstance(set);
@@ -116,11 +64,9 @@ public static boolean containsAny(final String str, final String... set) {
return false;
}
- // Count
- //-----------------------------------------------------------------------
/**
- * Takes an argument in set-syntax, see evaluateSet,
- * and returns the number of characters present in the specified string.
+ * Takes an argument in set-syntax, see evaluateSet,
+ * and returns the number of characters present in the specified string.
*
*
* CharSetUtils.count(null, *) = 0
@@ -131,13 +77,13 @@ public static boolean containsAny(final String str, final String... set) {
* CharSetUtils.count("hello", "a-e") = 1
*
*
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
+ * @see CharSet#getInstance(String...) for set-syntax.
* @param str String to count characters in, may be null
* @param set String[] set of characters to count, may be null
* @return the character count, zero if null string input
*/
public static int count(final String str, final String... set) {
- if (StringUtils.isEmpty(str) || deepEmpty(set)) {
+ if (isEmpty(str, set)) {
return 0;
}
final CharSet chars = CharSet.getInstance(set);
@@ -150,42 +96,20 @@ public static int count(final String str, final String... set) {
return count;
}
- // Keep
- //-----------------------------------------------------------------------
/**
- * Takes an argument in set-syntax, see evaluateSet,
- * and keeps any of characters present in the specified string.
- *
- *
- * CharSetUtils.keep(null, *) = null
- * CharSetUtils.keep("", *) = ""
- * CharSetUtils.keep(*, null) = ""
- * CharSetUtils.keep(*, "") = ""
- * CharSetUtils.keep("hello", "hl") = "hll"
- * CharSetUtils.keep("hello", "le") = "ell"
- *
+ * Determines whether or not all the Strings in an array are
+ * empty or not.
*
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
- * @param str String to keep characters from, may be null
- * @param set String[] set of characters to keep, may be null
- * @return the modified String, {@code null} if null string input
- * @since 2.0
+ * @param strings String[] whose elements are being checked for emptiness
+ * @return whether or not the String is empty
*/
- public static String keep(final String str, final String... set) {
- if (str == null) {
- return null;
- }
- if (str.isEmpty() || deepEmpty(set)) {
- return StringUtils.EMPTY;
- }
- return modify(str, set, true);
+ private static boolean deepEmpty(final String[] strings) {
+ return Streams.of(strings).allMatch(StringUtils::isEmpty);
}
- // Delete
- //-----------------------------------------------------------------------
/**
- * Takes an argument in set-syntax, see evaluateSet,
- * and deletes any of characters present in the specified string.
+ * Takes an argument in set-syntax, see evaluateSet,
+ * and deletes any of characters present in the specified string.
*
*
* CharSetUtils.delete(null, *) = null
@@ -196,21 +120,53 @@ public static String keep(final String str, final String... set) {
* CharSetUtils.delete("hello", "le") = "ho"
*
*
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
+ * @see CharSet#getInstance(String...) for set-syntax.
* @param str String to delete characters from, may be null
* @param set String[] set of characters to delete, may be null
* @return the modified String, {@code null} if null string input
*/
public static String delete(final String str, final String... set) {
- if (StringUtils.isEmpty(str) || deepEmpty(set)) {
+ if (isEmpty(str, set)) {
return str;
}
return modify(str, set, false);
}
- //-----------------------------------------------------------------------
+ private static boolean isEmpty(final String str, final String... set) {
+ return StringUtils.isEmpty(str) || deepEmpty(set);
+ }
+
+ /**
+ * Takes an argument in set-syntax, see evaluateSet,
+ * and keeps any of characters present in the specified string.
+ *
+ *
+ * CharSetUtils.keep(null, *) = null
+ * CharSetUtils.keep("", *) = ""
+ * CharSetUtils.keep(*, null) = ""
+ * CharSetUtils.keep(*, "") = ""
+ * CharSetUtils.keep("hello", "hl") = "hll"
+ * CharSetUtils.keep("hello", "le") = "ell"
+ *
+ *
+ * @see CharSet#getInstance(String...) for set-syntax.
+ * @param str String to keep characters from, may be null
+ * @param set String[] set of characters to keep, may be null
+ * @return the modified String, {@code null} if null string input
+ * @since 2.0
+ */
+ public static String keep(final String str, final String... set) {
+ if (str == null) {
+ return null;
+ }
+ if (str.isEmpty() || deepEmpty(set)) {
+ return StringUtils.EMPTY;
+ }
+ return modify(str, set, true);
+ }
+
/**
- * Implementation of delete and keep
+ * Implements delete and keep.
*
* @param str String to modify characters within
* @param set String[] set of characters to modify
@@ -221,30 +177,75 @@ private static String modify(final String str, final String[] set, final boolean
final CharSet chars = CharSet.getInstance(set);
final StringBuilder buffer = new StringBuilder(str.length());
final char[] chrs = str.toCharArray();
- final int sz = chrs.length;
- for(int i=0; i
+ * CharSetUtils.squeeze(null, *) = null
+ * CharSetUtils.squeeze("", *) = ""
+ * CharSetUtils.squeeze(*, null) = *
+ * CharSetUtils.squeeze(*, "") = *
+ * CharSetUtils.squeeze("hello", "k-p") = "helo"
+ * CharSetUtils.squeeze("hello", "a-e") = "hello"
+ *
+ *
+ * @see CharSet#getInstance(String...) for set-syntax.
+ * @param str the string to squeeze, may be null
+ * @param set the character set to use for manipulation, may be null
+ * @return the modified String, {@code null} if null string input
*/
- private static boolean deepEmpty(final String[] strings) {
- if (strings != null) {
- for (final String s : strings) {
- if (StringUtils.isNotEmpty(s)) {
- return false;
+ public static String squeeze(final String str, final String... set) {
+ if (isEmpty(str, set)) {
+ return str;
+ }
+ final CharSet chars = CharSet.getInstance(set);
+ final StringBuilder buffer = new StringBuilder(str.length());
+ final char[] chrs = str.toCharArray();
+ final int sz = chrs.length;
+ char lastChar = chrs[0];
+ char ch;
+ Character inChars = null;
+ Character notInChars = null;
+ buffer.append(lastChar);
+ for (int i = 1; i < sz; i++) {
+ ch = chrs[i];
+ if (ch == lastChar) {
+ if (inChars != null && ch == inChars) {
+ continue;
+ }
+ if (notInChars == null || ch != notInChars) {
+ if (chars.contains(ch)) {
+ inChars = ch;
+ continue;
+ }
+ notInChars = ch;
}
}
+ buffer.append(ch);
+ lastChar = ch;
}
- return true;
+ return buffer.toString();
+ }
+
+ /**
+ * CharSetUtils instances should NOT be constructed in standard programming.
+ * Instead, the class should be used as {@code CharSetUtils.evaluateSet(null);}.
+ *
+ * This constructor is public to permit tools that require a JavaBean instance
+ * to operate.
+ *
+ * @deprecated TODO Make private in 4.0.
+ */
+ @Deprecated
+ public CharSetUtils() {
}
}
diff --git a/src/main/java/org/apache/commons/lang3/CharUtils.java b/src/main/java/org/apache/commons/lang3/CharUtils.java
index 3e957411557..fda1bf6184e 100644
--- a/src/main/java/org/apache/commons/lang3/CharUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharUtils.java
@@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -16,127 +16,274 @@
*/
package org.apache.commons.lang3;
+import java.util.Objects;
+
/**
- * Operations on char primitives and Character objects.
+ * Operations on char primitives and Character objects.
*
* This class tries to handle {@code null} input gracefully.
* An exception will not be thrown for a {@code null} input.
- * Each method documents its behaviour in more detail.
- *
+ * Each method documents its behavior in more detail.
+ *
* #ThreadSafe#
+ *
* @since 2.1
*/
public class CharUtils {
-
- private static final String[] CHAR_STRING_ARRAY = new String[128];
-
- private static final char[] HEX_DIGITS = new char[] {'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'};
+
+ private static final String[] CHAR_STRING_ARRAY = ArrayUtils.setAll(new String[128], i -> String.valueOf((char) i));
+
+ private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
/**
- * {@code \u000a} linefeed LF ('\n').
- *
- * @see JLF: Escape Sequences
+ * Linefeed character LF ({@code '\n'}, Unicode 000a).
+ *
+ * @see JLF: Escape Sequences
* for Character and String Literals
* @since 2.2
*/
public static final char LF = '\n';
/**
- * {@code \u000d} carriage return CR ('\r').
- *
- * @see JLF: Escape Sequences
+ * Carriage return character CR ('\r', Unicode 000d).
+ *
+ * @see JLF: Escape Sequences
* for Character and String Literals
* @since 2.2
*/
public static final char CR = '\r';
-
- static {
- for (char c = 0; c < CHAR_STRING_ARRAY.length; c++) {
- CHAR_STRING_ARRAY[c] = String.valueOf(c);
- }
+ /**
+ * {@code \u0000} null control character ('\0'), abbreviated NUL.
+ *
+ * @since 3.6
+ */
+ public static final char NUL = '\0';
+
+ /**
+ * Compares two {@code char} values numerically. This is the same functionality as provided in Java 7.
+ *
+ * @param x the first {@code char} to compare
+ * @param y the second {@code char} to compare
+ * @return the value {@code 0} if {@code x == y};
+ * a value less than {@code 0} if {@code x < y}; and
+ * a value greater than {@code 0} if {@code x > y}
+ * @since 3.4
+ */
+ public static int compare(final char x, final char y) {
+ return x - y;
}
/**
- * {@code CharUtils} instances should NOT be constructed in standard programming.
- * Instead, the class should be used as {@code CharUtils.toString('c');}.
+ * Tests whether the character is ASCII 7 bit.
*
- * This constructor is public to permit tools that require a JavaBean instance
- * to operate.
+ *
+ * CharUtils.isAscii('a') = true
+ * CharUtils.isAscii('A') = true
+ * CharUtils.isAscii('3') = true
+ * CharUtils.isAscii('-') = true
+ * CharUtils.isAscii('\n') = true
+ * CharUtils.isAscii('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if less than 128
*/
- public CharUtils() {
- super();
+ public static boolean isAscii(final char ch) {
+ return ch < 128;
}
- //-----------------------------------------------------------------------
/**
- * Converts the character to a Character.
- *
- * For ASCII 7 bit characters, this uses a cache that will return the
- * same Character object each time.
+ * Tests whether the character is ASCII 7 bit alphabetic.
*
*
- * CharUtils.toCharacterObject(' ') = ' '
- * CharUtils.toCharacterObject('A') = 'A'
+ * CharUtils.isAsciiAlpha('a') = true
+ * CharUtils.isAsciiAlpha('A') = true
+ * CharUtils.isAsciiAlpha('3') = false
+ * CharUtils.isAsciiAlpha('-') = false
+ * CharUtils.isAsciiAlpha('\n') = false
+ * CharUtils.isAsciiAlpha('©') = false
*
*
- * @deprecated Java 5 introduced {@link Character#valueOf(char)} which caches chars 0 through 127.
- * @param ch the character to convert
- * @return a Character of the specified character
+ * @param ch the character to check
+ * @return true if between 65 and 90 or 97 and 122 inclusive
*/
- @Deprecated
- public static Character toCharacterObject(final char ch) {
- return Character.valueOf(ch);
+ public static boolean isAsciiAlpha(final char ch) {
+ return isAsciiAlphaUpper(ch) || isAsciiAlphaLower(ch);
}
-
+
/**
- * Converts the String to a Character using the first character, returning
- * null for empty Strings.
- *
- * For ASCII 7 bit characters, this uses a cache that will return the
- * same Character object each time.
- *
+ * Tests whether the character is ASCII 7 bit alphabetic lower case.
+ *
*
- * CharUtils.toCharacterObject(null) = null
- * CharUtils.toCharacterObject("") = null
- * CharUtils.toCharacterObject("A") = 'A'
- * CharUtils.toCharacterObject("BA") = 'B'
+ * CharUtils.isAsciiAlphaLower('a') = true
+ * CharUtils.isAsciiAlphaLower('A') = false
+ * CharUtils.isAsciiAlphaLower('3') = false
+ * CharUtils.isAsciiAlphaLower('-') = false
+ * CharUtils.isAsciiAlphaLower('\n') = false
+ * CharUtils.isAsciiAlphaLower('©') = false
*
*
- * @param str the character to convert
- * @return the Character value of the first letter of the String
+ * @param ch the character to check
+ * @return true if between 97 and 122 inclusive
*/
- public static Character toCharacterObject(final String str) {
- if (StringUtils.isEmpty(str)) {
- return null;
- }
- return Character.valueOf(str.charAt(0));
+ public static boolean isAsciiAlphaLower(final char ch) {
+ return ch >= 'a' && ch <= 'z';
+ }
+
+ /**
+ * Tests whether the character is ASCII 7 bit alphanumeric character.
+ *
+ *
+ * CharUtils.isAsciiAlphanumeric('a') = true
+ * CharUtils.isAsciiAlphanumeric('A') = true
+ * CharUtils.isAsciiAlphanumeric('3') = true
+ * CharUtils.isAsciiAlphanumeric('-') = false
+ * CharUtils.isAsciiAlphanumeric('\n') = false
+ * CharUtils.isAsciiAlphanumeric('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
+ */
+ public static boolean isAsciiAlphanumeric(final char ch) {
+ return isAsciiAlpha(ch) || isAsciiNumeric(ch);
+ }
+
+ /**
+ * Tests whether the character is ASCII 7 bit alphabetic upper case.
+ *
+ *
+ * CharUtils.isAsciiAlphaUpper('a') = false
+ * CharUtils.isAsciiAlphaUpper('A') = true
+ * CharUtils.isAsciiAlphaUpper('3') = false
+ * CharUtils.isAsciiAlphaUpper('-') = false
+ * CharUtils.isAsciiAlphaUpper('\n') = false
+ * CharUtils.isAsciiAlphaUpper('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if between 65 and 90 inclusive
+ */
+ public static boolean isAsciiAlphaUpper(final char ch) {
+ return ch >= 'A' && ch <= 'Z';
+ }
+
+ /**
+ * Tests whether the character is ASCII 7 bit control.
+ *
+ *
+ * CharUtils.isAsciiControl('a') = false
+ * CharUtils.isAsciiControl('A') = false
+ * CharUtils.isAsciiControl('3') = false
+ * CharUtils.isAsciiControl('-') = false
+ * CharUtils.isAsciiControl('\n') = true
+ * CharUtils.isAsciiControl('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if less than 32 or equals 127
+ */
+ public static boolean isAsciiControl(final char ch) {
+ return ch < 32 || ch == 127;
}
-
- //-----------------------------------------------------------------------
+
/**
- * Converts the Character to a char throwing an exception for {@code null}.
- *
+ * Tests whether the character is ASCII 7 bit numeric.
+ *
+ *
+ * CharUtils.isAsciiNumeric('a') = false
+ * CharUtils.isAsciiNumeric('A') = false
+ * CharUtils.isAsciiNumeric('3') = true
+ * CharUtils.isAsciiNumeric('-') = false
+ * CharUtils.isAsciiNumeric('\n') = false
+ * CharUtils.isAsciiNumeric('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if between 48 and 57 inclusive
+ */
+ public static boolean isAsciiNumeric(final char ch) {
+ return ch >= '0' && ch <= '9';
+ }
+
+ /**
+ * Tests whether the character is ASCII 7 bit printable.
+ *
+ *
+ * CharUtils.isAsciiPrintable('a') = true
+ * CharUtils.isAsciiPrintable('A') = true
+ * CharUtils.isAsciiPrintable('3') = true
+ * CharUtils.isAsciiPrintable('-') = true
+ * CharUtils.isAsciiPrintable('\n') = false
+ * CharUtils.isAsciiPrintable('©') = false
+ *
+ *
+ * @param ch the character to check
+ * @return true if between 32 and 126 inclusive
+ */
+ public static boolean isAsciiPrintable(final char ch) {
+ return ch >= 32 && ch < 127;
+ }
+
+ /**
+ * Tests whether a character is a hexadecimal character.
+ *
+ *
+ * CharUtils.isHex('0') = true
+ * CharUtils.isHex('3') = true
+ * CharUtils.isHex('9') = true
+ * CharUtils.isHex('a') = true
+ * CharUtils.isHex('f') = true
+ * CharUtils.isHex('g') = false
+ * CharUtils.isHex('A') = true
+ * CharUtils.isHex('F') = true
+ * CharUtils.isHex('G') = false
+ * CharUtils.isHex('#') = false
+ * CharUtils.isHex('-') = false
+ * CharUtils.isHex('\n') = false
+ * CharUtils.isHex('©') = false
+ *
+ *
+ * @param ch the character to test.
+ * @return true if character is a hexadecimal character.
+ * @since 3.18.0
+ */
+ public static boolean isHex(final char ch) {
+ return isAsciiNumeric(ch) || ch >= 'a' && ch <= 'f' || ch >= 'A' && ch <= 'F';
+ }
+
+ /**
+ * Tests if the given char is an octal digit. Octal digits are the character representations of the digits 0 to 7.
+ *
+ * @param ch the char to check
+ * @return true if the given char is the character representation of one of the digits from 0 to 7
+ * @since 3.18.0
+ */
+ public static boolean isOctal(final char ch) {
+ return ch >= '0' && ch <= '7';
+ }
+
+ /**
+ * Converts the Character to a char throwing an exception for {@code null}.
+ *
*
* CharUtils.toChar(' ') = ' '
* CharUtils.toChar('A') = 'A'
- * CharUtils.toChar(null) throws IllegalArgumentException
+ * CharUtils.toChar(null) throws NullPointerException
*
*
* @param ch the character to convert
* @return the char value of the Character
- * @throws IllegalArgumentException if the Character is null
+ * @throws NullPointerException if the Character is null
*/
public static char toChar(final Character ch) {
- if (ch == null) {
- throw new IllegalArgumentException("The Character must not be null");
- }
- return ch.charValue();
+ return Objects.requireNonNull(ch, "ch").charValue();
}
-
+
/**
- * Converts the Character to a char handling {@code null}.
- *
+ * Converts the Character to a char handling {@code null}.
+ *
*
* CharUtils.toChar(null, 'X') = 'X'
* CharUtils.toChar(' ', 'X') = ' '
@@ -148,39 +295,34 @@ public static char toChar(final Character ch) {
* @return the char value of the Character or the default if null
*/
public static char toChar(final Character ch, final char defaultValue) {
- if (ch == null) {
- return defaultValue;
- }
- return ch.charValue();
+ return ch != null ? ch.charValue() : defaultValue;
}
-
- //-----------------------------------------------------------------------
+
/**
- * Converts the String to a char using the first character, throwing
- * an exception on empty Strings.
- *
+ * Converts the String to a char using the first character, throwing
+ * an exception on empty Strings.
+ *
*
* CharUtils.toChar("A") = 'A'
* CharUtils.toChar("BA") = 'B'
- * CharUtils.toChar(null) throws IllegalArgumentException
+ * CharUtils.toChar(null) throws NullPointerException
* CharUtils.toChar("") throws IllegalArgumentException
*
*
* @param str the character to convert
* @return the char value of the first letter of the String
+ * @throws NullPointerException if the string is null
* @throws IllegalArgumentException if the String is empty
*/
public static char toChar(final String str) {
- if (StringUtils.isEmpty(str)) {
- throw new IllegalArgumentException("The String must not be empty");
- }
+ Validate.notEmpty(str, "The String must not be empty");
return str.charAt(0);
}
-
+
/**
- * Converts the String to a char using the first character, defaulting
- * the value on empty Strings.
- *
+ * Converts the String to a char using the first character, defaulting
+ * the value on empty Strings.
+ *
*
* CharUtils.toChar(null, 'X') = 'X'
* CharUtils.toChar("", 'X') = 'X'
@@ -193,18 +335,47 @@ public static char toChar(final String str) {
* @return the char value of the first letter of the String or the default if null
*/
public static char toChar(final String str, final char defaultValue) {
- if (StringUtils.isEmpty(str)) {
- return defaultValue;
- }
- return str.charAt(0);
+ return StringUtils.isEmpty(str) ? defaultValue : str.charAt(0);
+ }
+
+ /**
+ * Delegates to {@link Character#valueOf(char)}.
+ *
+ * @param c the character to convert
+ * @return a {@code Character} representing {@code c}.
+ * @deprecated Use {@link Character#valueOf(char)}.
+ */
+ @Deprecated
+ public static Character toCharacterObject(final char c) {
+ return Character.valueOf(c);
+ }
+
+ /**
+ * Converts the String to a Character using the first character, returning
+ * null for empty Strings.
+ *
+ * For ASCII 7 bit characters, this uses a cache that will return the
+ * same Character object each time.
+ *
+ *
+ * CharUtils.toCharacterObject(null) = null
+ * CharUtils.toCharacterObject("") = null
+ * CharUtils.toCharacterObject("A") = 'A'
+ * CharUtils.toCharacterObject("BA") = 'B'
+ *
+ *
+ * @param str the character to convert
+ * @return the Character value of the first letter of the String
+ */
+ public static Character toCharacterObject(final String str) {
+ return StringUtils.isEmpty(str) ? null : Character.valueOf(str.charAt(0));
}
-
- //-----------------------------------------------------------------------
+
/**
- * Converts the character to the Integer it represents, throwing an
- * exception if the character is not numeric.
- *
- * This method coverts the char '1' to the int 1 and so on.
+ * Converts the character to the Integer it represents, throwing an
+ * exception if the character is not numeric.
+ *
+ * This method converts the char '1' to the int 1 and so on.
*
*
* CharUtils.toIntValue('3') = 3
@@ -216,17 +387,17 @@ public static char toChar(final String str, final char defaultValue) {
* @throws IllegalArgumentException if the character is not ASCII numeric
*/
public static int toIntValue(final char ch) {
- if (isAsciiNumeric(ch) == false) {
+ if (!isAsciiNumeric(ch)) {
throw new IllegalArgumentException("The character " + ch + " is not in the range '0' - '9'");
}
return ch - 48;
}
-
+
/**
- * Converts the character to the Integer it represents, throwing an
- * exception if the character is not numeric.
- *
- * This method coverts the char '1' to the int 1 and so on.
+ * Converts the character to the Integer it represents, throwing an
+ * exception if the character is not numeric.
+ *
+ * This method converts the char '1' to the int 1 and so on.
*
*
* CharUtils.toIntValue('3', -1) = 3
@@ -238,40 +409,35 @@ public static int toIntValue(final char ch) {
* @return the int value of the character
*/
public static int toIntValue(final char ch, final int defaultValue) {
- if (isAsciiNumeric(ch) == false) {
- return defaultValue;
- }
- return ch - 48;
+ return isAsciiNumeric(ch) ? ch - 48 : defaultValue;
}
-
+
/**
- * Converts the character to the Integer it represents, throwing an
- * exception if the character is not numeric.
- *
- * This method coverts the char '1' to the int 1 and so on.
+ * Converts the character to the Integer it represents, throwing an
+ * exception if the character is not numeric.
+ *
+ * This method converts the char '1' to the int 1 and so on.
*
*
* CharUtils.toIntValue('3') = 3
- * CharUtils.toIntValue(null) throws IllegalArgumentException
+ * CharUtils.toIntValue(null) throws NullPointerException
* CharUtils.toIntValue('A') throws IllegalArgumentException
*
*
* @param ch the character to convert, not null
* @return the int value of the character
- * @throws IllegalArgumentException if the Character is not ASCII numeric or is null
+ * @throws NullPointerException if the Character is null
+ * @throws IllegalArgumentException if the Character is not ASCII numeric
*/
public static int toIntValue(final Character ch) {
- if (ch == null) {
- throw new IllegalArgumentException("The character must not be null");
- }
- return toIntValue(ch.charValue());
+ return toIntValue(toChar(ch));
}
-
+
/**
- * Converts the character to the Integer it represents, throwing an
- * exception if the character is not numeric.
- *
- * This method coverts the char '1' to the int 1 and so on.
+ * Converts the character to the Integer it represents, throwing an
+ * exception if the character is not numeric.
+ *
+ * This method converts the char '1' to the int 1 and so on.
*
*
* CharUtils.toIntValue(null, -1) = -1
@@ -284,16 +450,12 @@ public static int toIntValue(final Character ch) {
* @return the int value of the character
*/
public static int toIntValue(final Character ch, final int defaultValue) {
- if (ch == null) {
- return defaultValue;
- }
- return toIntValue(ch.charValue(), defaultValue);
+ return ch != null ? toIntValue(ch.charValue(), defaultValue) : defaultValue;
}
-
- //-----------------------------------------------------------------------
+
/**
- * Converts the character to a String that contains the one character.
- *
+ * Converts the character to a String that contains the one character.
+ *
* For ASCII 7 bit characters, this uses a cache that will return the
* same String object each time.
*
@@ -306,18 +468,18 @@ public static int toIntValue(final Character ch, final int defaultValue) {
* @return a String containing the one specified character
*/
public static String toString(final char ch) {
- if (ch < 128) {
+ if (ch < CHAR_STRING_ARRAY.length) {
return CHAR_STRING_ARRAY[ch];
}
- return new String(new char[] {ch});
+ return String.valueOf(ch);
}
-
+
/**
- * Converts the character to a String that contains the one character.
- *
+ * Converts the character to a String that contains the one character.
+ *
* For ASCII 7 bit characters, this uses a cache that will return the
* same String object each time.
- *
+ *
* If {@code null} is passed in, {@code null} will be returned.
*
*
@@ -330,41 +492,35 @@ public static String toString(final char ch) {
* @return a String containing the one specified character
*/
public static String toString(final Character ch) {
- if (ch == null) {
- return null;
- }
- return toString(ch.charValue());
+ return ch != null ? toString(ch.charValue()) : null;
}
-
- //--------------------------------------------------------------------------
+
/**
- * Converts the string to the Unicode format '\u0020'.
- *
+ * Converts the string to the Unicode format '\u0020'.
+ *
* This format is the Java source code format.
*
*
* CharUtils.unicodeEscaped(' ') = "\u0020"
* CharUtils.unicodeEscaped('A') = "\u0041"
*
- *
+ *
* @param ch the character to convert
* @return the escaped Unicode string
*/
public static String unicodeEscaped(final char ch) {
- StringBuilder sb = new StringBuilder(6);
- sb.append("\\u");
- sb.append(HEX_DIGITS[(ch >> 12) & 15]);
- sb.append(HEX_DIGITS[(ch >> 8) & 15]);
- sb.append(HEX_DIGITS[(ch >> 4) & 15]);
- sb.append(HEX_DIGITS[(ch) & 15]);
- return sb.toString();
+ return "\\u" +
+ HEX_DIGITS[ch >> 12 & 15] +
+ HEX_DIGITS[ch >> 8 & 15] +
+ HEX_DIGITS[ch >> 4 & 15] +
+ HEX_DIGITS[ch & 15];
}
-
+
/**
- * Converts the string to the Unicode format '\u0020'.
- *
+ * Converts the string to the Unicode format '\u0020'.
+ *
* This format is the Java source code format.
- *
+ *
* If {@code null} is passed in, {@code null} will be returned.
*
*
@@ -372,181 +528,25 @@ public static String unicodeEscaped(final char ch) {
* CharUtils.unicodeEscaped(' ') = "\u0020"
* CharUtils.unicodeEscaped('A') = "\u0041"
*
- *
+ *
* @param ch the character to convert, may be null
* @return the escaped Unicode string, null if null input
*/
public static String unicodeEscaped(final Character ch) {
- if (ch == null) {
- return null;
- }
- return unicodeEscaped(ch.charValue());
- }
-
- //--------------------------------------------------------------------------
- /**
- * Checks whether the character is ASCII 7 bit.
- *
- *
- * CharUtils.isAscii('a') = true
- * CharUtils.isAscii('A') = true
- * CharUtils.isAscii('3') = true
- * CharUtils.isAscii('-') = true
- * CharUtils.isAscii('\n') = true
- * CharUtils.isAscii('©') = false
- *
- *
- * @param ch the character to check
- * @return true if less than 128
- */
- public static boolean isAscii(final char ch) {
- return ch < 128;
- }
-
- /**
- * Checks whether the character is ASCII 7 bit printable.
- *
- *
- * CharUtils.isAsciiPrintable('a') = true
- * CharUtils.isAsciiPrintable('A') = true
- * CharUtils.isAsciiPrintable('3') = true
- * CharUtils.isAsciiPrintable('-') = true
- * CharUtils.isAsciiPrintable('\n') = false
- * CharUtils.isAsciiPrintable('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 32 and 126 inclusive
- */
- public static boolean isAsciiPrintable(final char ch) {
- return ch >= 32 && ch < 127;
- }
-
- /**
- * Checks whether the character is ASCII 7 bit control.
- *
- *
- * CharUtils.isAsciiControl('a') = false
- * CharUtils.isAsciiControl('A') = false
- * CharUtils.isAsciiControl('3') = false
- * CharUtils.isAsciiControl('-') = false
- * CharUtils.isAsciiControl('\n') = true
- * CharUtils.isAsciiControl('©') = false
- *
- *
- * @param ch the character to check
- * @return true if less than 32 or equals 127
- */
- public static boolean isAsciiControl(final char ch) {
- return ch < 32 || ch == 127;
- }
-
- /**
- * Checks whether the character is ASCII 7 bit alphabetic.
- *
- *
- * CharUtils.isAsciiAlpha('a') = true
- * CharUtils.isAsciiAlpha('A') = true
- * CharUtils.isAsciiAlpha('3') = false
- * CharUtils.isAsciiAlpha('-') = false
- * CharUtils.isAsciiAlpha('\n') = false
- * CharUtils.isAsciiAlpha('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 65 and 90 or 97 and 122 inclusive
- */
- public static boolean isAsciiAlpha(final char ch) {
- return isAsciiAlphaUpper(ch) || isAsciiAlphaLower(ch);
- }
-
- /**
- * Checks whether the character is ASCII 7 bit alphabetic upper case.
- *
- *
- * CharUtils.isAsciiAlphaUpper('a') = false
- * CharUtils.isAsciiAlphaUpper('A') = true
- * CharUtils.isAsciiAlphaUpper('3') = false
- * CharUtils.isAsciiAlphaUpper('-') = false
- * CharUtils.isAsciiAlphaUpper('\n') = false
- * CharUtils.isAsciiAlphaUpper('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 65 and 90 inclusive
- */
- public static boolean isAsciiAlphaUpper(final char ch) {
- return ch >= 'A' && ch <= 'Z';
- }
-
- /**
- * Checks whether the character is ASCII 7 bit alphabetic lower case.
- *
- *
- * CharUtils.isAsciiAlphaLower('a') = true
- * CharUtils.isAsciiAlphaLower('A') = false
- * CharUtils.isAsciiAlphaLower('3') = false
- * CharUtils.isAsciiAlphaLower('-') = false
- * CharUtils.isAsciiAlphaLower('\n') = false
- * CharUtils.isAsciiAlphaLower('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 97 and 122 inclusive
- */
- public static boolean isAsciiAlphaLower(final char ch) {
- return ch >= 'a' && ch <= 'z';
- }
-
- /**
- * Checks whether the character is ASCII 7 bit numeric.
- *
- *
- * CharUtils.isAsciiNumeric('a') = false
- * CharUtils.isAsciiNumeric('A') = false
- * CharUtils.isAsciiNumeric('3') = true
- * CharUtils.isAsciiNumeric('-') = false
- * CharUtils.isAsciiNumeric('\n') = false
- * CharUtils.isAsciiNumeric('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 48 and 57 inclusive
- */
- public static boolean isAsciiNumeric(final char ch) {
- return ch >= '0' && ch <= '9';
- }
-
- /**
- * Checks whether the character is ASCII 7 bit numeric.
- *
- *
- * CharUtils.isAsciiAlphanumeric('a') = true
- * CharUtils.isAsciiAlphanumeric('A') = true
- * CharUtils.isAsciiAlphanumeric('3') = true
- * CharUtils.isAsciiAlphanumeric('-') = false
- * CharUtils.isAsciiAlphanumeric('\n') = false
- * CharUtils.isAsciiAlphanumeric('©') = false
- *
- *
- * @param ch the character to check
- * @return true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
- */
- public static boolean isAsciiAlphanumeric(final char ch) {
- return isAsciiAlpha(ch) || isAsciiNumeric(ch);
+ return ch != null ? unicodeEscaped(ch.charValue()) : null;
}
/**
- * Compares two {@code char} values numerically. This is the same functionality as provided in Java 7.
+ * {@link CharUtils} instances should NOT be constructed in standard programming.
+ * Instead, the class should be used as {@code CharUtils.toString('c');}.
*
- * @param x the first {@code char} to compare
- * @param y the second {@code char} to compare
- * @return the value {@code 0} if {@code x == y};
- * a value less than {@code 0} if {@code x < y}; and
- * a value greater than {@code 0} if {@code x > y}
- * @since 3.4
+ * This constructor is public to permit tools that require a JavaBean instance
+ * to operate.
+ *
+ * @deprecated TODO Make private in 4.0.
*/
- public static int compare(char x, char y) {
- return x-y;
+ @Deprecated
+ public CharUtils() {
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/Charsets.java b/src/main/java/org/apache/commons/lang3/Charsets.java
new file mode 100644
index 00000000000..4db73473f20
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/Charsets.java
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+import java.nio.charset.Charset;
+import java.nio.charset.UnsupportedCharsetException;
+
+/**
+ * Internal use only.
+ *
+ * Provides utilities for {@link Charset}.
+ *
+ *
+ * Package private since Apache Commons IO already provides a Charsets because {@link Charset} is in
+ * {@code java.nio.charset}.
+ *
+ *
+ * @since 3.10
+ */
+final class Charsets {
+
+ /**
+ * Returns the given {@code charset} or the default Charset if {@code charset} is null.
+ *
+ * @param charset a Charset or null.
+ * @return the given {@code charset} or the default Charset if {@code charset} is null.
+ */
+ static Charset toCharset(final Charset charset) {
+ return charset == null ? Charset.defaultCharset() : charset;
+ }
+
+ /**
+ * Returns the given {@code charset} or the default Charset if {@code charset} is null.
+ *
+ * @param charsetName a Charset or null.
+ * @return the given {@code charset} or the default Charset if {@code charset} is null.
+ * @throws UnsupportedCharsetException If no support for the named charset is available in this instance of the Java
+ * virtual machine
+ */
+ static Charset toCharset(final String charsetName) {
+ return charsetName == null ? Charset.defaultCharset() : Charset.forName(charsetName);
+ }
+
+ /**
+ * Returns the given {@code charset} or the default Charset if {@code charset} is null.
+ *
+ * @param charsetName a Charset or null.
+ * @return the given {@code charset} or the default Charset if {@code charset} is null.
+ */
+ static String toCharsetName(final String charsetName) {
+ return charsetName == null ? Charset.defaultCharset().name() : charsetName;
+ }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/ClassLoaderUtils.java b/src/main/java/org/apache/commons/lang3/ClassLoaderUtils.java
new file mode 100644
index 00000000000..9e53fef0866
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/ClassLoaderUtils.java
@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * Helps work with {@link ClassLoader}.
+ *
+ * @since 3.10
+ */
+public class ClassLoaderUtils {
+
+ private static final URL[] EMPTY_URL_ARRAY = {};
+
+ /**
+ * Gets the system class loader's URLs, if any.
+ *
+ * @return the system class loader's URLs, if any.
+ * @since 3.13.0
+ */
+ public static URL[] getSystemURLs() {
+ return getURLs(ClassLoader.getSystemClassLoader());
+ }
+
+ /**
+ * Gets the current thread's context class loader's URLs, if any.
+ *
+ * @return the current thread's context class loader's URLs, if any.
+ * @since 3.13.0
+ */
+ public static URL[] getThreadURLs() {
+ return getURLs(Thread.currentThread().getContextClassLoader());
+ }
+
+ private static URL[] getURLs(final ClassLoader cl) {
+ return cl instanceof URLClassLoader ? ((URLClassLoader) cl).getURLs() : EMPTY_URL_ARRAY;
+ }
+
+ /**
+ * Converts the given class loader to a String calling {@link #toString(URLClassLoader)}.
+ *
+ * @param classLoader to URLClassLoader to convert.
+ * @return the formatted string.
+ */
+ public static String toString(final ClassLoader classLoader) {
+ if (classLoader instanceof URLClassLoader) {
+ return toString((URLClassLoader) classLoader);
+ }
+ return Objects.toString(classLoader);
+ }
+
+ /**
+ * Converts the given URLClassLoader to a String in the format {@code "URLClassLoader.toString() + [URL1, URL2, ...]"}.
+ *
+ * @param classLoader to URLClassLoader to convert.
+ * @return the formatted string.
+ */
+ public static String toString(final URLClassLoader classLoader) {
+ return classLoader != null ? classLoader + Arrays.toString(classLoader.getURLs()) : "null";
+ }
+
+ /**
+ * Make private in 4.0.
+ *
+ * @deprecated TODO Make private in 4.0.
+ */
+ @Deprecated
+ public ClassLoaderUtils() {
+ // empty
+ }
+}
diff --git a/src/main/java/org/apache/commons/lang3/ClassPathUtils.java b/src/main/java/org/apache/commons/lang3/ClassPathUtils.java
index df3773a344c..db7fbf385db 100644
--- a/src/main/java/org/apache/commons/lang3/ClassPathUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ClassPathUtils.java
@@ -6,7 +6,7 @@
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@@ -16,10 +16,14 @@
*/
package org.apache.commons.lang3;
+import java.util.Objects;
+
/**
* Operations regarding the classpath.
*
- * The methods of this class do not allow {@code null} inputs.
+ *
+ * The methods of this class do not allow {@code null} inputs.
+ *
*
* @since 3.3
*/
@@ -27,104 +31,130 @@
public class ClassPathUtils {
/**
- * {@code ClassPathUtils} instances should NOT be constructed in
- * standard programming. Instead, the class should be used as
- * {@code ClassPathUtils.toFullyQualifiedName(MyClass.class, "MyClass.properties");}.
+ * Converts a package name to a Java path ('/').
*
- * This constructor is public to permit tools that require a JavaBean
- * instance to operate.
+ * @param path the source path.
+ * @return a package name.
+ * @throws NullPointerException if {@code path} is null.
+ * @since 3.13.0
*/
- public ClassPathUtils() {
- super();
+ public static String packageToPath(final String path) {
+ return Objects.requireNonNull(path, "path").replace('.', '/');
+ }
+
+ /**
+ * Converts a Java path ('/') to a package name.
+ *
+ * @param path the source path.
+ * @return a package name.
+ * @throws NullPointerException if {@code path} is null.
+ * @since 3.13.0
+ */
+ public static String pathToPackage(final String path) {
+ return Objects.requireNonNull(path, "path").replace('/', '.');
}
/**
* Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
*
- * Note that this method does not check whether the resource actually exists.
- * It only constructs the name.
- * Null inputs are not allowed.
+ *
+ * Note that this method does not check whether the resource actually exists. It only constructs the name. Null inputs are not allowed.
+ *
*
*
* ClassPathUtils.toFullyQualifiedName(StringUtils.class, "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
*
*
- * @param context The context for constructing the name.
+ * @param context The context for constructing the name.
* @param resourceName the resource name to construct the fully qualified name for.
* @return the fully qualified name of the resource with name {@code resourceName}.
- * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
+ * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
*/
public static String toFullyQualifiedName(final Class context, final String resourceName) {
- Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
- Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
+ Objects.requireNonNull(context, "context");
+ Objects.requireNonNull(resourceName, "resourceName");
return toFullyQualifiedName(context.getPackage(), resourceName);
}
/**
* Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
*
- * Note that this method does not check whether the resource actually exists.
- * It only constructs the name.
- * Null inputs are not allowed.
+ *
+ * Note that this method does not check whether the resource actually exists. It only constructs the name. Null inputs are not allowed.
+ *
*
*
* ClassPathUtils.toFullyQualifiedName(StringUtils.class.getPackage(), "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
*
*
- * @param context The context for constructing the name.
+ * @param context The context for constructing the name.
* @param resourceName the resource name to construct the fully qualified name for.
* @return the fully qualified name of the resource with name {@code resourceName}.
- * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
+ * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
*/
public static String toFullyQualifiedName(final Package context, final String resourceName) {
- Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
- Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
+ Objects.requireNonNull(context, "context");
+ Objects.requireNonNull(resourceName, "resourceName");
return context.getName() + "." + resourceName;
}
/**
* Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
*
- * Note that this method does not check whether the resource actually exists.
- * It only constructs the path.
- * Null inputs are not allowed.
+ *
+ * Note that this method does not check whether the resource actually exists. It only constructs the path. Null inputs are not allowed.
+ *
*
*
* ClassPathUtils.toFullyQualifiedPath(StringUtils.class, "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
*
*
- * @param context The context for constructing the path.
+ * @param context The context for constructing the path.
* @param resourceName the resource name to construct the fully qualified path for.
* @return the fully qualified path of the resource with name {@code resourceName}.
- * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
+ * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
*/
public static String toFullyQualifiedPath(final Class context, final String resourceName) {
- Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
- Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
+ Objects.requireNonNull(context, "context");
+ Objects.requireNonNull(resourceName, "resourceName");
return toFullyQualifiedPath(context.getPackage(), resourceName);
}
-
/**
* Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
*
- * Note that this method does not check whether the resource actually exists.
- * It only constructs the path.
- * Null inputs are not allowed.
+ *
+ * Note that this method does not check whether the resource actually exists. It only constructs the path. Null inputs are not allowed.
+ *
*
*
* ClassPathUtils.toFullyQualifiedPath(StringUtils.class.getPackage(), "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
*
*
- * @param context The context for constructing the path.
+ * @param context The context for constructing the path.
* @param resourceName the resource name to construct the fully qualified path for.
* @return the fully qualified path of the resource with name {@code resourceName}.
- * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
+ * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
*/
public static String toFullyQualifiedPath(final Package context, final String resourceName) {
- Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
- Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
- return context.getName().replace('.', '/') + "/" + resourceName;
+ Objects.requireNonNull(context, "context");
+ Objects.requireNonNull(resourceName, "resourceName");
+ return packageToPath(context.getName()) + "/" + resourceName;
+ }
+
+ /**
+ * {@link ClassPathUtils} instances should NOT be constructed in standard programming. Instead, the class should be used as
+ * {@code ClassPathUtils.toFullyQualifiedName(MyClass.class, "MyClass.properties");}.
+ *
+ *
+ * This constructor is public to permit tools that require a JavaBean instance to operate.
+ *
+ *
+ * @deprecated TODO Make private in 4.0.
+ */
+ @Deprecated
+ public ClassPathUtils() {
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/ClassUtils.java b/src/main/java/org/apache/commons/lang3/ClassUtils.java
index 0a7480ff8d9..ca9894b794d 100644
--- a/src/main/java/org/apache/commons/lang3/ClassUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ClassUtils.java
@@ -6,7 +6,7 @@
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@@ -18,52 +18,91 @@
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
+import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Collections;
+import java.util.Comparator;
+import java.util.Deque;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
+import java.util.Objects;
import java.util.Set;
-
-import org.apache.commons.lang3.mutable.MutableObject;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.stream.Collectors;
/**
- * Operates on classes without using reflection.
+ * Operates on classes without using reflection.
*
- * This class handles invalid {@code null} inputs as best it can.
- * Each method documents its behaviour in more detail.
+ *
+ * This class handles invalid {@code null} inputs as best it can. Each method documents its behavior in more detail.
+ *
*
- * The notion of a {@code canonical name} includes the human
- * readable name for the type, for example {@code int[]}. The
- * non-canonical method variants work with the JVM names, such as
- * {@code [I}.
+ *
+ * The notion of a {@code canonical name} includes the human-readable name for the type, for example {@code int[]}. The
+ * non-canonical method variants work with the JVM names, such as {@code [I}.
+ *
*
* @since 2.0
*/
public class ClassUtils {
+
/**
- * Inclusivity literals for {@link #hierarchy(Class, Interfaces)}.
+ * Enumerates inclusivity literals for {@link #hierarchy(Class, Interfaces)}.
+ *
* @since 3.2
*/
public enum Interfaces {
- INCLUDE, EXCLUDE
+
+ /** Includes interfaces. */
+ INCLUDE,
+
+ /** Excludes interfaces. */
+ EXCLUDE
}
/**
- * The package separator character: '.' == {@value}.
+ * The JLS-specified maximum class name length {@value}.
+ *
+ * @see Class#forName(String, boolean, ClassLoader)
+ * @see JVM: Array dimension limits in JVM Specification CONSTANT_Class_info
+ * @see JLS: Fully Qualified Names and Canonical Names
+ * @see JLS: The Form of a Binary
+ */
+ private static final int MAX_CLASS_NAME_LENGTH = 65535;
+
+ /**
+ * The JVM-specified {@code CONSTANT_Class_info} structure defines an array type descriptor is valid only if it represents {@value} or fewer dimensions.
+ *
+ * @see Class#forName(String, boolean, ClassLoader)
+ * @see JVM: Array dimension limits in JVM Specification CONSTANT_Class_info
+ * @see JLS: Fully Qualified Names and Canonical Names
+ * @see JLS: The Form of a Binary
+ */
+ private static final int MAX_JVM_ARRAY_DIMENSION = 255;
+
+ /**
+ * The maximum number of array dimensions.
+ */
+ private static final int MAX_DIMENSIONS = 255;
+
+ private static final Comparator> COMPARATOR = (o1, o2) -> Objects.compare(getName(o1), getName(o2), String::compareTo);
+
+ /**
+ * The package separator character: {@code '.' == {@value}}.
*/
public static final char PACKAGE_SEPARATOR_CHAR = '.';
/**
- * The package separator String: ".".
+ * The package separator String: {@code "."}.
*/
public static final String PACKAGE_SEPARATOR = String.valueOf(PACKAGE_SEPARATOR_CHAR);
/**
- * The inner class separator character: '$' == {@value}.
+ * The inner class separator character: {@code '$' == {@value}}.
*/
public static final char INNER_CLASS_SEPARATOR_CHAR = '$';
@@ -73,342 +112,306 @@ public enum Interfaces {
public static final String INNER_CLASS_SEPARATOR = String.valueOf(INNER_CLASS_SEPARATOR_CHAR);
/**
- * Maps primitive {@code Class}es to their corresponding wrapper {@code Class}.
+ * Maps names of primitives to their corresponding primitive {@link Class}es.
+ */
+ private static final Map> NAME_PRIMITIVE_MAP = new HashMap<>();
+
+ static {
+ NAME_PRIMITIVE_MAP.put(Boolean.TYPE.getName(), Boolean.TYPE);
+ NAME_PRIMITIVE_MAP.put(Byte.TYPE.getName(), Byte.TYPE);
+ NAME_PRIMITIVE_MAP.put(Character.TYPE.getName(), Character.TYPE);
+ NAME_PRIMITIVE_MAP.put(Double.TYPE.getName(), Double.TYPE);
+ NAME_PRIMITIVE_MAP.put(Float.TYPE.getName(), Float.TYPE);
+ NAME_PRIMITIVE_MAP.put(Integer.TYPE.getName(), Integer.TYPE);
+ NAME_PRIMITIVE_MAP.put(Long.TYPE.getName(), Long.TYPE);
+ NAME_PRIMITIVE_MAP.put(Short.TYPE.getName(), Short.TYPE);
+ NAME_PRIMITIVE_MAP.put(Void.TYPE.getName(), Void.TYPE);
+ }
+
+ /**
+ * Maps primitive {@link Class}es to their corresponding wrapper {@link Class}.
*/
- private static final Map, Class> primitiveWrapperMap = new HashMap, Class>();
+ private static final Map, Class> PRIMITIVE_WRAPPER_MAP = new HashMap<>();
+
static {
- primitiveWrapperMap.put(Boolean.TYPE, Boolean.class);
- primitiveWrapperMap.put(Byte.TYPE, Byte.class);
- primitiveWrapperMap.put(Character.TYPE, Character.class);
- primitiveWrapperMap.put(Short.TYPE, Short.class);
- primitiveWrapperMap.put(Integer.TYPE, Integer.class);
- primitiveWrapperMap.put(Long.TYPE, Long.class);
- primitiveWrapperMap.put(Double.TYPE, Double.class);
- primitiveWrapperMap.put(Float.TYPE, Float.class);
- primitiveWrapperMap.put(Void.TYPE, Void.TYPE);
+ PRIMITIVE_WRAPPER_MAP.put(Boolean.TYPE, Boolean.class);
+ PRIMITIVE_WRAPPER_MAP.put(Byte.TYPE, Byte.class);
+ PRIMITIVE_WRAPPER_MAP.put(Character.TYPE, Character.class);
+ PRIMITIVE_WRAPPER_MAP.put(Short.TYPE, Short.class);
+ PRIMITIVE_WRAPPER_MAP.put(Integer.TYPE, Integer.class);
+ PRIMITIVE_WRAPPER_MAP.put(Long.TYPE, Long.class);
+ PRIMITIVE_WRAPPER_MAP.put(Double.TYPE, Double.class);
+ PRIMITIVE_WRAPPER_MAP.put(Float.TYPE, Float.class);
+ PRIMITIVE_WRAPPER_MAP.put(Void.TYPE, Void.TYPE);
}
/**
- * Maps wrapper {@code Class}es to their corresponding primitive types.
+ * Maps wrapper {@link Class}es to their corresponding primitive types.
*/
- private static final Map, Class> wrapperPrimitiveMap = new HashMap, Class>();
+ private static final Map, Class> WRAPPER_PRIMITIVE_MAP = new HashMap<>();
+
static {
- for (final Map.Entry, Class> entry : primitiveWrapperMap.entrySet()) {
- final Class primitiveClass = entry.getKey();
- final Class wrapperClass = entry.getValue();
+ PRIMITIVE_WRAPPER_MAP.forEach((primitiveClass, wrapperClass) -> {
if (!primitiveClass.equals(wrapperClass)) {
- wrapperPrimitiveMap.put(wrapperClass, primitiveClass);
+ WRAPPER_PRIMITIVE_MAP.put(wrapperClass, primitiveClass);
}
- }
+ });
}
/**
* Maps a primitive class name to its corresponding abbreviation used in array class names.
*/
- private static final Map abbreviationMap;
+ private static final Map ABBREVIATION_MAP;
/**
* Maps an abbreviation used in array class names to corresponding primitive class name.
*/
- private static final Map reverseAbbreviationMap;
+ private static final Map REVERSE_ABBREVIATION_MAP;
- /**
- * Feed abbreviation maps
- */
+ /** Feed abbreviation maps. */
static {
- final Map m = new HashMap();
- m.put("int", "I");
- m.put("boolean", "Z");
- m.put("float", "F");
- m.put("long", "J");
- m.put("short", "S");
- m.put("byte", "B");
- m.put("double", "D");
- m.put("char", "C");
- m.put("void", "V");
- final Map r = new HashMap();
- for (final Map.Entry e : m.entrySet()) {
- r.put(e.getValue(), e.getKey());
- }
- abbreviationMap = Collections.unmodifiableMap(m);
- reverseAbbreviationMap = Collections.unmodifiableMap(r);
- }
-
- /**
- * ClassUtils instances should NOT be constructed in standard programming.
- * Instead, the class should be used as
- * {@code ClassUtils.getShortClassName(cls)}.
- *
- * This constructor is public to permit tools that require a JavaBean
- * instance to operate.
- */
- public ClassUtils() {
- super();
+ final Map map = new HashMap<>();
+ map.put(Integer.TYPE.getName(), "I");
+ map.put(Boolean.TYPE.getName(), "Z");
+ map.put(Float.TYPE.getName(), "F");
+ map.put(Long.TYPE.getName(), "J");
+ map.put(Short.TYPE.getName(), "S");
+ map.put(Byte.TYPE.getName(), "B");
+ map.put(Double.TYPE.getName(), "D");
+ map.put(Character.TYPE.getName(), "C");
+ ABBREVIATION_MAP = Collections.unmodifiableMap(map);
+ REVERSE_ABBREVIATION_MAP = Collections.unmodifiableMap(map.entrySet().stream().collect(Collectors.toMap(Map.Entry::getValue, Map.Entry::getKey)));
}
- // Short class name
- // ----------------------------------------------------------------------
/**
- * Gets the class name minus the package name for an {@code Object}.
+ * Gets the class comparator, comparing by class name.
*
- * @param object the class to get the short name for, may be null
- * @param valueIfNull the value to return if null
- * @return the class name of the object without the package name, or the null value
+ * @return the class comparator.
+ * @since 3.13.0
*/
- public static String getShortClassName(final Object object, final String valueIfNull) {
- if (object == null) {
- return valueIfNull;
- }
- return getShortClassName(object.getClass());
+ public static Comparator> comparator() {
+ return COMPARATOR;
}
/**
- * Gets the class name minus the package name from a {@code Class}.
+ * Given a {@link List} of {@link Class} objects, this method converts them into class names.
*
- * Consider using the Java 5 API {@link Class#getSimpleName()} instead.
- * The one known difference is that this code will return {@code "Map.Entry"} while
- * the {@code java.lang.Class} variant will simply return {@code "Entry"}.
+ *
+ * A new {@link List} is returned. {@code null} objects will be copied into the returned list as {@code null}.
+ *
*
- * @param cls the class to get the short name for.
- * @return the class name without the package name or an empty string
+ * @param classes the classes to change.
+ * @return a {@link List} of class names corresponding to the Class objects, {@code null} if null input.
+ * @throws ClassCastException if {@code classes} contains a non-{@link Class} entry.
*/
- public static String getShortClassName(final Class cls) {
- if (cls == null) {
- return StringUtils.EMPTY;
- }
- return getShortClassName(cls.getName());
+ public static List convertClassesToClassNames(final List> classes) {
+ return classes == null ? null : classes.stream().map(e -> getName(e, null)).collect(Collectors.toList());
}
/**
- * Gets the class name minus the package name from a String.
+ * Given a {@link List} of class names, this method converts them into classes.
*
- * The string passed in is assumed to be a class name - it is not checked.
-
- * Note that this method differs from Class.getSimpleName() in that this will
- * return {@code "Map.Entry"} whilst the {@code java.lang.Class} variant will simply
- * return {@code "Entry"}.
+ *
+ * A new {@link List} is returned. If the class name cannot be found, {@code null} is stored in the {@link List}. If the
+ * class name in the {@link List} is {@code null}, {@code null} is stored in the output {@link List}.
+ *
*
- * @param className the className to get the short name for
- * @return the class name of the class without the package name or an empty string
+ * @param classNames the classNames to change.
+ * @return a {@link List} of Class objects corresponding to the class names, {@code null} if null input.
+ * @throws ClassCastException if classNames contains a non String entry.
*/
- public static String getShortClassName(String className) {
- if (StringUtils.isEmpty(className)) {
- return StringUtils.EMPTY;
+ public static List> convertClassNamesToClasses(final List classNames) {
+ if (classNames == null) {
+ return null;
}
-
- final StringBuilder arrayPrefix = new StringBuilder();
-
- // Handle array encoding
- if (className.startsWith("[")) {
- while (className.charAt(0) == '[') {
- className = className.substring(1);
- arrayPrefix.append("[]");
- }
- // Strip Object type encoding
- if (className.charAt(0) == 'L' && className.charAt(className.length() - 1) == ';') {
- className = className.substring(1, className.length() - 1);
- }
-
- if (reverseAbbreviationMap.containsKey(className)) {
- className = reverseAbbreviationMap.get(className);
+ final List> classes = new ArrayList<>(classNames.size());
+ classNames.forEach(className -> {
+ try {
+ classes.add(Class.forName(className));
+ } catch (final Exception ex) {
+ classes.add(null);
}
- }
-
- final int lastDotIdx = className.lastIndexOf(PACKAGE_SEPARATOR_CHAR);
- final int innerIdx = className.indexOf(
- INNER_CLASS_SEPARATOR_CHAR, lastDotIdx == -1 ? 0 : lastDotIdx + 1);
- String out = className.substring(lastDotIdx + 1);
- if (innerIdx != -1) {
- out = out.replace(INNER_CLASS_SEPARATOR_CHAR, PACKAGE_SEPARATOR_CHAR);
- }
- return out + arrayPrefix;
+ });
+ return classes;
}
/**
- *