T[] addFirst(final T[] array, final T element) {
return array == null ? add(array, element) : insert(0, array, element);
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param the type.
+ * @param source The source array.
+ * @param sourcePos starting position in the source array.
+ * @param destPos starting position in the destination data.
+ * @param length The number of array elements to be copied.
+ * @param allocator allocates the array to populate and return.
+ * @return dest
+ * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
+ * @throws ArrayStoreException if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
+ * mismatch.
+ * @throws NullPointerException if either {@code src} or {@code dest} is {@code null}.
+ * @since 3.15.0
*/
- public static boolean[] clone(final boolean[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ public static T arraycopy(final T source, final int sourcePos, final int destPos, final int length, final Function allocator) {
+ return arraycopy(source, sourcePos, allocator.apply(length), destPos, length);
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
+ * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
*
- *
This method returns {@code null} for a {@code null} input array.
- *
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param the type.
+ * @param source The source array.
+ * @param sourcePos starting position in the source array.
+ * @param destPos starting position in the destination data.
+ * @param length The number of array elements to be copied.
+ * @param allocator allocates the array to populate and return.
+ * @return dest
+ * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
+ * @throws ArrayStoreException if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
+ * mismatch.
+ * @throws NullPointerException if either {@code src} or {@code dest} is {@code null}.
+ * @since 3.15.0
*/
- public static byte[] clone(final byte[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ public static T arraycopy(final T source, final int sourcePos, final int destPos, final int length, final Supplier allocator) {
+ return arraycopy(source, sourcePos, allocator.get(), destPos, length);
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param the type.
+ * @param source The source array.
+ * @param sourcePos starting position in the source array.
+ * @param dest The destination array.
+ * @param destPos starting position in the destination data.
+ * @param length The number of array elements to be copied.
+ * @return dest
+ * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
+ * @throws ArrayStoreException if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
+ * mismatch.
+ * @throws NullPointerException if either {@code src} or {@code dest} is {@code null}.
+ * @since 3.15.0
*/
- public static char[] clone(final char[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ public static T arraycopy(final T source, final int sourcePos, final T dest, final int destPos, final int length) {
+ System.arraycopy(source, sourcePos, dest, destPos, length);
+ return dest;
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * This method returns {@code null} for a {@code null} input array.
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
+ */
+ public static boolean[] clone(final boolean[] array) {
+ return array != null ? array.clone() : null;
+ }
+
+ /**
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
*/
- public static double[] clone(final double[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ public static byte[] clone(final byte[] array) {
+ return array != null ? array.clone() : null;
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * This method returns {@code null} for a {@code null} input array.
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
+ */
+ public static char[] clone(final char[] array) {
+ return array != null ? array.clone() : null;
+ }
+
+ /**
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
*/
- public static float[] clone(final float[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ public static double[] clone(final double[] array) {
+ return array != null ? array.clone() : null;
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * This method returns {@code null} for a {@code null} input array.
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
+ */
+ public static float[] clone(final float[] array) {
+ return array != null ? array.clone() : null;
+ }
+
+ /**
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
*/
public static int[] clone(final int[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ return array != null ? array.clone() : null;
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
*/
public static long[] clone(final long[] array) {
- if (array == null) {
- return null;
- }
- return array.clone();
+ return array != null ? array.clone() : null;
}
/**
- * Clones an array returning a typecast result and handling
- * {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Clones an array or returns {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the array to clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
+ * @param array The array to clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
*/
public static short[] clone(final short[] array) {
- if (array == null) {
- return null;
+ return array != null ? array.clone() : null;
+ }
+
+ /**
+ * Shallow clones an array or returns {@code null}.
+ *
+ * The objects in the array are not cloned, thus there is no special handling for multi-dimensional arrays.
+ *
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
+ *
+ * @param the component type of the array.
+ * @param array The array to shallow clone, may be {@code null}.
+ * @return The cloned array, {@code null} if {@code null} input.
+ */
+ public static T[] clone(final T[] array) {
+ return array != null ? array.clone() : null;
+ }
+
+ /**
+ * Concatenates multiple boolean arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
+ *
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new boolean array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static boolean[] concat(final boolean[]... arrays) {
+ int totalLength = 0;
+ for (final boolean[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final boolean[] result = new boolean[totalLength];
+ int currentPos = 0;
+ for (final boolean[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
}
- return array.clone();
+ return result;
}
- // Clone
- //-----------------------------------------------------------------------
/**
- * Shallow clones an array returning a typecast result and handling
- * {@code null}.
+ * Concatenates multiple byte arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
*
- * The objects in the array are not cloned, thus there is no special
- * handling for multi-dimensional arrays.
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new byte array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static byte[] concat(final byte[]... arrays) {
+ int totalLength = 0;
+ for (final byte[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final byte[] result = new byte[totalLength];
+ int currentPos = 0;
+ for (final byte[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Concatenates multiple char arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
*
- * This method returns {@code null} for a {@code null} input array.
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new char array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static char[] concat(final char[]... arrays) {
+ int totalLength = 0;
+ for (final char[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final char[] result = new char[totalLength];
+ int currentPos = 0;
+ for (final char[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Concatenates multiple double arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
*
- * @param the component type of the array
- * @param array the array to shallow clone, may be {@code null}
- * @return the cloned array, {@code null} if {@code null} input
- */
- public static T[] clone(final T[] array) {
- if (array == null) {
- return null;
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new double array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static double[] concat(final double[]... arrays) {
+ int totalLength = 0;
+ for (final double[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final double[] result = new double[totalLength];
+ int currentPos = 0;
+ for (final double[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
}
- return array.clone();
+ return result;
}
/**
- * Checks if the value is in the given array.
+ * Concatenates multiple float arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
*
- * The method returns {@code false} if a {@code null} array is passed in.
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new float array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static float[] concat(final float[]... arrays) {
+ int totalLength = 0;
+ for (final float[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final float[] result = new float[totalLength];
+ int currentPos = 0;
+ for (final float[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Concatenates multiple int arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new int array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static int[] concat(final int[]... arrays) {
+ int totalLength = 0;
+ for (final int[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final int[] result = new int[totalLength];
+ int currentPos = 0;
+ for (final int[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Concatenates multiple long arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
+ *
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new long array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static long[] concat(final long[]... arrays) {
+ int totalLength = 0;
+ for (final long[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final long[] result = new long[totalLength];
+ int currentPos = 0;
+ for (final long[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Concatenates multiple short arrays into a single array.
+ *
+ * This method combines all input arrays in the order they are provided,
+ * creating a new array that contains all elements from the input arrays.
+ * The resulting array length is the sum of lengths of all non-null input arrays.
+ *
+ *
+ * @param arrays The arrays to concatenate. Can be empty, contain nulls,
+ * or be null itself (treated as empty varargs).
+ * @return A new short array containing all elements from the input arrays
+ * in the order they appear, or an empty array if no elements are present.
+ * @throws NullPointerException if the input array of arrays is null.
+ * @throws IllegalArgumentException if total arrays length exceed {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
+ * @since 3.21.0
+ */
+ public static short[] concat(final short[]... arrays) {
+ int totalLength = 0;
+ for (final short[] array : arrays) {
+ totalLength = addExact(totalLength, array);
+ }
+ final short[] result = new short[totalLength];
+ int currentPos = 0;
+ for (final short[] array : arrays) {
+ if (array != null && array.length > 0) {
+ System.arraycopy(array, 0, result, currentPos, array.length);
+ currentPos += array.length;
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final boolean[] array, final boolean valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(byte[])} and {@link Arrays#binarySearch(byte[], byte)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final byte[] array, final byte valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(char[])} and {@link Arrays#binarySearch(char[], char)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
* @since 2.1
*/
public static boolean contains(final char[] array, final char valueToFind) {
@@ -1542,100 +1918,173 @@ public static boolean contains(final char[] array, final char valueToFind) {
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(double[])} and {@link Arrays#binarySearch(double[], double)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final double[] array, final double valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if a value falling within the given tolerance is in the
+ * Checks if a value falling within the given tolerance is in the
* given array. If the array contains a value within the inclusive range
* defined by (value - tolerance) to (value + tolerance).
- *
- *
The method returns {@code false} if a {@code null} array
+ *
+ * The method returns {@code false} if a {@code null} array
* is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(double[])} and {@link Arrays#binarySearch(double[], double)}.
+ *
*
- * @param array the array to search
- * @param valueToFind the value to find
- * @param tolerance the array contains the tolerance of the search
- * @return true if value falling within tolerance is in array
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @param tolerance The array contains the tolerance of the search.
+ * @return true if value falling within tolerance is in array.
*/
public static boolean contains(final double[] array, final double valueToFind, final double tolerance) {
return indexOf(array, valueToFind, 0, tolerance) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(float[])} and {@link Arrays#binarySearch(float[], float)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final float[] array, final float valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(int[])} and {@link Arrays#binarySearch(int[], int)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final int[] array, final int valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(long[])} and {@link Arrays#binarySearch(long[], long)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final long[] array, final long valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the object is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the object is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(Object[], Comparator)} and {@link Arrays#binarySearch(Object[], Object)}.
+ *
*
- * @param array the array to search through
- * @param objectToFind the object to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final Object[] array, final Object objectToFind) {
return indexOf(array, objectToFind) != INDEX_NOT_FOUND;
}
/**
- * Checks if the value is in the given array.
- *
- *
The method returns {@code false} if a {@code null} array is passed in.
+ * Checks if the value is in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(short[])} and {@link Arrays#binarySearch(short[], short)}.
+ *
*
- * @param array the array to search through
- * @param valueToFind the value to find
- * @return {@code true} if the array contains the object
+ * @param array The array to search.
+ * @param valueToFind The value to find.
+ * @return {@code true} if the array contains the object.
*/
public static boolean contains(final short[] array, final short valueToFind) {
return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
}
+ /**
+ * Checks if any of the ints are in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(int[])} and {@link Arrays#binarySearch(int[], int)}.
+ *
+ *
+ * @param array The array to search.
+ * @param objectsToFind any of the ints to find.
+ * @return {@code true} if the array contains any of the ints.
+ * @since 3.18.0
+ */
+ public static boolean containsAny(final int[] array, final int... objectsToFind) {
+ return IntStreams.of(objectsToFind).anyMatch(e -> contains(array, e));
+ }
+
+ /**
+ * Checks if any of the objects are in the given array.
+ *
+ * The method returns {@code false} if a {@code null} array is passed in.
+ *
+ *
+ * If the {@code array} elements you are searching implement {@link Comparator}, consider whether it is worth using
+ * {@link Arrays#sort(Object[], Comparator)} and {@link Arrays#binarySearch(Object[], Object)}.
+ *
+ *
+ * @param array The array to search, may be {@code null}.
+ * @param objectsToFind any of the objects to find, may be {@code null}.
+ * @return {@code true} if the array contains any of the objects.
+ * @since 3.13.0
+ */
+ public static boolean containsAny(final Object[] array, final Object... objectsToFind) {
+ return Streams.of(objectsToFind).anyMatch(e -> contains(array, e));
+ }
+
/**
* Returns a copy of the given array of size 1 greater than the argument.
* The last value of the array is left to the default value.
@@ -1655,13 +2104,74 @@ private static Object copyArrayGrow1(final Object array, final Class newArray
return Array.newInstance(newArrayComponentType, 1);
}
- //-----------------------------------------------------------------------
/**
- * Returns the length of the specified array.
- * This method can deal with {@code Object} arrays and with primitive arrays.
+ * Gets the nTh element of an array or null if the index is out of bounds or the array is null.
+ *
+ * @param The type of array elements.
+ * @param array The array to index.
+ * @param index The index.
+ * @return The nTh element of an array or null if the index is out of bounds or the array is null.
+ * @since 3.11
+ */
+ public static T get(final T[] array, final int index) {
+ return get(array, index, null);
+ }
+
+ /**
+ * Gets the nTh element of an array or a default value if the index is out of bounds.
+ *
+ * @param The type of array elements.
+ * @param array The array to index.
+ * @param index The index.
+ * @param defaultValue The return value of the given index is out of bounds.
+ * @return The nTh element of an array or a default value if the index is out of bounds.
+ * @since 3.11
+ */
+ public static T get(final T[] array, final int index, final T defaultValue) {
+ return isArrayIndexValid(array, index) ? array[index] : defaultValue;
+ }
+
+ /**
+ * Gets an array's component type.
*
- * If the input array is {@code null}, {@code 0} is returned.
+ * @param The array type.
+ * @param array The array.
+ * @return The component type.
+ * @since 3.13.0
+ */
+ public static Class getComponentType(final T[] array) {
+ return ClassUtils.getComponentType(ObjectUtils.getClass(array));
+ }
+
+ /**
+ * Gets the number of dimensions of an array.
+ *
+ * The JVM specification limits the number of dimensions to 255.
+ *
*
+ * @param array The array, may be {@code null}.
+ * @return The number of dimensions, 0 if the input is null or not an array. The JVM specification limits the number of dimensions to 255.
+ * @since 3.21.0
+ * @see JVM specification Field Descriptors
+ */
+ public static int getDimensions(final Object array) {
+ int dimensions = 0;
+ if (array != null) {
+ Class arrayClass = array.getClass();
+ while (arrayClass.isArray()) {
+ dimensions++;
+ arrayClass = arrayClass.getComponentType();
+ }
+ }
+ return dimensions;
+ }
+
+ /**
+ * Gets the length of the specified array.
+ * This method handles {@link Object} arrays and primitive arrays.
+ *
+ * If the input array is {@code null}, {@code 0} is returned.
+ *
*
* ArrayUtils.getLength(null) = 0
* ArrayUtils.getLength([]) = 0
@@ -1671,39 +2181,43 @@ private static Object copyArrayGrow1(final Object array, final Class newArray
* ArrayUtils.getLength(["a", "b", "c"]) = 3
*
*
- * @param array the array to retrieve the length from, may be null
- * @return The length of the array, or {@code 0} if the array is {@code null}
+ * @param array The array to retrieve the length from, may be {@code null}.
+ * @return The length of the array, or {@code 0} if the array is {@code null}.
* @throws IllegalArgumentException if the object argument is not an array.
* @since 2.1
*/
public static int getLength(final Object array) {
- if (array == null) {
- return 0;
- }
- return Array.getLength(array);
+ return array != null ? Array.getLength(array) : 0;
}
/**
- * Get a hash code for an array handling multi-dimensional arrays correctly.
- *
- *
Multi-dimensional primitive arrays are also handled correctly by this method.
+ * Gets a hash code for an array handling multidimensional arrays.
+ *
+ * Multi-dimensional primitive arrays are also handled by this method.
+ *
*
- * @param array the array to get a hash code for, {@code null} returns zero
- * @return a hash code for the array
+ * @param array The array to get a hash code for, may be {@code null}.
+ * @return A hash code for the array.
+ * @see HashCodeBuilder
*/
public static int hashCode(final Object array) {
return new HashCodeBuilder().append(array).toHashCode();
}
+ static void increment(final Map occurrences, final K boxed) {
+ occurrences.computeIfAbsent(boxed, k -> new MutableInt()).increment();
+ }
+
/**
* Finds the indices of the given value in the array.
+ *
+ * This method returns an empty BitSet for a {@code null} input array.
+ *
*
- * This method returns an empty BitSet for a {@code null} input array.
- *
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final boolean[] array, final boolean valueToFind) {
@@ -1712,50 +2226,44 @@ public static BitSet indexesOf(final boolean[] array, final boolean valueToFind)
/**
* Finds the indices of the given value in the array starting at the given index.
+ *
+ * This method returns an empty BitSet for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return an empty BitSet ({@code -1}).
+ *
*
- * This method returns an empty BitSet for a {@code null} input array.
- *
- * A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return an empty BitSet ({@code -1}).
- *
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null}
- * array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array, an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final boolean[] array, final boolean valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
/**
* Finds the indices of the given value in the array.
*
- * This method returns an empty BitSet for a {@code null} input array.
+ *
+ * This method returns an empty BitSet for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array, an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final byte[] array, final byte valueToFind) {
@@ -1770,31 +2278,25 @@ public static BitSet indexesOf(final byte[] array, final byte valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final byte[] array, final byte valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -1803,10 +2305,10 @@ public static BitSet indexesOf(final byte[] array, final byte valueToFind, int s
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final char[] array, final char valueToFind) {
@@ -1821,31 +2323,25 @@ public static BitSet indexesOf(final char[] array, final char valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final char[] array, final char valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -1854,10 +2350,10 @@ public static BitSet indexesOf(final char[] array, final char valueToFind, int s
*
* This method returns empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final double[] array, final double valueToFind) {
@@ -1874,11 +2370,11 @@ public static BitSet indexesOf(final double[] array, final double valueToFind) {
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param tolerance tolerance of the search
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param tolerance tolerance of the search.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final double[] array, final double valueToFind, final double tolerance) {
@@ -1893,31 +2389,25 @@ public static BitSet indexesOf(final double[] array, final double valueToFind, f
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final double[] array, final double valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -1934,32 +2424,26 @@ public static BitSet indexesOf(final double[] array, final double valueToFind, i
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @param tolerance tolerance of the search
- * @return a BitSet of the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @param tolerance tolerance of the search.
+ * @return A BitSet of the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final double[] array, final double valueToFind, int startIndex, final double tolerance) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex, tolerance);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex, tolerance);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -1968,10 +2452,10 @@ public static BitSet indexesOf(final double[] array, final double valueToFind, i
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final float[] array, final float valueToFind) {
@@ -1986,31 +2470,25 @@ public static BitSet indexesOf(final float[] array, final float valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final float[] array, final float valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -2019,10 +2497,10 @@ public static BitSet indexesOf(final float[] array, final float valueToFind, int
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final int[] array, final int valueToFind) {
@@ -2037,31 +2515,25 @@ public static BitSet indexesOf(final int[] array, final int valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final int[] array, final int valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -2070,10 +2542,10 @@ public static BitSet indexesOf(final int[] array, final int valueToFind, int sta
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final long[] array, final long valueToFind) {
@@ -2088,31 +2560,25 @@ public static BitSet indexesOf(final long[] array, final long valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final long[] array, final long valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -2121,10 +2587,10 @@ public static BitSet indexesOf(final long[] array, final long valueToFind, int s
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @return a BitSet of all the indices of the object within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @return A BitSet of all the indices of the object within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final Object[] array, final Object objectToFind) {
@@ -2139,31 +2605,25 @@ public static BitSet indexesOf(final Object[] array, final Object objectToFind)
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the object within the array starting at the index,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the object within the array starting at the index,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final Object[] array, final Object objectToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, objectToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, objectToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
@@ -2172,10 +2632,10 @@ public static BitSet indexesOf(final Object[] array, final Object objectToFind,
*
* This method returns an empty BitSet for a {@code null} input array.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final short[] array, final short valueToFind) {
@@ -2190,73 +2650,61 @@ public static BitSet indexesOf(final short[] array, final short valueToFind) {
* A negative startIndex is treated as zero. A startIndex larger than the array
* length will return an empty BitSet.
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return a BitSet of all the indices of the value within the array,
- * an empty BitSet if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return A BitSet of all the indices of the value within the array,
+ * an empty BitSet if not found or {@code null} array input.
* @since 3.10
*/
public static BitSet indexesOf(final short[] array, final short valueToFind, int startIndex) {
- BitSet bitSet = new BitSet();
-
- if (array == null) {
- return bitSet;
- }
-
- while (startIndex < array.length) {
- startIndex = indexOf(array, valueToFind, startIndex);
-
- if (startIndex == INDEX_NOT_FOUND) {
- break;
+ final BitSet bitSet = new BitSet();
+ if (array != null) {
+ while (startIndex < array.length) {
+ startIndex = indexOf(array, valueToFind, startIndex);
+ if (startIndex == INDEX_NOT_FOUND) {
+ break;
+ }
+ bitSet.set(startIndex);
+ ++startIndex;
}
-
- bitSet.set(startIndex);
- ++startIndex;
}
-
return bitSet;
}
- // boolean IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final boolean[] array, final boolean valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null}
- * array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final boolean[] array, final boolean valueToFind, int startIndex) {
+ public static int indexOf(final boolean[] array, final boolean valueToFind, final int startIndex) {
if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2264,44 +2712,39 @@ public static int indexOf(final boolean[] array, final boolean valueToFind, int
return INDEX_NOT_FOUND;
}
- // byte IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final byte[] array, final byte valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final byte[] array, final byte valueToFind, int startIndex) {
- if (array == null) {
+ public static int indexOf(final byte[] array, final byte valueToFind, final int startIndex) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2309,17 +2752,15 @@ public static int indexOf(final byte[] array, final byte valueToFind, int startI
return INDEX_NOT_FOUND;
}
- // char IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
* @since 2.1
*/
public static int indexOf(final char[] array, final char valueToFind) {
@@ -2327,28 +2768,25 @@ public static int indexOf(final char[] array, final char valueToFind) {
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
* @since 2.1
*/
- public static int indexOf(final char[] array, final char valueToFind, int startIndex) {
- if (array == null) {
+ public static int indexOf(final char[] array, final char valueToFind, final int startIndex) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2356,61 +2794,58 @@ public static int indexOf(final char[] array, final char valueToFind, int startI
return INDEX_NOT_FOUND;
}
- // double IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final double[] array, final double valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value within a given tolerance in the array.
- * This method will return the index of the first value which falls between the region
- * defined by valueToFind - tolerance and valueToFind + tolerance.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value within a given tolerance in the array. This method will return the index of the first value which falls between the
+ * region defined by valueToFind - tolerance and valueToFind + tolerance.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param tolerance tolerance of the search
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param tolerance tolerance of the search.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final double[] array, final double valueToFind, final double tolerance) {
return indexOf(array, valueToFind, 0, tolerance);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final double[] array, final double valueToFind, int startIndex) {
+ public static int indexOf(final double[] array, final double valueToFind, final int startIndex) {
+ if (Double.isNaN(valueToFind)) {
+ return indexOfNaN(array, startIndex);
+ }
if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2419,32 +2854,31 @@ public static int indexOf(final double[] array, final double valueToFind, int st
}
/**
- * Finds the index of the given value in the array starting at the given index.
- * This method will return the index of the first value which falls between the region
- * defined by valueToFind - tolerance and valueToFind + tolerance.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index. This method will return the index of the first value which falls between the
+ * region defined by valueToFind - tolerance and valueToFind + tolerance.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @param tolerance tolerance of the search
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @param tolerance tolerance of the search.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final double[] array, final double valueToFind, int startIndex, final double tolerance) {
+ public static int indexOf(final double[] array, final double valueToFind, final int startIndex, final double tolerance) {
+ if (Double.isNaN(valueToFind)) {
+ return indexOfNaN(array, startIndex);
+ }
if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
final double min = valueToFind - tolerance;
final double max = valueToFind + tolerance;
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (array[i] >= min && array[i] <= max) {
return i;
}
@@ -2452,89 +2886,81 @@ public static int indexOf(final double[] array, final double valueToFind, int st
return INDEX_NOT_FOUND;
}
- // float IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final float[] array, final float valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final float[] array, final float valueToFind, int startIndex) {
+ public static int indexOf(final float[] array, final float valueToFind, final int startIndex) {
if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
- if (valueToFind == array[i]) {
+ final boolean searchNaN = Float.isNaN(valueToFind);
+ for (int i = max0(startIndex); i < array.length; i++) {
+ final float element = array[i];
+ if (valueToFind == element || searchNaN && Float.isNaN(element)) {
return i;
}
}
return INDEX_NOT_FOUND;
}
- // int IndexOf
-//-----------------------------------------------------------------------
-/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
- */
-public static int indexOf(final int[] array, final int valueToFind) {
- return indexOf(array, valueToFind, 0);
-}
-
/**
- *
Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
+ */
+ public static int indexOf(final int[] array, final int valueToFind) {
+ return indexOf(array, valueToFind, 0);
+ }
+
+ /**
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final int[] array, final int valueToFind, int startIndex) {
- if (array == null) {
+ public static int indexOf(final int[] array, final int valueToFind, final int startIndex) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2542,44 +2968,39 @@ public static int indexOf(final int[] array, final int valueToFind, int startInd
return INDEX_NOT_FOUND;
}
- // long IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final long[] array, final long valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final long[] array, final long valueToFind, int startIndex) {
- if (array == null) {
+ public static int indexOf(final long[] array, final long valueToFind, final int startIndex) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2587,43 +3008,39 @@ public static int indexOf(final long[] array, final long valueToFind, int startI
return INDEX_NOT_FOUND;
}
- // Object IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given object in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given object in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @return the index of the object within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @return The index of the object within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final Object[] array, final Object objectToFind) {
return indexOf(array, objectToFind, 0);
}
/**
- * Finds the index of the given object in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given object in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @param startIndex the index to start searching at
- * @return the index of the object within the array starting at the index,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @param startIndex The index to start searching.
+ * @return The index of the object within the array starting at the index, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final Object[] array, final Object objectToFind, int startIndex) {
- if (array == null) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
+ startIndex = max0(startIndex);
if (objectToFind == null) {
for (int i = startIndex; i < array.length; i++) {
if (array[i] == null) {
@@ -2640,44 +3057,39 @@ public static int indexOf(final Object[] array, final Object objectToFind, int s
return INDEX_NOT_FOUND;
}
- // short IndexOf
- //-----------------------------------------------------------------------
/**
- * Finds the index of the given value in the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the index of the given value in the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}
+ * @param valueToFind The value to find.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int indexOf(final short[] array, final short valueToFind) {
return indexOf(array, valueToFind, 0);
}
/**
- * Finds the index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex is treated as zero. A startIndex larger than the array
- * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ * Finds the index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex is treated as zero. A startIndex larger than the array length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the index to start searching at
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The index to start searching.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
- public static int indexOf(final short[] array, final short valueToFind, int startIndex) {
- if (array == null) {
+ public static int indexOf(final short[] array, final short valueToFind, final int startIndex) {
+ if (isEmpty(array)) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- startIndex = 0;
- }
- for (int i = startIndex; i < array.length; i++) {
+ for (int i = max0(startIndex); i < array.length; i++) {
if (valueToFind == array[i]) {
return i;
}
@@ -2686,9 +3098,29 @@ public static int indexOf(final short[] array, final short valueToFind, int star
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Finds the index of the NaN value in a double array.
+ * @param array The array to search for NaN, may be {@code null}.
+ * @param startIndex The index to start searching.
+ * @return The index of the NaN value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
+ */
+ private static int indexOfNaN(final double[] array, final int startIndex) {
+ if (isEmpty(array)) {
+ return INDEX_NOT_FOUND;
+ }
+ for (int i = max0(startIndex); i < array.length; i++) {
+ if (Double.isNaN(array[i])) {
+ return i;
+ }
+ }
+ return INDEX_NOT_FOUND;
+ }
+
+ /**
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2696,27 +3128,25 @@ public static int indexOf(final short[] array, final short valueToFind, int star
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static boolean[] insert(final int index, final boolean[] array, final boolean... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final boolean[] result = new boolean[array.length + values.length];
-
+ final boolean[] result = new boolean[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2728,9 +3158,11 @@ public static boolean[] insert(final int index, final boolean[] array, final boo
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2738,27 +3170,25 @@ public static boolean[] insert(final int index, final boolean[] array, final boo
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static byte[] insert(final int index, final byte[] array, final byte... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final byte[] result = new byte[array.length + values.length];
-
+ final byte[] result = new byte[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2770,9 +3200,11 @@ public static byte[] insert(final int index, final byte[] array, final byte... v
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2780,27 +3212,25 @@ public static byte[] insert(final int index, final byte[] array, final byte... v
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static char[] insert(final int index, final char[] array, final char... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final char[] result = new char[array.length + values.length];
-
+ final char[] result = new char[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2812,9 +3242,11 @@ public static char[] insert(final int index, final char[] array, final char... v
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2822,27 +3254,25 @@ public static char[] insert(final int index, final char[] array, final char... v
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static double[] insert(final int index, final double[] array, final double... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final double[] result = new double[array.length + values.length];
-
+ final double[] result = new double[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2854,9 +3284,11 @@ public static double[] insert(final int index, final double[] array, final doubl
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2864,27 +3296,25 @@ public static double[] insert(final int index, final double[] array, final doubl
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static float[] insert(final int index, final float[] array, final float... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final float[] result = new float[array.length + values.length];
-
+ final float[] result = new float[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2896,9 +3326,11 @@ public static float[] insert(final int index, final float[] array, final float..
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2906,27 +3338,25 @@ public static float[] insert(final int index, final float[] array, final float..
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static int[] insert(final int index, final int[] array, final int... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final int[] result = new int[array.length + values.length];
-
+ final int[] result = new int[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2938,9 +3368,11 @@ public static int[] insert(final int index, final int[] array, final int... valu
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2948,27 +3380,25 @@ public static int[] insert(final int index, final int[] array, final int... valu
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static long[] insert(final int index, final long[] array, final long... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final long[] result = new long[array.length + values.length];
-
+ final long[] result = new long[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -2980,9 +3410,11 @@ public static long[] insert(final int index, final long[] array, final long... v
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -2990,27 +3422,25 @@ public static long[] insert(final int index, final long[] array, final long... v
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
public static short[] insert(final int index, final short[] array, final short... values) {
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final short[] result = new short[array.length + values.length];
-
+ final short[] result = new short[addExact(array.length, values)];
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -3022,9 +3452,11 @@ public static short[] insert(final int index, final short[] array, final short..
}
/**
- * Inserts elements into an array at the given index (starting from zero).
+ * Inserts elements into an array at the given index (starting from zero).
*
- * When an array is returned, it is always a new array.
+ *
+ * When an array is returned, it is always a new array.
+ *
*
*
* ArrayUtils.insert(index, null, null) = null
@@ -3032,13 +3464,13 @@ public static short[] insert(final int index, final short[] array, final short..
* ArrayUtils.insert(index, null, values) = null
*
*
- * @param The type of elements in {@code array} and {@code values}
- * @param index the position within {@code array} to insert the new values
- * @param array the array to insert the values into, may be {@code null}
- * @param values the new values to insert, may be {@code null}
- * @return The new array.
- * @throws IndexOutOfBoundsException if {@code array} is provided
- * and either {@code index < 0} or {@code index > array.length}
+ * @param The type of elements in {@code array} and {@code values}.
+ * @param index The position within {@code array} to insert the new values.
+ * @param array The array to insert the values into, may be {@code null}.
+ * @param values The new values to insert, may be {@code null}.
+ * @return The new array or {@code null} if the given array is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code array} is provided and either {@code index < 0} or {@code index > array.length}.
+ * @throws IllegalArgumentException if the total array length exceeds {@link ArrayUtils#SAFE_MAX_ARRAY_LENGTH}.
* @since 3.6
*/
@SafeVarargs
@@ -3050,22 +3482,18 @@ public static T[] insert(final int index, final T[] array, final T... values
* array to the caller. We also avoid relying on the type of the vararg
* array, by inspecting the component type of 'array'.
*/
-
if (array == null) {
return null;
}
- if (ArrayUtils.isEmpty(values)) {
+ if (isEmpty(values)) {
return clone(array);
}
if (index < 0 || index > array.length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
}
-
- final Class type = array.getClass().getComponentType();
- @SuppressWarnings("unchecked") // OK, because array and values are of type T
- final
- T[] result = (T[]) Array.newInstance(type, array.length + values.length);
-
+ final Class type = getComponentType(array);
+ final int length = addExact(array.length, values);
+ final T[] result = newInstance(type, length);
System.arraycopy(values, 0, result, index, values.length);
if (index > 0) {
System.arraycopy(array, 0, result, 0, index);
@@ -3077,136 +3505,144 @@ public static T[] insert(final int index, final T[] array, final T... values
}
/**
- * Returns whether a given array can safely be accessed at the given index.
- * @param the component type of the array
- * @param array the array to inspect, may be null
- * @param index the index of the array to be inspected
- * @return Whether the given index is safely-accessible in the given array
- * @since 3.8
+ * Checks if an array is empty or {@code null}.
+ *
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
*/
- public static boolean isArrayIndexValid(T[] array, int index) {
- if (getLength(array) == 0 || array.length <= index) {
- return false;
- }
+ private static boolean isArrayEmpty(final Object array) {
+ return getLength(array) == 0;
+ }
- return index >= 0;
+ /**
+ * Tests whether a given array can safely be accessed at the given index.
+ *
+ *
+ * ArrayUtils.isArrayIndexValid(null, 0) = false
+ * ArrayUtils.isArrayIndexValid([], 0) = false
+ * ArrayUtils.isArrayIndexValid(["a"], 0) = true
+ *
+ *
+ * @param The component type of the array.
+ * @param array The array to inspect, may be {@code null}.
+ * @param index The index of the array to be inspected.
+ * @return Whether the given index is safely-accessible in the given array.
+ * @since 3.8
+ */
+ public static boolean isArrayIndexValid(final T[] array, final int index) {
+ return index >= 0 && getLength(array) > index;
}
/**
- * Checks if an array of primitive booleans is empty or {@code null}.
+ * Tests whether an array of primitive booleans is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final boolean[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
- // IndexOf search
- // ----------------------------------------------------------------------
-
/**
- *
Checks if an array of primitive bytes is empty or {@code null}.
+ * Tests whether an array of primitive bytes is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final byte[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
/**
- *
Checks if an array of primitive chars is empty or {@code null}.
+ * Tests whether an array of primitive chars is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final char[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
/**
- *
Checks if an array of primitive doubles is empty or {@code null}.
+ * Tests whether an array of primitive doubles is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final double[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
/**
- *
Checks if an array of primitive floats is empty or {@code null}.
+ * Tests whether an array of primitive floats is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final float[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
-
-
/**
- *
Checks if an array of primitive ints is empty or {@code null}.
+ * Tests whether an array of primitive ints is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final int[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
/**
- *
Checks if an array of primitive longs is empty or {@code null}.
+ * Tests whether an array of primitive longs is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final long[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
- // ----------------------------------------------------------------------
/**
- *
Checks if an array of Objects is empty or {@code null}.
+ * Tests whether an array of Objects is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final Object[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
/**
- *
Checks if an array of primitive shorts is empty or {@code null}.
+ * Tests whether an array of primitive shorts is empty or {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is empty or {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is empty or {@code null}.
* @since 2.1
*/
public static boolean isEmpty(final short[] array) {
- return getLength(array) == 0;
+ return isArrayEmpty(array);
}
- /**
- *
Compares two arrays, using equals(), handling multi-dimensional arrays
+ /**
+ * Tests whether two arrays have equal content, using equals(), handling multidimensional arrays
* correctly.
+ *
+ * Multi-dimensional primitive arrays are also handled correctly by this method.
+ *
*
- * Multi-dimensional primitive arrays are also handled correctly by this method.
- *
- * @param array1 the left hand array to compare, may be {@code null}
- * @param array2 the right hand array to compare, may be {@code null}
- * @return {@code true} if the arrays are equal
- * @deprecated this method has been replaced by {@code java.util.Objects.deepEquals(Object, Object)} and will be
+ * @param array1 The left-hand side array to compare, may be {@code null}.
+ * @param array2 The right-hand side array to compare, may be {@code null}.
+ * @return {@code true} if the arrays are equal.
+ * @deprecated Replaced by {@code java.util.Objects.deepEquals(Object, Object)} and will be
* removed from future releases.
*/
@Deprecated
@@ -3215,10 +3651,10 @@ public static boolean isEquals(final Object array1, final Object array2) {
}
/**
- *
Checks if an array of primitive booleans is not empty and not {@code null}.
+ * Tests whether an array of primitive booleans is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final boolean[] array) {
@@ -3226,10 +3662,10 @@ public static boolean isNotEmpty(final boolean[] array) {
}
/**
- *
Checks if an array of primitive bytes is not empty and not {@code null}.
+ * Tests whether an array of primitive bytes is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final byte[] array) {
@@ -3237,10 +3673,10 @@ public static boolean isNotEmpty(final byte[] array) {
}
/**
- *
Checks if an array of primitive chars is not empty and not {@code null}.
+ * Tests whether an array of primitive chars is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final char[] array) {
@@ -3248,10 +3684,10 @@ public static boolean isNotEmpty(final char[] array) {
}
/**
- *
Checks if an array of primitive doubles is not empty and not {@code null}.
+ * Tests whether an array of primitive doubles is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final double[] array) {
@@ -3259,10 +3695,10 @@ public static boolean isNotEmpty(final double[] array) {
}
/**
- *
Checks if an array of primitive floats is not empty and not {@code null}.
+ * Tests whether an array of primitive floats is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final float[] array) {
@@ -3270,10 +3706,10 @@ public static boolean isNotEmpty(final float[] array) {
}
/**
- *
Checks if an array of primitive ints is not empty and not {@code null}.
+ * Tests whether an array of primitive ints is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final int[] array) {
@@ -3281,10 +3717,10 @@ public static boolean isNotEmpty(final int[] array) {
}
/**
- *
Checks if an array of primitive longs is not empty and not {@code null}.
+ * Tests whether an array of primitive longs is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final long[] array) {
@@ -3292,23 +3728,22 @@ public static boolean isNotEmpty(final long[] array) {
}
/**
- *
Checks if an array of primitive shorts is not empty and not {@code null}.
+ * Tests whether an array of primitive shorts is not empty and not {@code null}.
*
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final short[] array) {
return !isEmpty(array);
}
- // ----------------------------------------------------------------------
/**
- *
Checks if an array of Objects is not empty and not {@code null}.
+ * Tests whether an array of Objects is not empty and not {@code null}.
*
- * @param the component type of the array
- * @param array the array to test
- * @return {@code true} if the array is not empty and not {@code null}
+ * @param The component type of the array
+ * @param array The array to test.
+ * @return {@code true} if the array is not empty and not {@code null}.
* @since 2.5
*/
public static boolean isNotEmpty(final T[] array) {
@@ -3316,134 +3751,129 @@ public static boolean isNotEmpty(final T[] array) {
}
/**
- * Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
- *
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
- */
- public static boolean isSameLength(final boolean[] array1, final boolean[] array2) {
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
+ *
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
+ */
+ public static boolean isSameLength(final boolean[] array1, final boolean[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final byte[] array1, final byte[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final char[] array1, final char[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final double[] array1, final double[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final float[] array1, final float[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final int[] array1, final int[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final long[] array1, final long[] array2) {
return getLength(array1) == getLength(array2);
}
- // Is same length
- //-----------------------------------------------------------------------
/**
- *
Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
+ *
+ * Any multi-dimensional aspects of the arrays are ignored.
+ *
*
- * Any multi-dimensional aspects of the arrays are ignored.
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
+ * @since 3.11
+ */
+ public static boolean isSameLength(final Object array1, final Object array2) {
+ return getLength(array1) == getLength(array2);
+ }
+
+ /**
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
+ *
+ * Any multi-dimensional aspects of the arrays are ignored.
+ *
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final Object[] array1, final Object[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- * Checks whether two arrays are the same length, treating
- * {@code null} arrays as length {@code 0}.
+ * Tests whether two arrays are the same length, treating {@code null} arrays as length {@code 0}.
*
- * @param array1 the first array, may be {@code null}
- * @param array2 the second array, may be {@code null}
- * @return {@code true} if length of arrays matches, treating
- * {@code null} as an empty array
+ * @param array1 The first array, may be {@code null}.
+ * @param array2 The second array, may be {@code null}.
+ * @return {@code true} if length of arrays matches, treating {@code null} as an empty array.
*/
public static boolean isSameLength(final short[] array1, final short[] array2) {
return getLength(array1) == getLength(array2);
}
/**
- *
Checks whether two arrays are the same type taking into account
- * multi-dimensional arrays.
+ * Tests whether two arrays are the same type taking into account multidimensional arrays.
*
- * @param array1 the first array, must not be {@code null}
- * @param array2 the second array, must not be {@code null}
- * @return {@code true} if type of arrays matches
- * @throws IllegalArgumentException if either array is {@code null}
+ * @param array1 The first array, must not be {@code null}.
+ * @param array2 The second array, must not be {@code null}.
+ * @return {@code true} if type of arrays matches.
+ * @throws IllegalArgumentException if either array is {@code null}.
*/
public static boolean isSameType(final Object array1, final Object array2) {
if (array1 == null || array2 == null) {
@@ -3453,18 +3883,16 @@ public static boolean isSameType(final Object array1, final Object array2) {
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering
- * ({@code false} before {@code true}).
+ * Tests whether the provided array is sorted according to natural ordering ({@code false} before {@code true}).
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final boolean[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
boolean previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
@@ -3472,49 +3900,45 @@ public static boolean isSorted(final boolean[] array) {
if (BooleanUtils.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final byte[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
byte previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
final byte current = array[i];
- if (NumberUtils.compare(previous, current) > 0) {
+ if (Byte.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final char[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
char previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
@@ -3522,24 +3946,22 @@ public static boolean isSorted(final char[] array) {
if (CharUtils.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final double[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
double previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
@@ -3547,24 +3969,22 @@ public static boolean isSorted(final double[] array) {
if (Double.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final float[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
float previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
@@ -3572,118 +3992,108 @@ public static boolean isSorted(final float[] array) {
if (Float.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final int[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
int previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
final int current = array[i];
- if (NumberUtils.compare(previous, current) > 0) {
+ if (Integer.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final long[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
long previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
final long current = array[i];
- if (NumberUtils.compare(previous, current) > 0) {
+ if (Long.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to natural ordering.
+ * Tests whether the provided array is sorted according to natural ordering.
*
- * @param array the array to check
- * @return whether the array is sorted according to natural ordering
+ * @param array The array to check.
+ * @return whether the array is sorted according to natural ordering.
* @since 3.4
*/
public static boolean isSorted(final short[] array) {
- if (array == null || array.length < 2) {
+ if (getLength(array) < 2) {
return true;
}
-
short previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
final short current = array[i];
- if (NumberUtils.compare(previous, current) > 0) {
+ if (Short.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- *
This method checks whether the provided array is sorted according to the class's
+ * Tests whether the provided array is sorted according to the class's
* {@code compareTo} method.
*
- * @param array the array to check
- * @param the datatype of the array to check, it must implement {@code Comparable}
- * @return whether the array is sorted
+ * @param array The array to check.
+ * @param The datatype of the array to check, it must implement {@link Comparable}.
+ * @return whether the array is sorted.
* @since 3.4
*/
public static > boolean isSorted(final T[] array) {
- return isSorted(array, (o1, o2) -> o1.compareTo(o2));
+ return isSorted(array, Comparable::compareTo);
}
/**
- * This method checks whether the provided array is sorted according to the provided {@code Comparator}.
+ * Tests whether the provided array is sorted according to the provided {@link Comparator}.
*
- * @param array the array to check
- * @param comparator the {@code Comparator} to compare over
- * @param the datatype of the array
- * @return whether the array is sorted
+ * @param array The array to check.
+ * @param comparator The {@link Comparator} to compare over.
+ * @param The datatype of the array.
+ * @return whether the array is sorted.
+ * @throws NullPointerException if {@code comparator} is {@code null}.
* @since 3.4
*/
public static boolean isSorted(final T[] array, final Comparator comparator) {
- if (comparator == null) {
- throw new IllegalArgumentException("Comparator should not be null.");
- }
-
- if (array == null || array.length < 2) {
+ Objects.requireNonNull(comparator, "comparator");
+ if (getLength(array) < 2) {
return true;
}
-
T previous = array[0];
final int n = array.length;
for (int i = 1; i < n; i++) {
@@ -3691,48 +4101,44 @@ public static boolean isSorted(final T[] array, final Comparator comparat
if (comparator.compare(previous, current) > 0) {
return false;
}
-
previous = current;
}
return true;
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) if
- * {@code null} array input.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) if {@code null} array input.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final boolean[] array, final boolean valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than
- * the array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final boolean[] array, final boolean valueToFind, int startIndex) {
- if (isEmpty(array)) {
+ if (isEmpty(array) || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -3744,40 +4150,38 @@ public static int lastIndexOf(final boolean[] array, final boolean valueToFind,
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final byte[] array, final byte valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final byte[] array, final byte valueToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -3789,14 +4193,14 @@ public static int lastIndexOf(final byte[] array, final byte valueToFind, int st
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
* @since 2.1
*/
public static int lastIndexOf(final char[] array, final char valueToFind) {
@@ -3804,27 +4208,25 @@ public static int lastIndexOf(final char[] array, final char valueToFind) {
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
* @since 2.1
*/
public static int lastIndexOf(final char[] array, final char valueToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -3836,57 +4238,57 @@ public static int lastIndexOf(final char[] array, final char valueToFind, int st
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final double[] array, final double valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value within a given tolerance in the array.
- * This method will return the index of the last value which falls between the region
- * defined by valueToFind - tolerance and valueToFind + tolerance.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within a given tolerance in the array. This method will return the index of the last value which falls between
+ * the region defined by valueToFind - tolerance and valueToFind + tolerance.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to search through for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param tolerance tolerance of the search
- * @return the index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to search for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param tolerance tolerance of the search.
+ * @return The index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final double[] array, final double valueToFind, final double tolerance) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE, tolerance);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final double[] array, final double valueToFind, int startIndex) {
- if (isEmpty(array)) {
- return INDEX_NOT_FOUND;
+ if (Double.isNaN(valueToFind)) {
+ return lastIndexOfNaN(array, startIndex);
}
- if (startIndex < 0) {
+ if (isEmpty(array) || startIndex < 0) {
return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ }
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -3898,29 +4300,29 @@ public static int lastIndexOf(final double[] array, final double valueToFind, in
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- * This method will return the index of the last value which falls between the region
- * defined by valueToFind - tolerance and valueToFind + tolerance.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index. This method will return the index of the last value which falls between
+ * the region defined by valueToFind - tolerance and valueToFind + tolerance.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @param tolerance search for value within plus/minus this amount
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @param tolerance search for value within plus/minus this amount.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final double[] array, final double valueToFind, int startIndex, final double tolerance) {
- if (isEmpty(array)) {
- return INDEX_NOT_FOUND;
+ if (Double.isNaN(valueToFind)) {
+ return lastIndexOfNaN(array, startIndex);
}
- if (startIndex < 0) {
+ if (isEmpty(array) || startIndex < 0) {
return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ }
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
final double min = valueToFind - tolerance;
@@ -3933,46 +4335,45 @@ public static int lastIndexOf(final double[] array, final double valueToFind, in
return INDEX_NOT_FOUND;
}
-
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final float[] array, final float valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final float[] array, final float valueToFind, int startIndex) {
- if (isEmpty(array)) {
+ if (isEmpty(array) || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
+ final boolean searchNaN = Float.isNaN(valueToFind);
for (int i = startIndex; i >= 0; i--) {
- if (valueToFind == array[i]) {
+ final float element = array[i];
+ if (valueToFind == element || searchNaN && Float.isNaN(element)) {
return i;
}
}
@@ -3980,40 +4381,38 @@ public static int lastIndexOf(final float[] array, final float valueToFind, int
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final int[] array, final int valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final int[] array, final int valueToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -4025,40 +4424,38 @@ public static int lastIndexOf(final int[] array, final int valueToFind, int star
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final long[] array, final long valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final long[] array, final long valueToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -4070,40 +4467,38 @@ public static int lastIndexOf(final long[] array, final long valueToFind, int st
}
/**
- * Finds the last index of the given object within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given object within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @return the last index of the object within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @return The last index of the object within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final Object[] array, final Object objectToFind) {
return lastIndexOf(array, objectToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given object in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than
- * the array length will search from the end of the array.
+ * Finds the last index of the given object in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param objectToFind the object to find, may be {@code null}
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the object within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param objectToFind The object to find, may be {@code null}.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the object within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final Object[] array, final Object objectToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
if (objectToFind == null) {
@@ -4123,40 +4518,38 @@ public static int lastIndexOf(final Object[] array, final Object objectToFind, i
}
/**
- * Finds the last index of the given value within the array.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ * Finds the last index of the given value within the array.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
*
- * @param array the array to traverse backwards looking for the object, may be {@code null}
- * @param valueToFind the object to find
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse backwards looking for the object, may be {@code null}.
+ * @param valueToFind The object to find.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final short[] array, final short valueToFind) {
return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
}
/**
- * Finds the last index of the given value in the array starting at the given index.
- *
- *
This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
- *
- *
A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
- * array length will search from the end of the array.
+ * Finds the last index of the given value in the array starting at the given index.
+ *
+ * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+ *
+ *
+ * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the array length will search from the end of the array.
+ *
*
- * @param array the array to traverse for looking for the object, may be {@code null}
- * @param valueToFind the value to find
- * @param startIndex the start index to traverse backwards from
- * @return the last index of the value within the array,
- * {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
+ * @param array The array to traverse for looking for the object, may be {@code null}.
+ * @param valueToFind The value to find.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
*/
public static int lastIndexOf(final short[] array, final short valueToFind, int startIndex) {
- if (array == null) {
+ if (array == null || startIndex < 0) {
return INDEX_NOT_FOUND;
}
- if (startIndex < 0) {
- return INDEX_NOT_FOUND;
- } else if (startIndex >= array.length) {
+ if (startIndex >= array.length) {
startIndex = array.length - 1;
}
for (int i = startIndex; i >= 0; i--) {
@@ -4168,408 +4561,459 @@ public static int lastIndexOf(final short[] array, final short valueToFind, int
}
/**
- * Defensive programming technique to change a {@code null}
- * reference to an empty one.
+ * Finds the last index of the NaN value in a double array.
+ * @param array The array to traverse backwards for NaN, may be {@code null}.
+ * @param startIndex The start index to traverse backwards from.
+ * @return The last index of the NaN value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input.
+ */
+ private static int lastIndexOfNaN(final double[] array, final int startIndex) {
+ if (isEmpty(array) || startIndex < 0) {
+ return INDEX_NOT_FOUND;
+ }
+ for (int i = Math.min(startIndex, array.length - 1); i >= 0; i--) {
+ if (Double.isNaN(array[i])) {
+ return i;
+ }
+ }
+ return INDEX_NOT_FOUND;
+ }
+
+ /**
+ * Maps elements from an array into elements of a new array of a given type, while mapping old elements to new elements.
+ *
+ * @param The input array type.
+ * @param The output array type.
+ * @param The type of exceptions thrown when the mapper function fails.
+ * @param array The input array.
+ * @param componentType The component type of the result array.
+ * @param mapper A non-interfering, stateless function to apply to each element.
+ * @return A new array.
+ * @throws E Thrown when the mapper function fails.
+ */
+ private static R[] map(final T[] array, final Class componentType, final FailableFunction mapper)
+ throws E {
+ return ArrayFill.fill(newInstance(componentType, array.length), i -> mapper.apply(array[i]));
+ }
+
+ private static int max0(final int other) {
+ return Math.max(0, other);
+ }
+
+ /**
+ * Delegates to {@link Array#newInstance(Class,int)} using generics.
*
- * This method returns an empty array for a {@code null} input array.
+ * @param The array type.
+ * @param componentType The array class.
+ * @param length The array length
+ * @return The new array.
+ * @throws NullPointerException if the specified {@code componentType} parameter is null.
+ * @since 3.13.0
+ */
+ @SuppressWarnings("unchecked") // OK, because array and values are of type T
+ public static T[] newInstance(final Class componentType, final int length) {
+ return (T[]) Array.newInstance(componentType, length);
+ }
+
+ /**
+ * Defensive programming technique to change a {@code null}
+ * reference to an empty one.
+ *
+ * This method returns a default array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
+ * the empty {@code public static} references in this class.
+ *
*
- * As a memory optimizing technique an empty array passed in will be overridden with
+ * @param The array type.
+ * @param array The array to check for {@code null} or empty
+ * @param defaultArray A default array, usually empty.
+ * @return The same array, or defaultArray if {@code null} or empty input.
+ * @since 3.15.0
+ */
+ public static T[] nullTo(final T[] array, final T[] defaultArray) {
+ return isEmpty(array) ? defaultArray : array;
+ }
+
+ /**
+ * Defensive programming technique to change a {@code null}
+ * reference to an empty one.
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static boolean[] nullToEmpty(final boolean[] array) {
- if (isEmpty(array)) {
- return EMPTY_BOOLEAN_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_BOOLEAN_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Boolean[] nullToEmpty(final Boolean[] array) {
- if (isEmpty(array)) {
- return EMPTY_BOOLEAN_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_BOOLEAN_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static byte[] nullToEmpty(final byte[] array) {
- if (isEmpty(array)) {
- return EMPTY_BYTE_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_BYTE_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Byte[] nullToEmpty(final Byte[] array) {
- if (isEmpty(array)) {
- return EMPTY_BYTE_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_BYTE_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static char[] nullToEmpty(final char[] array) {
- if (isEmpty(array)) {
- return EMPTY_CHAR_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_CHAR_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Character[] nullToEmpty(final Character[] array) {
- if (isEmpty(array)) {
- return EMPTY_CHARACTER_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_CHARACTER_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 3.2
*/
public static Class[] nullToEmpty(final Class[] array) {
- if (isEmpty(array)) {
- return EMPTY_CLASS_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_CLASS_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static double[] nullToEmpty(final double[] array) {
- if (isEmpty(array)) {
- return EMPTY_DOUBLE_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_DOUBLE_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Double[] nullToEmpty(final Double[] array) {
- if (isEmpty(array)) {
- return EMPTY_DOUBLE_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_DOUBLE_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static float[] nullToEmpty(final float[] array) {
- if (isEmpty(array)) {
- return EMPTY_FLOAT_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_FLOAT_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Float[] nullToEmpty(final Float[] array) {
- if (isEmpty(array)) {
- return EMPTY_FLOAT_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_FLOAT_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static int[] nullToEmpty(final int[] array) {
- if (isEmpty(array)) {
- return EMPTY_INT_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_INT_ARRAY : array;
}
- // Primitive/Object array converters
- // ----------------------------------------------------------------------
-
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Integer[] nullToEmpty(final Integer[] array) {
- if (isEmpty(array)) {
- return EMPTY_INTEGER_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_INTEGER_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static long[] nullToEmpty(final long[] array) {
- if (isEmpty(array)) {
- return EMPTY_LONG_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_LONG_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Long[] nullToEmpty(final Long[] array) {
- if (isEmpty(array)) {
- return EMPTY_LONG_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_LONG_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Object[] nullToEmpty(final Object[] array) {
- if (isEmpty(array)) {
- return EMPTY_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static short[] nullToEmpty(final short[] array) {
- if (isEmpty(array)) {
- return EMPTY_SHORT_ARRAY;
- }
- return array;
+ return isEmpty(array) ? EMPTY_SHORT_ARRAY : array;
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static Short[] nullToEmpty(final Short[] array) {
- if (isEmpty(array)) {
- return EMPTY_SHORT_OBJECT_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_SHORT_OBJECT_ARRAY);
}
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
- *
- *
This method returns an empty array for a {@code null} input array.
- *
- *
As a memory optimizing technique an empty array passed in will be overridden with
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
+ *
+ * As a memory optimizing technique an empty array passed in will be overridden with
* the empty {@code public static} references in this class.
+ *
*
- * @param array the array to check for {@code null} or empty
- * @return the same array, {@code public static} empty array if {@code null} or empty input
+ * @param array The array to check for {@code null} or empty.
+ * @return The same array, {@code public static} empty array if {@code null} or empty input.
* @since 2.5
*/
public static String[] nullToEmpty(final String[] array) {
- if (isEmpty(array)) {
- return EMPTY_STRING_ARRAY;
- }
- return array;
+ return nullTo(array, EMPTY_STRING_ARRAY);
}
- // nullToEmpty
- //-----------------------------------------------------------------------
/**
- * Defensive programming technique to change a {@code null}
+ * Defensive programming technique to change a {@code null}
* reference to an empty one.
+ *
+ * This method returns an empty array for a {@code null} input array.
+ *
*
- * This method returns an empty array for a {@code null} input array.
- *
- * @param array the array to check for {@code null} or empty
- * @param type the class representation of the desired array
- * @param the class type
- * @return the same array, {@code public static} empty array if {@code null}
- * @throws IllegalArgumentException if the type argument is null
+ * @param array The array to check for {@code null} or empty.
+ * @param type The class representation of the desired array.
+ * @param the class type.
+ * @return The same array, {@code public static} empty array if {@code null}.
+ * @throws IllegalArgumentException if the type argument is null.
* @since 3.5
*/
public static T[] nullToEmpty(final T[] array, final Class type) {
if (type == null) {
throw new IllegalArgumentException("The type must not be null");
}
-
if (array == null) {
return type.cast(Array.newInstance(type.getComponentType(), 0));
}
@@ -4577,17 +5021,24 @@ public static T[] nullToEmpty(final T[] array, final Class type) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
+ * Gets the current thread's {@link ThreadLocalRandom} for {@code shuffle} methods that don't take a {@link Random} argument.
*
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * @return The current ThreadLocalRandom.
+ */
+ private static ThreadLocalRandom random() {
+ return ThreadLocalRandom.current();
+ }
+
+ /**
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([true], 0) = []
@@ -4596,12 +5047,10 @@ public static T[] nullToEmpty(final T[] array, final Class type) {
* ArrayUtils.remove([true, true, false], 1) = [true, false]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static boolean[] remove(final boolean[] array, final int index) {
@@ -4609,17 +5058,15 @@ public static boolean[] remove(final boolean[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1], 0) = []
@@ -4628,12 +5075,10 @@ public static boolean[] remove(final boolean[] array, final int index) {
* ArrayUtils.remove([1, 0, 1], 1) = [1, 1]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static byte[] remove(final byte[] array, final int index) {
@@ -4641,17 +5086,15 @@ public static byte[] remove(final byte[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove(['a'], 0) = []
@@ -4660,12 +5103,10 @@ public static byte[] remove(final byte[] array, final int index) {
* ArrayUtils.remove(['a', 'b', 'c'], 1) = ['a', 'c']
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static char[] remove(final char[] array, final int index) {
@@ -4673,17 +5114,15 @@ public static char[] remove(final char[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1.1], 0) = []
@@ -4692,12 +5131,10 @@ public static char[] remove(final char[] array, final int index) {
* ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static double[] remove(final double[] array, final int index) {
@@ -4705,17 +5142,15 @@ public static double[] remove(final double[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1.1], 0) = []
@@ -4724,12 +5159,10 @@ public static double[] remove(final double[] array, final int index) {
* ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static float[] remove(final float[] array, final int index) {
@@ -4737,17 +5170,15 @@ public static float[] remove(final float[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1], 0) = []
@@ -4756,12 +5187,10 @@ public static float[] remove(final float[] array, final int index) {
* ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static int[] remove(final int[] array, final int index) {
@@ -4769,17 +5198,15 @@ public static int[] remove(final int[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1], 0) = []
@@ -4788,12 +5215,10 @@ public static int[] remove(final int[] array, final int index) {
* ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static long[] remove(final long[] array, final int index) {
@@ -4801,24 +5226,20 @@ public static long[] remove(final long[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
private static Object remove(final Object array, final int index) {
@@ -4826,28 +5247,24 @@ private static Object remove(final Object array, final int index) {
if (index < 0 || index >= length) {
throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + length);
}
-
final Object result = Array.newInstance(array.getClass().getComponentType(), length - 1);
System.arraycopy(array, 0, result, 0, index);
if (index < length - 1) {
System.arraycopy(array, index + 1, result, index, length - index - 1);
}
-
return result;
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove([1], 0) = []
@@ -4856,12 +5273,10 @@ private static Object remove(final Object array, final int index) {
* ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
public static short[] remove(final short[] array, final int index) {
@@ -4869,17 +5284,15 @@ public static short[] remove(final short[] array, final int index) {
}
/**
- * Removes the element at the specified position from the specified array.
- * All subsequent elements are shifted to the left (subtracts one from
- * their indices).
- *
- *
This method returns a new array with the same elements of the input
- * array except the element on the specified position. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the element at the specified position from the specified array. All subsequent elements are shifted to the left (subtracts one from their
+ * indices).
+ *
+ * This method returns a new array with the same elements of the input array except the element on the specified position. The component type of the
+ * returned array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, an IndexOutOfBoundsException will be thrown, because in that case no valid index can be specified.
+ *
*
*
* ArrayUtils.remove(["a"], 0) = []
@@ -4888,13 +5301,11 @@ public static short[] remove(final short[] array, final int index) {
* ArrayUtils.remove(["a", "b", "c"], 1) = ["a", "c"]
*
*
- * @param the component type of the array
- * @param array the array to remove the element from, may not be {@code null}
- * @param index the position of the element to be removed
- * @return A new array containing the existing elements except the element
- * at the specified position.
- * @throws IndexOutOfBoundsException if the index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param the component type of the array.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param index The position of the element to be removed.
+ * @return A new array containing the existing elements except the element at the specified position.
+ * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= array.length), or if the array is {@code null}.
* @since 2.1
*/
@SuppressWarnings("unchecked") // remove() always creates an array of the same type as its input
@@ -4903,28 +5314,24 @@ public static T[] remove(final T[] array, final int index) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([true, false, true], 0, 2) = [false]
* ArrayUtils.removeAll([true, false, true], 1, 2) = [true]
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static boolean[] removeAll(final boolean[] array, final int... indices) {
@@ -4932,16 +5339,14 @@ public static boolean[] removeAll(final boolean[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -4952,12 +5357,10 @@ public static boolean[] removeAll(final boolean[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static byte[] removeAll(final byte[] array, final int... indices) {
@@ -4965,16 +5368,14 @@ public static byte[] removeAll(final byte[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -4985,12 +5386,10 @@ public static byte[] removeAll(final byte[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static char[] removeAll(final char[] array, final int... indices) {
@@ -4998,16 +5397,14 @@ public static char[] removeAll(final char[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -5018,12 +5415,10 @@ public static char[] removeAll(final char[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static double[] removeAll(final double[] array, final int... indices) {
@@ -5031,16 +5426,14 @@ public static double[] removeAll(final double[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -5051,12 +5444,10 @@ public static double[] removeAll(final double[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static float[] removeAll(final float[] array, final int... indices) {
@@ -5064,16 +5455,14 @@ public static float[] removeAll(final float[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -5084,12 +5473,10 @@ public static float[] removeAll(final float[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static int[] removeAll(final int[] array, final int... indices) {
@@ -5097,16 +5484,14 @@ public static int[] removeAll(final int[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -5117,12 +5502,10 @@ public static int[] removeAll(final int[] array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static long[] removeAll(final long[] array, final int... indices) {
@@ -5130,61 +5513,20 @@ public static long[] removeAll(final long[] array, final int... indices) {
}
/**
- * Removes multiple array elements specified by indices.
+ * Removes multiple array elements specified by index.
*
- * @param array source
+ * @param array source
* @param indices to remove
- * @return new array of same type minus elements specified by the set bits in {@code indices}
- * @since 3.2
+ * @return new array of same type minus elements specified by unique values of {@code indices}
*/
// package protected for access by unit tests
- static Object removeAll(final Object array, final BitSet indices) {
+ static Object removeAll(final Object array, final int... indices) {
if (array == null) {
return null;
}
-
- final int srcLength = getLength(array);
- // No need to check maxIndex here, because method only currently called from removeElements()
- // which guarantee to generate on;y valid bit entries.
-// final int maxIndex = indices.length();
-// if (maxIndex > srcLength) {
-// throw new IndexOutOfBoundsException("Index: " + (maxIndex-1) + ", Length: " + srcLength);
-// }
- final int removals = indices.cardinality(); // true bits are items to remove
- final Object result = Array.newInstance(array.getClass().getComponentType(), srcLength - removals);
- int srcIndex = 0;
- int destIndex = 0;
- int count;
- int set;
- while ((set = indices.nextSetBit(srcIndex)) != -1) {
- count = set - srcIndex;
- if (count > 0) {
- System.arraycopy(array, srcIndex, result, destIndex, count);
- destIndex += count;
- }
- srcIndex = indices.nextClearBit(set);
- }
- count = srcLength - srcIndex;
- if (count > 0) {
- System.arraycopy(array, srcIndex, result, destIndex, count);
- }
- return result;
- }
-
- /**
- * Removes multiple array elements specified by index.
- * @param array source
- * @param indices to remove
- * @return new array of same type minus elements specified by unique values of {@code indices}
- * @since 3.0.1
- */
- // package protected for access by unit tests
- static Object removeAll(final Object array, final int... indices) {
final int length = getLength(array);
int diff = 0; // number of distinct indexes, i.e. number of entries that will be removed
- final int[] clonedIndices = clone(indices);
- Arrays.sort(clonedIndices);
-
+ final int[] clonedIndices = ArraySorter.sort(clone(indices));
// identify length of result array
if (isNotEmpty(clonedIndices)) {
int i = clonedIndices.length;
@@ -5201,10 +5543,9 @@ static Object removeAll(final Object array, final int... indices) {
prevIndex = index;
}
}
-
// create result array
final Object result = Array.newInstance(array.getClass().getComponentType(), length - diff);
- if (diff < length) {
+ if (diff < length && clonedIndices != null) {
int end = length; // index just after last copy
int dest = length - diff; // number of entries so far not copied
for (int i = clonedIndices.length - 1; i >= 0; i--) {
@@ -5213,7 +5554,7 @@ static Object removeAll(final Object array, final int... indices) {
final int cp = end - index - 1;
dest -= cp;
System.arraycopy(array, index + 1, result, dest, cp);
- // Afer this copy, we still have room for dest items.
+ // After this copy, we still have room for dest items.
}
end = index;
}
@@ -5225,16 +5566,14 @@ static Object removeAll(final Object array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll([1], 0) = []
@@ -5245,12 +5584,10 @@ static Object removeAll(final Object array, final int... indices) {
* ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
*
*
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
public static short[] removeAll(final short[] array, final int... indices) {
@@ -5258,29 +5595,25 @@ public static short[] removeAll(final short[] array, final int... indices) {
}
/**
- * Removes the elements at the specified positions from the specified array.
- * All remaining elements are shifted to the left.
- *
- *
This method returns a new array with the same elements of the input
- * array except those at the specified positions. The component
- * type of the returned array is always the same as that of the input
- * array.
- *
- *
If the input array is {@code null}, an IndexOutOfBoundsException
- * will be thrown, because in that case no valid index can be specified.
+ * Removes the elements at the specified positions from the specified array. All remaining elements are shifted to the left.
+ *
+ * This method returns a new array with the same elements of the input array except those at the specified positions. The component type of the returned
+ * array is always the same as that of the input array.
+ *
+ *
+ * If the input array is {@code null}, then return {@code null}.
+ *
*
*
* ArrayUtils.removeAll(["a", "b", "c"], 0, 2) = ["b"]
* ArrayUtils.removeAll(["a", "b", "c"], 1, 2) = ["a"]
*
*
- * @param the component type of the array
- * @param array the array to remove the element from, may not be {@code null}
- * @param indices the positions of the elements to be removed
- * @return A new array containing the existing elements except those
- * at the specified positions.
- * @throws IndexOutOfBoundsException if any index is out of range
- * (index < 0 || index >= array.length), or if the array is {@code null}.
+ * @param the component type of the array.
+ * @param array The array to remove the element from, may not be {@code null}.
+ * @param indices The positions of the elements to be removed.
+ * @return A new array containing the existing elements except those at the specified positions or {@code null} if the input array is {@code null}.
+ * @throws IndexOutOfBoundsException if any index is out of range (index < 0 || index >= array.length).
* @since 3.0.1
*/
@SuppressWarnings("unchecked") // removeAll() always creates an array of the same type as its input
@@ -5290,187 +5623,381 @@ public static T[] removeAll(final T[] array, final int... indices) {
/**
* Removes the occurrences of the specified element from the specified boolean array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
* @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(boolean[], boolean)}.
*/
+ @Deprecated
public static boolean[] removeAllOccurences(final boolean[] array, final boolean element) {
- return (boolean[]) removeAll((Object) array, indexesOf(array, element));
+ return (boolean[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified byte array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
* @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(byte[], byte)}.
*/
+ @Deprecated
public static byte[] removeAllOccurences(final byte[] array, final byte element) {
- return (byte[]) removeAll((Object) array, indexesOf(array, element));
+ return (byte[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified char array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
* @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(char[], char)}.
*/
+ @Deprecated
public static char[] removeAllOccurences(final char[] array, final char element) {
- return (char[]) removeAll((Object) array, indexesOf(array, element));
+ return (char[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified double array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
* @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(double[], double)}.
*/
+ @Deprecated
public static double[] removeAllOccurences(final double[] array, final double element) {
- return (double[]) removeAll((Object) array, indexesOf(array, element));
+ return (double[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified float array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(float[], float)}.
+ */
+ @Deprecated
+ public static float[] removeAllOccurences(final float[] array, final float element) {
+ return (float[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified int array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(int[], int)}.
+ */
+ @Deprecated
+ public static int[] removeAllOccurences(final int[] array, final int element) {
+ return (int[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified long array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(long[], long)}.
+ */
+ @Deprecated
+ public static long[] removeAllOccurences(final long[] array, final long element) {
+ return (long[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified short array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(short[], short)}.
+ */
+ @Deprecated
+ public static short[] removeAllOccurences(final short[] array, final short element) {
+ return (short[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param The type of object in the array, may be {@code null}.
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove, may be {@code null}.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.5
+ * @deprecated Use {@link #removeAllOccurrences(Object[], Object)}.
+ */
+ @Deprecated
+ public static T[] removeAllOccurences(final T[] array, final T element) {
+ return (T[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified boolean array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.10
+ */
+ public static boolean[] removeAllOccurrences(final boolean[] array, final boolean element) {
+ return (boolean[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified byte array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.10
+ */
+ public static byte[] removeAllOccurrences(final byte[] array, final byte element) {
+ return (byte[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified char array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.10
+ */
+ public static char[] removeAllOccurrences(final char[] array, final char element) {
+ return (char[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified double array.
+ *
+ * All subsequent elements are shifted to the left (subtracts one from their indices).
+ * If the array doesn't contain such an element, no elements are removed from the array.
+ * {@code null} will be returned if the input array is {@code null}.
+ *
*
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
+ * @return A new array containing the existing elements except the occurrences of the specified element.
+ * @since 3.10
+ */
+ public static double[] removeAllOccurrences(final double[] array, final double element) {
+ return (double[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes the occurrences of the specified element from the specified float array.
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
- * @since 3.5
+ * @since 3.10
*/
- public static float[] removeAllOccurences(final float[] array, final float element) {
- return (float[]) removeAll((Object) array, indexesOf(array, element));
+ public static float[] removeAllOccurrences(final float[] array, final float element) {
+ return (float[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified int array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
- * @since 3.5
+ * @since 3.10
*/
- public static int[] removeAllOccurences(final int[] array, final int element) {
- return (int[]) removeAll((Object) array, indexesOf(array, element));
+ public static int[] removeAllOccurrences(final int[] array, final int element) {
+ return (int[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified long array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
- * @since 3.5
+ * @since 3.10
*/
- public static long[] removeAllOccurences(final long[] array, final long element) {
- return (long[]) removeAll((Object) array, indexesOf(array, element));
+ public static long[] removeAllOccurrences(final long[] array, final long element) {
+ return (long[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified short array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param element the element to remove
- * @param array the input array
- *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove.
* @return A new array containing the existing elements except the occurrences of the specified element.
- * @since 3.5
+ * @since 3.10
*/
- public static short[] removeAllOccurences(final short[] array, final short element) {
- return (short[]) removeAll((Object) array, indexesOf(array, element));
+ public static short[] removeAllOccurrences(final short[] array, final short element) {
+ return (short[]) removeAt(array, indexesOf(array, element));
}
/**
* Removes the occurrences of the specified element from the specified array.
- *
*
* All subsequent elements are shifted to the left (subtracts one from their indices).
- * If the array doesn't contains such an element, no elements are removed from the array.
+ * If the array doesn't contain such an element, no elements are removed from the array.
* {@code null} will be returned if the input array is {@code null}.
*
*
- * @param the type of object in the array
- * @param element the element to remove
- * @param array the input array
- *
+ * @param The type of object in the array, may be {@code null}.
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param element The element to remove, may be {@code null}.
* @return A new array containing the existing elements except the occurrences of the specified element.
- * @since 3.5
+ * @since 3.10
*/
- public static T[] removeAllOccurences(final T[] array, final T element) {
- return (T[]) removeAll((Object) array, indexesOf(array, element));
+ public static T[] removeAllOccurrences(final T[] array, final T element) {
+ return (T[]) removeAt(array, indexesOf(array, element));
+ }
+
+ /**
+ * Removes multiple array elements specified by indices.
+ *
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param indices to remove.
+ * @return new array of same type minus elements specified by the set bits in {@code indices}.
+ */
+ // package protected for access by unit tests
+ static Object removeAt(final Object array, final BitSet indices) {
+ if (array == null) {
+ return null;
+ }
+ final int srcLength = getLength(array);
+ // No need to check maxIndex here, because method only currently called from removeElements()
+ // which guarantee to generate only valid bit entries.
+// final int maxIndex = indices.length();
+// if (maxIndex > srcLength) {
+// throw new IndexOutOfBoundsException("Index: " + (maxIndex-1) + ", Length: " + srcLength);
+// }
+ final int removals = indices.cardinality(); // true bits are items to remove
+ final Object result = Array.newInstance(array.getClass().getComponentType(), srcLength - removals);
+ int srcIndex = 0;
+ int destIndex = 0;
+ int count;
+ int set;
+ while ((set = indices.nextSetBit(srcIndex)) != -1) {
+ count = set - srcIndex;
+ if (count > 0) {
+ System.arraycopy(array, srcIndex, result, destIndex, count);
+ destIndex += count;
+ }
+ srcIndex = indices.nextClearBit(set);
+ }
+ count = srcLength - srcIndex;
+ if (count > 0) {
+ System.arraycopy(array, srcIndex, result, destIndex, count);
+ }
+ return result;
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, true) = null
* ArrayUtils.removeElement([], true) = []
@@ -5479,31 +6006,28 @@ public static T[] removeAllOccurences(final T[] array, final T element) {
* ArrayUtils.removeElement([true, false, true], true) = [false, true]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static boolean[] removeElement(final boolean[] array, final boolean element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1) = null
* ArrayUtils.removeElement([], 1) = []
@@ -5512,31 +6036,28 @@ public static boolean[] removeElement(final boolean[] array, final boolean eleme
* ArrayUtils.removeElement([1, 0, 1], 1) = [0, 1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static byte[] removeElement(final byte[] array, final byte element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 'a') = null
* ArrayUtils.removeElement([], 'a') = []
@@ -5545,31 +6066,28 @@ public static byte[] removeElement(final byte[] array, final byte element) {
* ArrayUtils.removeElement(['a', 'b', 'a'], 'a') = ['b', 'a']
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static char[] removeElement(final char[] array, final char element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1.1) = null
* ArrayUtils.removeElement([], 1.1) = []
@@ -5578,31 +6096,28 @@ public static char[] removeElement(final char[] array, final char element) {
* ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static double[] removeElement(final double[] array, final double element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1.1) = null
* ArrayUtils.removeElement([], 1.1) = []
@@ -5611,31 +6126,28 @@ public static double[] removeElement(final double[] array, final double element)
* ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static float[] removeElement(final float[] array, final float element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1) = null
* ArrayUtils.removeElement([], 1) = []
@@ -5644,31 +6156,28 @@ public static float[] removeElement(final float[] array, final float element) {
* ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static int[] removeElement(final int[] array, final int element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1) = null
* ArrayUtils.removeElement([], 1) = []
@@ -5677,31 +6186,28 @@ public static int[] removeElement(final int[] array, final int element) {
* ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static long[] removeElement(final long[] array, final long element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, 1) = null
* ArrayUtils.removeElement([], 1) = []
@@ -5710,31 +6216,28 @@ public static long[] removeElement(final long[] array, final long element) {
* ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static short[] removeElement(final short[] array, final short element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes the first occurrence of the specified element from the
+ * Removes the first occurrence of the specified element from the
* specified array. All subsequent elements are shifted to the left
- * (subtracts one from their indices). If the array doesn't contains
+ * (subtracts one from their indices). If the array doesn't contain
* such an element, no elements are removed from the array.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except the first occurrence of the specified element. The component
* type of the returned array is always the same as that of the input
* array.
- *
+ *
*
* ArrayUtils.removeElement(null, "a") = null
* ArrayUtils.removeElement([], "a") = []
@@ -5743,33 +6246,30 @@ public static short[] removeElement(final short[] array, final short element) {
* ArrayUtils.removeElement(["a", "b", "a"], "a") = ["b", "a"]
*
*
- * @param the component type of the array
- * @param array the array to remove the element from, may be {@code null}
- * @param element the element to be removed
+ * @param The component type of the array
+ * @param array The input array, may be {@code null}.
+ * @param element The element to be removed, may be {@code null}.
* @return A new array containing the existing elements except the first
* occurrence of the specified element.
* @since 2.1
*/
public static T[] removeElement(final T[] array, final Object element) {
final int index = indexOf(array, element);
- if (index == INDEX_NOT_FOUND) {
- return clone(array);
- }
- return remove(array, index);
+ return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, true, false) = null
* ArrayUtils.removeElements([], true, false) = []
@@ -5779,8 +6279,8 @@ public static T[] removeElement(final T[] array, final Object element) {
* ArrayUtils.removeElements([true, false, true], true, true) = [false]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -5791,13 +6291,7 @@ public static boolean[] removeElements(final boolean[] array, final boolean... v
}
final HashMap occurrences = new HashMap<>(2); // only two possible values here
for (final boolean v : values) {
- final Boolean boxed = Boolean.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Boolean.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -5810,21 +6304,21 @@ public static boolean[] removeElements(final boolean[] array, final boolean... v
toRemove.set(i);
}
}
- return (boolean[]) removeAll(array, toRemove);
+ return (boolean[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -5834,8 +6328,8 @@ public static boolean[] removeElements(final boolean[] array, final boolean... v
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -5844,15 +6338,9 @@ public static byte[] removeElements(final byte[] array, final byte... values) {
if (isEmpty(array) || isEmpty(values)) {
return clone(array);
}
- final Map occurrences = new HashMap<>(values.length);
+ final HashMap occurrences = new HashMap<>(values.length);
for (final byte v : values) {
- final Byte boxed = Byte.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Byte.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -5865,21 +6353,21 @@ public static byte[] removeElements(final byte[] array, final byte... values) {
toRemove.set(i);
}
}
- return (byte[]) removeAll(array, toRemove);
+ return (byte[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -5889,8 +6377,8 @@ public static byte[] removeElements(final byte[] array, final byte... values) {
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -5901,13 +6389,7 @@ public static char[] removeElements(final char[] array, final char... values) {
}
final HashMap occurrences = new HashMap<>(values.length);
for (final char v : values) {
- final Character boxed = Character.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Character.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -5920,21 +6402,21 @@ public static char[] removeElements(final char[] array, final char... values) {
toRemove.set(i);
}
}
- return (char[]) removeAll(array, toRemove);
+ return (char[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -5944,8 +6426,8 @@ public static char[] removeElements(final char[] array, final char... values) {
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -5956,13 +6438,7 @@ public static double[] removeElements(final double[] array, final double... valu
}
final HashMap occurrences = new HashMap<>(values.length);
for (final double v : values) {
- final Double boxed = Double.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Double.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -5975,21 +6451,21 @@ public static double[] removeElements(final double[] array, final double... valu
toRemove.set(i);
}
}
- return (double[]) removeAll(array, toRemove);
+ return (double[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -5999,8 +6475,8 @@ public static double[] removeElements(final double[] array, final double... valu
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -6011,13 +6487,7 @@ public static float[] removeElements(final float[] array, final float... values)
}
final HashMap occurrences = new HashMap<>(values.length);
for (final float v : values) {
- final Float boxed = Float.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Float.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -6030,21 +6500,21 @@ public static float[] removeElements(final float[] array, final float... values)
toRemove.set(i);
}
}
- return (float[]) removeAll(array, toRemove);
+ return (float[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -6054,8 +6524,8 @@ public static float[] removeElements(final float[] array, final float... values)
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -6066,13 +6536,7 @@ public static int[] removeElements(final int[] array, final int... values) {
}
final HashMap occurrences = new HashMap<>(values.length);
for (final int v : values) {
- final Integer boxed = Integer.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Integer.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -6085,21 +6549,21 @@ public static int[] removeElements(final int[] array, final int... values) {
toRemove.set(i);
}
}
- return (int[]) removeAll(array, toRemove);
+ return (int[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -6109,8 +6573,8 @@ public static int[] removeElements(final int[] array, final int... values) {
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -6121,13 +6585,7 @@ public static long[] removeElements(final long[] array, final long... values) {
}
final HashMap occurrences = new HashMap<>(values.length);
for (final long v : values) {
- final Long boxed = Long.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Long.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -6140,21 +6598,21 @@ public static long[] removeElements(final long[] array, final long... values) {
toRemove.set(i);
}
}
- return (long[]) removeAll(array, toRemove);
+ return (long[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, 1, 2) = null
* ArrayUtils.removeElements([], 1, 2) = []
@@ -6164,8 +6622,8 @@ public static long[] removeElements(final long[] array, final long... values) {
* ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
*
*
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -6176,13 +6634,7 @@ public static short[] removeElements(final short[] array, final short... values)
}
final HashMap occurrences = new HashMap<>(values.length);
for (final short v : values) {
- final Short boxed = Short.valueOf(v);
- final MutableInt count = occurrences.get(boxed);
- if (count == null) {
- occurrences.put(boxed, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, Short.valueOf(v));
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -6195,21 +6647,21 @@ public static short[] removeElements(final short[] array, final short... values)
toRemove.set(i);
}
}
- return (short[]) removeAll(array, toRemove);
+ return (short[]) removeAt(array, toRemove);
}
/**
- * Removes occurrences of specified elements, in specified quantities,
+ * Removes occurrences of specified elements, in specified quantities,
* from the specified array. All subsequent elements are shifted left.
* For any element-to-be-removed specified in greater quantities than
* contained in the original array, no change occurs beyond the
* removal of the existing matching items.
- *
- *
This method returns a new array with the same elements of the input
+ *
+ * This method returns a new array with the same elements of the input
* array except for the earliest-encountered occurrences of the specified
* elements. The component type of the returned array is always the same
* as that of the input array.
- *
+ *
*
* ArrayUtils.removeElements(null, "a", "b") = null
* ArrayUtils.removeElements([], "a", "b") = []
@@ -6219,9 +6671,9 @@ public static short[] removeElements(final short[] array, final short... values)
* ArrayUtils.removeElements(["a", "b", "a"], "a", "a") = ["b"]
*
*
- * @param the component type of the array
- * @param array the array to remove the element from, may be {@code null}
- * @param values the elements to be removed
+ * @param The component type of the array
+ * @param array The input array, will not be modified, and may be {@code null}.
+ * @param values The values to be removed.
* @return A new array containing the existing elements except the
* earliest-encountered occurrences of the specified elements.
* @since 3.0.1
@@ -6233,12 +6685,7 @@ public static T[] removeElements(final T[] array, final T... values) {
}
final HashMap occurrences = new HashMap<>(values.length);
for (final T v : values) {
- final MutableInt count = occurrences.get(v);
- if (count == null) {
- occurrences.put(v, new MutableInt(1));
- } else {
- count.increment();
- }
+ increment(occurrences, v);
}
final BitSet toRemove = new BitSet();
for (int i = 0; i < array.length; i++) {
@@ -6252,33 +6699,32 @@ public static T[] removeElements(final T[] array, final T... values) {
}
}
@SuppressWarnings("unchecked") // removeAll() always creates an array of the same type as its input
- final T[] result = (T[]) removeAll(array, toRemove);
+ final T[] result = (T[]) removeAt(array, toRemove);
return result;
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final boolean[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
* @param array
- * the array to reverse, may be {@code null}
+ * the array to reverse, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6291,8 +6737,8 @@ public static void reverse(final boolean[] array, final int startIndexInclusive,
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
boolean tmp;
while (j > i) {
tmp = array[j];
@@ -6304,42 +6750,37 @@ public static void reverse(final boolean[] array, final int startIndexInclusive,
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final byte[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
- * @param array
- * the array to reverse, may be {@code null}
- * @param startIndexInclusive
- * the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
- * change.
- * @param endIndexExclusive
- * elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no
- * change. Overvalue (>array.length) is demoted to array length.
+ * @param array The array to reverse, may be {@code null}.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no change.
+ * @param endIndexExclusive elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no change. Overvalue
+ * (>array.length) is demoted to array length.
* @since 3.2
*/
public static void reverse(final byte[] array, final int startIndexInclusive, final int endIndexExclusive) {
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
byte tmp;
while (j > i) {
tmp = array[j];
@@ -6351,42 +6792,37 @@ public static void reverse(final byte[] array, final int startIndexInclusive, fi
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final char[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
- * @param array
- * the array to reverse, may be {@code null}
- * @param startIndexInclusive
- * the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
- * change.
- * @param endIndexExclusive
- * elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no
- * change. Overvalue (>array.length) is demoted to array length.
+ * @param array The array to reverse, may be {@code null}.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no change.
+ * @param endIndexExclusive elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no change. Overvalue
+ * (>array.length) is demoted to array length.
* @since 3.2
*/
public static void reverse(final char[] array, final int startIndexInclusive, final int endIndexExclusive) {
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
char tmp;
while (j > i) {
tmp = array[j];
@@ -6398,42 +6834,37 @@ public static void reverse(final char[] array, final int startIndexInclusive, fi
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}
*/
public static void reverse(final double[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
- * @param array
- * the array to reverse, may be {@code null}
- * @param startIndexInclusive
- * the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
- * change.
- * @param endIndexExclusive
- * elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no
- * change. Overvalue (>array.length) is demoted to array length.
+ * @param array The array to reverse, may be {@code null}.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no change.
+ * @param endIndexExclusive elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no change. Overvalue
+ * (>array.length) is demoted to array length.
* @since 3.2
*/
public static void reverse(final double[] array, final int startIndexInclusive, final int endIndexExclusive) {
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
double tmp;
while (j > i) {
tmp = array[j];
@@ -6445,42 +6876,37 @@ public static void reverse(final double[] array, final int startIndexInclusive,
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final float[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
- * @param array
- * the array to reverse, may be {@code null}
- * @param startIndexInclusive
- * the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
- * change.
- * @param endIndexExclusive
- * elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no
- * change. Overvalue (>array.length) is demoted to array length.
+ * @param array The array to reverse, may be {@code null}.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no change.
+ * @param endIndexExclusive elements up to endIndex-1 are reversed in the array. Undervalue (< start index) results in no change. Overvalue
+ * (>array.length) is demoted to array length.
* @since 3.2
*/
public static void reverse(final float[] array, final int startIndexInclusive, final int endIndexExclusive) {
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
float tmp;
while (j > i) {
tmp = array[j];
@@ -6492,28 +6918,27 @@ public static void reverse(final float[] array, final int startIndexInclusive, f
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final int[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
* @param array
- * the array to reverse, may be {@code null}
+ * the array to reverse, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6526,8 +6951,8 @@ public static void reverse(final int[] array, final int startIndexInclusive, fin
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
int tmp;
while (j > i) {
tmp = array[j];
@@ -6539,28 +6964,27 @@ public static void reverse(final int[] array, final int startIndexInclusive, fin
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final long[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
* @param array
- * the array to reverse, may be {@code null}
+ * the array to reverse, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6573,8 +6997,8 @@ public static void reverse(final long[] array, final int startIndexInclusive, fi
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
long tmp;
while (j > i) {
tmp = array[j];
@@ -6585,33 +7009,31 @@ public static void reverse(final long[] array, final int startIndexInclusive, fi
}
}
- // Reverse
- //-----------------------------------------------------------------------
/**
- * Reverses the order of the given array.
- *
- *
There is no special handling for multi-dimensional arrays.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * There is no special handling for multi-dimensional arrays.
+ *
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final Object[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
* @param array
- * the array to reverse, may be {@code null}
+ * the array to reverse, may be {@code null}.
* @param startIndexInclusive
* the starting index. Under value (<0) is promoted to 0, over value (>array.length) results in no
* change.
@@ -6624,8 +7046,8 @@ public static void reverse(final Object[] array, final int startIndexInclusive,
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
Object tmp;
while (j > i) {
tmp = array[j];
@@ -6637,28 +7059,27 @@ public static void reverse(final Object[] array, final int startIndexInclusive,
}
/**
- * Reverses the order of the given array.
- *
- *
This method does nothing for a {@code null} input array.
+ * Reverses the order of the given array.
+ *
+ * This method does nothing for a {@code null} input array.
+ *
*
- * @param array the array to reverse, may be {@code null}
+ * @param array The array to reverse, may be {@code null}.
*/
public static void reverse(final short[] array) {
- if (array == null) {
- return;
+ if (array != null) {
+ reverse(array, 0, array.length);
}
- reverse(array, 0, array.length);
}
/**
- *
* Reverses the order of the given array in the given range.
- *
*
* This method does nothing for a {@code null} input array.
+ *
*
* @param array
- * the array to reverse, may be {@code null}
+ * the array to reverse, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6671,8 +7092,8 @@ public static void reverse(final short[] array, final int startIndexInclusive, f
if (array == null) {
return;
}
- int i = startIndexInclusive < 0 ? 0 : startIndexInclusive;
- int j = Math.min(array.length, endIndexExclusive) - 1;
+ int i = Math.max(startIndexInclusive, 0);
+ int j = max0(Math.min(array.length, endIndexExclusive)) - 1;
short tmp;
while (j > i) {
tmp = array[j];
@@ -6683,23 +7104,64 @@ public static void reverse(final short[] array, final int startIndexInclusive, f
}
}
+ /**
+ * Sets all elements of the specified array, using the provided generator supplier to compute each element.
+ *
+ * If the generator supplier throws an exception, it is relayed to the caller and the array is left in an indeterminate
+ * state.
+ *
+ *
+ * @param type of elements of the array, may be {@code null}.
+ * @param array array to be initialized, may be {@code null}.
+ * @param generator A function accepting an index and producing the desired value for that position.
+ * @return The input array
+ * @since 3.13.0
+ */
+ public static T[] setAll(final T[] array, final IntFunction generator) {
+ if (array != null && generator != null) {
+ Arrays.setAll(array, generator);
+ }
+ return array;
+ }
+
+ /**
+ * Sets all elements of the specified array, using the provided generator supplier to compute each element.
+ *
+ * If the generator supplier throws an exception, it is relayed to the caller and the array is left in an indeterminate
+ * state.
+ *
+ *
+ * @param type of elements of the array, may be {@code null}.
+ * @param array array to be initialized, may be {@code null}.
+ * @param generator A function accepting an index and producing the desired value for that position.
+ * @return The input array
+ * @since 3.13.0
+ */
+ public static T[] setAll(final T[] array, final Supplier generator) {
+ if (array != null && generator != null) {
+ for (int i = 0; i < array.length; i++) {
+ array[i] = generator.get();
+ }
+ }
+ return array;
+ }
+
/**
* Shifts the order of the given boolean array.
*
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final boolean[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -6709,7 +7171,7 @@ public static void shift(final boolean[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6722,18 +7184,11 @@ public static void shift(final boolean[] array, final int offset) {
* @since 3.5
*/
public static void shift(final boolean[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -6745,18 +7200,17 @@ public static void shift(final boolean[] array, int startIndexInclusive, int end
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -6768,17 +7222,16 @@ public static void shift(final boolean[] array, int startIndexInclusive, int end
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final byte[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -6788,7 +7241,7 @@ public static void shift(final byte[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6801,18 +7254,11 @@ public static void shift(final byte[] array, final int offset) {
* @since 3.5
*/
public static void shift(final byte[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
- return;
- }
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -6824,18 +7270,17 @@ public static void shift(final byte[] array, int startIndexInclusive, int endInd
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -6847,17 +7292,16 @@ public static void shift(final byte[] array, int startIndexInclusive, int endInd
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final char[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -6867,7 +7311,7 @@ public static void shift(final char[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6880,18 +7324,11 @@ public static void shift(final char[] array, final int offset) {
* @since 3.5
*/
public static void shift(final char[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -6903,18 +7340,17 @@ public static void shift(final char[] array, int startIndexInclusive, int endInd
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -6926,17 +7362,16 @@ public static void shift(final char[] array, int startIndexInclusive, int endInd
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final double[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -6946,7 +7381,7 @@ public static void shift(final double[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -6959,18 +7394,11 @@ public static void shift(final double[] array, final int offset) {
* @since 3.5
*/
public static void shift(final double[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -6982,18 +7410,17 @@ public static void shift(final double[] array, int startIndexInclusive, int endI
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -7005,17 +7432,16 @@ public static void shift(final double[] array, int startIndexInclusive, int endI
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final float[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -7025,7 +7451,7 @@ public static void shift(final float[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -7038,18 +7464,11 @@ public static void shift(final float[] array, final int offset) {
* @since 3.5
*/
public static void shift(final float[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -7061,18 +7480,17 @@ public static void shift(final float[] array, int startIndexInclusive, int endIn
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -7084,17 +7502,16 @@ public static void shift(final float[] array, int startIndexInclusive, int endIn
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final int[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -7104,7 +7521,7 @@ public static void shift(final int[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -7117,18 +7534,11 @@ public static void shift(final int[] array, final int offset) {
* @since 3.5
*/
public static void shift(final int[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
- return;
- }
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -7140,18 +7550,17 @@ public static void shift(final int[] array, int startIndexInclusive, int endInde
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -7163,17 +7572,16 @@ public static void shift(final int[] array, int startIndexInclusive, int endInde
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final long[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -7183,7 +7591,7 @@ public static void shift(final long[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -7196,18 +7604,11 @@ public static void shift(final long[] array, final int offset) {
* @since 3.5
*/
public static void shift(final long[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -7219,42 +7620,38 @@ public static void shift(final long[] array, int startIndexInclusive, int endInd
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
}
- // Shift
- //-----------------------------------------------------------------------
/**
* Shifts the order of the given array.
*
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final Object[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -7264,7 +7661,7 @@ public static void shift(final Object[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -7277,18 +7674,11 @@ public static void shift(final Object[] array, final int offset) {
* @since 3.5
*/
public static void shift(final Object[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -7300,18 +7690,17 @@ public static void shift(final Object[] array, int startIndexInclusive, int endI
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
@@ -7323,17 +7712,16 @@ public static void shift(final Object[] array, int startIndexInclusive, int endI
* There is no special handling for multi-dimensional arrays. This method
* does nothing for {@code null} or empty input arrays.
*
- * @param array the array to shift, may be {@code null}
+ * @param array The array to shift, may be {@code null}.
* @param offset
* The number of positions to rotate the elements. If the offset is larger than the number of elements to
* rotate, than the effective offset is modulo the number of elements to rotate.
* @since 3.5
*/
public static void shift(final short[] array, final int offset) {
- if (array == null) {
- return;
+ if (array != null) {
+ shift(array, 0, array.length, offset);
}
- shift(array, 0, array.length, offset);
}
/**
@@ -7343,7 +7731,7 @@ public static void shift(final short[] array, final int offset) {
* does nothing for {@code null} or empty input arrays.
*
* @param array
- * the array to shift, may be {@code null}
+ * the array to shift, may be {@code null}.
* @param startIndexInclusive
* the starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in no
* change.
@@ -7356,18 +7744,11 @@ public static void shift(final short[] array, final int offset) {
* @since 3.5
*/
public static void shift(final short[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
- if (array == null) {
- return;
- }
- if (startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
+ if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
return;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive >= array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = Math.min(endIndexExclusive, array.length);
int n = endIndexExclusive - startIndexInclusive;
if (n <= 1) {
return;
@@ -7379,265 +7760,392 @@ public static void shift(final short[] array, int startIndexInclusive, int endIn
// For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
// see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
while (n > 1 && offset > 0) {
- final int n_offset = n - offset;
-
- if (offset > n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n - n_offset, n_offset);
+ final int nOffset = n - offset;
+ if (offset > nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + n - nOffset, nOffset);
n = offset;
- offset -= n_offset;
- } else if (offset < n_offset) {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ offset -= nOffset;
+ } else if (offset < nOffset) {
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
startIndexInclusive += offset;
- n = n_offset;
+ n = nOffset;
} else {
- swap(array, startIndexInclusive, startIndexInclusive + n_offset, offset);
+ swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
break;
}
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final boolean[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final boolean[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final byte[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final byte[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final char[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final char[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final double[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final double[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final float[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final float[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final int[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final int[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final long[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final long[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final Object[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final Object[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
+ *
+ * This method uses the current {@link ThreadLocalRandom} as its random number generator.
+ *
+ *
+ * Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
+ * with a {@link SecureRandom} argument.
+ *
*
- * @param array the array to shuffle
+ * @param array The array to shuffle.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final short[] array) {
- shuffle(array, new Random());
+ shuffle(array, random());
}
/**
- * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
+ * Shuffles randomly the elements of the specified array using the Fisher-Yates shuffle
+ * algorithm .
*
- * @param array the array to shuffle
- * @param random the source of randomness used to permute the elements
+ * @param array The array to shuffle, no-op if {@code null}.
+ * @param random The source of randomness used to permute the elements, no-op if {@code null}.
* @see Fisher-Yates shuffle algorithm
* @since 3.6
*/
public static void shuffle(final short[] array, final Random random) {
- for (int i = array.length; i > 1; i--) {
- swap(array, i - 1, random.nextInt(i), 1);
+ if (array != null && random != null) {
+ for (int i = array.length; i > 1; i--) {
+ swap(array, i - 1, random.nextInt(i), 1);
+ }
}
}
/**
- * Produces a new {@code boolean} array containing the elements
- * between the start and end indices.
+ * Tests whether the given data array starts with an expected array, for example, signature bytes.
+ *
+ * If both arrays are null, the method returns true. The method return false when one array is null and the other not.
+ *
*
- * The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * @param data The data to search, maybe larger than the expected data.
+ * @param expected The expected data to find.
+ * @return whether a match was found.
+ * @since 3.18.0
+ */
+ public static boolean startsWith(final byte[] data, final byte[] expected) {
+ if (data == expected) {
+ return true;
+ }
+ if (data == null || expected == null) {
+ return false;
+ }
+ final int dataLen = data.length;
+ if (expected.length > dataLen) {
+ return false;
+ }
+ if (expected.length == dataLen) {
+ // delegate to Arrays.equals() which has optimizations on Java > 8
+ return Arrays.equals(data, expected);
+ }
+ // Once we are on Java 9+ we can delegate to Arrays here as well (or not).
+ for (int i = 0; i < expected.length; i++) {
+ if (data[i] != expected[i]) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
+ * Produces a new {@code boolean} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(boolean[], int, int)
*/
@@ -7645,39 +8153,26 @@ public static boolean[] subarray(final boolean[] array, int startIndexInclusive,
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_BOOLEAN_ARRAY;
}
-
- final boolean[] subarray = new boolean[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, boolean[]::new);
}
/**
- * Produces a new {@code byte} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code byte} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(byte[], int, int)
*/
@@ -7685,39 +8180,26 @@ public static byte[] subarray(final byte[] array, int startIndexInclusive, int e
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_BYTE_ARRAY;
}
-
- final byte[] subarray = new byte[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, byte[]::new);
}
/**
- * Produces a new {@code char} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code char} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(char[], int, int)
*/
@@ -7725,39 +8207,26 @@ public static char[] subarray(final char[] array, int startIndexInclusive, int e
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_CHAR_ARRAY;
}
-
- final char[] subarray = new char[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, char[]::new);
}
/**
- * Produces a new {@code double} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code double} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(double[], int, int)
*/
@@ -7765,39 +8234,26 @@ public static double[] subarray(final double[] array, int startIndexInclusive, i
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_DOUBLE_ARRAY;
}
-
- final double[] subarray = new double[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, double[]::new);
}
/**
- * Produces a new {@code float} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code float} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(float[], int, int)
*/
@@ -7805,39 +8261,26 @@ public static float[] subarray(final float[] array, int startIndexInclusive, int
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_FLOAT_ARRAY;
}
-
- final float[] subarray = new float[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, float[]::new);
}
/**
- * Produces a new {@code int} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code int} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(int[], int, int)
*/
@@ -7845,39 +8288,26 @@ public static int[] subarray(final int[] array, int startIndexInclusive, int end
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_INT_ARRAY;
}
-
- final int[] subarray = new int[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, int[]::new);
}
/**
- * Produces a new {@code long} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code long} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(long[], int, int)
*/
@@ -7885,39 +8315,26 @@ public static long[] subarray(final long[] array, int startIndexInclusive, int e
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_LONG_ARRAY;
}
-
- final long[] subarray = new long[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, long[]::new);
}
/**
- * Produces a new {@code short} array containing the elements
- * between the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
+ * Produces a new {@code short} array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
*
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(short[], int, int)
*/
@@ -7925,50 +8342,36 @@ public static short[] subarray(final short[] array, int startIndexInclusive, int
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
if (newSize <= 0) {
return EMPTY_SHORT_ARRAY;
}
-
- final short[] subarray = new short[newSize];
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, short[]::new);
}
- // Subarrays
- //-----------------------------------------------------------------------
/**
- * Produces a new array containing the elements between
- * the start and end indices.
- *
- *
The start index is inclusive, the end index exclusive.
- * Null array input produces null output.
- *
- *
The component type of the subarray is always the same as
- * that of the input array. Thus, if the input is an array of type
- * {@code Date}, the following usage is envisaged:
+ * Produces a new array containing the elements between the start and end indices.
+ *
+ * The start index is inclusive, the end index exclusive. Null array input produces null output.
+ *
+ *
+ * The component type of the subarray is always the same as that of the input array. Thus, if the input is an array of type {@link Date}, the following
+ * usage is envisaged:
+ *
*
*
+ *
* Date[] someDates = (Date[]) ArrayUtils.subarray(allDates, 2, 5);
*
*
- * @param the component type of the array
- * @param array the array
- * @param startIndexInclusive the starting index. Undervalue (<0)
- * is promoted to 0, overvalue (>array.length) results
- * in an empty array.
- * @param endIndexExclusive elements up to endIndex-1 are present in the
- * returned subarray. Undervalue (< startIndex) produces
- * empty array, overvalue (>array.length) is demoted to
- * array length.
- * @return a new array containing the elements between
- * the start and end indices.
+ * @param the component type of the array.
+ * @param array The input array.
+ * @param startIndexInclusive The starting index. Undervalue (<0) is promoted to 0, overvalue (>array.length) results in an empty array.
+ * @param endIndexExclusive elements up to endIndex-1 are present in the returned subarray. Undervalue (< startIndex) produces empty array, overvalue
+ * (>array.length) is demoted to array length.
+ * @return A new array containing the elements between the start and end indices.
* @since 2.1
* @see Arrays#copyOfRange(Object[], int, int)
*/
@@ -7976,24 +8379,14 @@ public static T[] subarray(final T[] array, int startIndexInclusive, int end
if (array == null) {
return null;
}
- if (startIndexInclusive < 0) {
- startIndexInclusive = 0;
- }
- if (endIndexExclusive > array.length) {
- endIndexExclusive = array.length;
- }
+ startIndexInclusive = max0(startIndexInclusive);
+ endIndexExclusive = max0(Math.min(endIndexExclusive, array.length));
final int newSize = endIndexExclusive - startIndexInclusive;
- final Class type = array.getClass().getComponentType();
+ final Class type = getComponentType(array);
if (newSize <= 0) {
- @SuppressWarnings("unchecked") // OK, because array is of type T
- final T[] emptyArray = (T[]) Array.newInstance(type, 0);
- return emptyArray;
+ return newInstance(type, 0);
}
- @SuppressWarnings("unchecked") // OK, because array is of type T
- final
- T[] subarray = (T[]) Array.newInstance(type, newSize);
- System.arraycopy(array, startIndexInclusive, subarray, 0, newSize);
- return subarray;
+ return arraycopy(array, startIndexInclusive, 0, newSize, () -> newInstance(type, newSize));
}
/**
@@ -8012,15 +8405,12 @@ public static T[] subarray(final T[] array, int startIndexInclusive, int end
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final boolean[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8042,22 +8432,18 @@ public static void swap(final boolean[] array, final int offset1, final int offs
* ArrayUtils.swap([true, false, true, false], 0, 3, 3) -> [false, false, true, true]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final boolean[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final boolean aux = array[offset1];
@@ -8066,7 +8452,6 @@ public static void swap(final boolean[] array, int offset1, int offset2, int len
}
}
-
/**
* Swaps two elements in the given byte array.
*
@@ -8083,15 +8468,12 @@ public static void swap(final boolean[] array, int offset1, int offset2, int len
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final byte[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8113,22 +8495,18 @@ public static void swap(final byte[] array, final int offset1, final int offset2
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final byte[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final byte aux = array[offset1];
@@ -8153,15 +8531,12 @@ public static void swap(final byte[] array, int offset1, int offset2, int len) {
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final char[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8183,22 +8558,18 @@ public static void swap(final char[] array, final int offset1, final int offset2
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final char[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final char aux = array[offset1];
@@ -8223,15 +8594,12 @@ public static void swap(final char[] array, int offset1, int offset2, int len) {
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final double[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8253,22 +8621,18 @@ public static void swap(final double[] array, final int offset1, final int offse
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final double[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final double aux = array[offset1];
@@ -8293,15 +8657,12 @@ public static void swap(final double[] array, int offset1, int offset2, int len
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final float[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8323,22 +8684,18 @@ public static void swap(final float[] array, final int offset1, final int offset
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final float[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final float aux = array[offset1];
@@ -8364,15 +8721,12 @@ public static void swap(final float[] array, int offset1, int offset2, int len)
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final int[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8394,22 +8748,18 @@ public static void swap(final int[] array, final int offset1, final int offset2)
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final int[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final int aux = array[offset1];
@@ -8434,16 +8784,12 @@ public static void swap(final int[] array, int offset1, int offset2, int len) {
* ArrayUtils.swap([true, false, true], -1, 1) -> [false, true, true]
*
*
- *
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final long[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8465,22 +8811,18 @@ public static void swap(final long[] array, final int offset1, final int offset2
* ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final long[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final long aux = array[offset1];
@@ -8489,8 +8831,6 @@ public static void swap(final long[] array, int offset1, int offset2, int len)
}
}
- // Swap
- //-----------------------------------------------------------------------
/**
* Swaps two elements in the given array.
*
@@ -8507,15 +8847,12 @@ public static void swap(final long[] array, int offset1, int offset2, int len)
* ArrayUtils.swap(["1", "2", "3"], -1, 1) -> ["2", "1", "3"]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final Object[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
@@ -8537,22 +8874,18 @@ public static void swap(final Object[] array, final int offset1, final int offse
* ArrayUtils.swap(["1", "2", "3", "4"], 0, 3, 3) -> ["4", "2", "3", "1"]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
* @since 3.5
*/
public static void swap(final Object[] array, int offset1, int offset2, int len) {
if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
return;
}
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
for (int i = 0; i < len; i++, offset1++, offset2++) {
final Object aux = array[offset1];
@@ -8577,70 +8910,61 @@ public static void swap(final Object[] array, int offset1, int offset2, int len
* ArrayUtils.swap([1, 2, 3], -1, 1) -> [2, 1, 3]
*
*
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element to swap
- * @param offset2 the index of the second element to swap
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element to swap.
+ * @param offset2 The index of the second element to swap.
* @since 3.5
*/
public static void swap(final short[] array, final int offset1, final int offset2) {
- if (isEmpty(array)) {
- return;
- }
swap(array, offset1, offset2, 1);
}
/**
- * Swaps a series of elements in the given short array.
- *
- * This method does nothing for a {@code null} or empty input array or
- * for overflow indices. Negative indices are promoted to 0(zero). If any
- * of the sub-arrays to swap falls outside of the given array, then the
- * swap is stopped at the end of the array and as many as possible elements
- * are swapped.
- *
- * Examples:
- *
- * ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]
- * ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]
- * ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]
- * ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -> [3, 4, 1, 2]
- * ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
- *
- *
- * @param array the array to swap, may be {@code null}
- * @param offset1 the index of the first element in the series to swap
- * @param offset2 the index of the second element in the series to swap
- * @param len the number of elements to swap starting with the given indices
- * @since 3.5
- */
- public static void swap(final short[] array, int offset1, int offset2, int len) {
- if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
- return;
- }
- if (offset1 < 0) {
- offset1 = 0;
- }
- if (offset2 < 0) {
- offset2 = 0;
- }
- if (offset1 == offset2) {
- return;
- }
- len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
- for (int i = 0; i < len; i++, offset1++, offset2++) {
- final short aux = array[offset1];
- array[offset1] = array[offset2];
- array[offset2] = aux;
- }
+ * Swaps a series of elements in the given short array.
+ *
+ * This method does nothing for a {@code null} or empty input array or
+ * for overflow indices. Negative indices are promoted to 0(zero). If any
+ * of the sub-arrays to swap falls outside of the given array, then the
+ * swap is stopped at the end of the array and as many as possible elements
+ * are swapped.
+ *
+ * Examples:
+ *
+ * ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]
+ * ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]
+ * ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]
+ * ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -> [3, 4, 1, 2]
+ * ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> [4, 2, 3, 1]
+ *
+ *
+ * @param array The array to swap, may be {@code null}.
+ * @param offset1 The index of the first element in the series to swap.
+ * @param offset2 The index of the second element in the series to swap.
+ * @param len The number of elements to swap starting with the given indices.
+ * @since 3.5
+ */
+ public static void swap(final short[] array, int offset1, int offset2, int len) {
+ if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
+ return;
+ }
+ offset1 = max0(offset1);
+ offset2 = max0(offset2);
+ if (offset1 == offset2) {
+ return;
+ }
+ len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
+ for (int i = 0; i < len; i++, offset1++, offset2++) {
+ final short aux = array[offset1];
+ array[offset1] = array[offset2];
+ array[offset2] = aux;
}
+ }
- // Generic array
- //-----------------------------------------------------------------------
/**
- * Create a type-safe generic array.
- *
- *
The Java language does not allow an array to be created from a generic type:
- *
+ * Create a type-safe generic array.
+ *
+ * The Java language does not allow an array to be created from a generic type:
+ *
*
public static <T> T[] createAnArray(int size) {
return new T[size]; // compiler error here
@@ -8649,60 +8973,56 @@ public static void swap(final short[] array, int offset1, int offset2, int len)
return (T[]) new Object[size]; // ClassCastException at runtime
}
*
- *
- * Therefore new arrays of generic types can be created with this method.
+ *
+ * Therefore new arrays of generic types can be created with this method.
* For example, an array of Strings can be created:
- *
- *
- String[] array = ArrayUtils.toArray("1", "2");
- String[] emptyArray = ArrayUtils.<String>toArray();
- *
- *
- * The method is typically used in scenarios, where the caller itself uses generic types
+ *
+ * {@code
+ * String[] array = ArrayUtils.toArray("1", "2");
+ * String[] emptyArray = ArrayUtils.toArray();
+ * }
+ *
+ * The method is typically used in scenarios, where the caller itself uses generic types
* that have to be combined into an array.
- *
- *
Note, this method makes only sense to provide arguments of the same type so that the
+ *
+ *
+ * Note, this method makes only sense to provide arguments of the same type so that the
* compiler can deduce the type of the array itself. While it is possible to select the
* type explicitly like in
- * {@code Number[] array = ArrayUtils.<Number>toArray(Integer.valueOf(42), Double.valueOf(Math.PI))},
+ * {@code Number[] array = ArrayUtils.toArray(Integer.valueOf(42), Double.valueOf(Math.PI))},
* there is no real advantage when compared to
* {@code new Number[] {Integer.valueOf(42), Double.valueOf(Math.PI)}}.
+ *
*
- * @param the array's element type
- * @param items the varargs array items, null allowed
- * @return the array, not null unless a null array is passed in
- * @since 3.0
+ * @param the array's element type.
+ * @param items the varargs array items, null allowed.
+ * @return The array, not null unless a null array is passed in.
+ * @since 3.0
*/
public static T[] toArray(@SuppressWarnings("unchecked") final T... items) {
return items;
}
- // To map
- //-----------------------------------------------------------------------
/**
- * Converts the given array into a {@link java.util.Map}. Each element of the array
- * must be either a {@link java.util.Map.Entry} or an Array, containing at least two
- * elements, where the first element is used as key and the second as
- * value.
+ * Converts the given array into a {@link java.util.Map}. Each element of the array must be either a {@link java.util.Map.Entry} or an Array, containing at
+ * least two elements, where the first element is used as key and the second as value.
+ *
+ * This method can be used to initialize:
+ *
*
- * This method can be used to initialize:
*
+ *
* // Create a Map mapping colors.
- * Map colorMap = ArrayUtils.toMap(new String[][] {
- * {"RED", "#FF0000"},
- * {"GREEN", "#00FF00"},
- * {"BLUE", "#0000FF"}});
+ * Map colorMap = ArrayUtils.toMap(new String[][] { { "RED", "#FF0000" }, { "GREEN", "#00FF00" }, { "BLUE", "#0000FF" } });
*
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * This method returns {@code null} for a {@code null} input array.
- *
- * @param array an array whose elements are either a {@link java.util.Map.Entry} or
- * an Array containing at least two elements, may be {@code null}
- * @return a {@code Map} that was created from the array
- * @throws IllegalArgumentException if one element of this Array is
- * itself an Array containing less then two elements
- * @throws IllegalArgumentException if the array contains elements other
- * than {@link java.util.Map.Entry} and an Array
+ * @param array An array whose elements are either a {@link java.util.Map.Entry} or an Array containing at least two elements, may be {@code null}.
+ * @return A {@link Map} that was created from the array.
+ * @throws IllegalArgumentException if one element of this Array is itself an Array containing less than two elements.
+ * @throws IllegalArgumentException if the array contains elements other than {@link java.util.Map.Entry} and an Array.
*/
public static Map toMap(final Object[] array) {
if (array == null) {
@@ -8732,235 +9052,205 @@ public static Map toMap(final Object[] array) {
}
/**
- * Converts an array of primitive booleans to objects.
+ * Converts an array of primitive booleans to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code boolean} array
- * @return a {@code Boolean} array, {@code null} if null array input
+ * @param array A {@code boolean} array.
+ * @return A {@link Boolean} array, {@code null} if null array input.
*/
public static Boolean[] toObject(final boolean[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_BOOLEAN_OBJECT_ARRAY;
}
- final Boolean[] result = new Boolean[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = (array[i] ? Boolean.TRUE : Boolean.FALSE);
+ if (array.length == 0) {
+ return EMPTY_BOOLEAN_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Boolean[array.length], i -> array[i] ? Boolean.TRUE : Boolean.FALSE);
}
/**
- * Converts an array of primitive bytes to objects.
+ * Converts an array of primitive bytes to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code byte} array
- * @return a {@code Byte} array, {@code null} if null array input
+ * @param array A {@code byte} array.
+ * @return A {@link Byte} array, {@code null} if null array input.
*/
public static Byte[] toObject(final byte[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_BYTE_OBJECT_ARRAY;
}
- final Byte[] result = new Byte[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Byte.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_BYTE_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Byte[array.length], i -> Byte.valueOf(array[i]));
}
/**
- * Converts an array of primitive chars to objects.
+ * Converts an array of primitive chars to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code char} array
- * @return a {@code Character} array, {@code null} if null array input
+ * @param array A {@code char} array.
+ * @return A {@link Character} array, {@code null} if null array input.
*/
public static Character[] toObject(final char[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_CHARACTER_OBJECT_ARRAY;
}
- final Character[] result = new Character[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Character.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_CHARACTER_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Character[array.length], i -> Character.valueOf(array[i]));
}
/**
- * Converts an array of primitive doubles to objects.
+ * Converts an array of primitive doubles to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code double} array
- * @return a {@code Double} array, {@code null} if null array input
+ * @param array A {@code double} array.
+ * @return A {@link Double} array, {@code null} if null array input.
*/
public static Double[] toObject(final double[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_DOUBLE_OBJECT_ARRAY;
}
- final Double[] result = new Double[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Double.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_DOUBLE_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Double[array.length], i -> Double.valueOf(array[i]));
}
/**
- * Converts an array of primitive floats to objects.
+ * Converts an array of primitive floats to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code float} array
- * @return a {@code Float} array, {@code null} if null array input
+ * @param array A {@code float} array.
+ * @return A {@link Float} array, {@code null} if null array input.
*/
public static Float[] toObject(final float[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_FLOAT_OBJECT_ARRAY;
}
- final Float[] result = new Float[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Float.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_FLOAT_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Float[array.length], i -> Float.valueOf(array[i]));
}
/**
- * Converts an array of primitive ints to objects.
+ * Converts an array of primitive ints to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array an {@code int} array
- * @return an {@code Integer} array, {@code null} if null array input
+ * @param array An {@code int} array.
+ * @return An {@link Integer} array, {@code null} if null array input.
*/
public static Integer[] toObject(final int[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_INTEGER_OBJECT_ARRAY;
}
- final Integer[] result = new Integer[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Integer.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_INTEGER_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Integer[array.length], i -> Integer.valueOf(array[i]));
}
/**
- * Converts an array of primitive longs to objects.
+ * Converts an array of primitive longs to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code long} array
- * @return a {@code Long} array, {@code null} if null array input
+ * @param array A {@code long} array.
+ * @return A {@link Long} array, {@code null} if null array input.
*/
public static Long[] toObject(final long[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_LONG_OBJECT_ARRAY;
}
- final Long[] result = new Long[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Long.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_LONG_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Long[array.length], i -> Long.valueOf(array[i]));
}
/**
- * Converts an array of primitive shorts to objects.
+ * Converts an array of primitive shorts to objects.
*
- *
This method returns {@code null} for a {@code null} input array.
+ *
This method returns {@code null} for a {@code null} input array.
*
- * @param array a {@code short} array
- * @return a {@code Short} array, {@code null} if null array input
+ * @param array A {@code short} array.
+ * @return A {@link Short} array, {@code null} if null array input.
*/
public static Short[] toObject(final short[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_SHORT_OBJECT_ARRAY;
}
- final Short[] result = new Short[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = Short.valueOf(array[i]);
+ if (array.length == 0) {
+ return EMPTY_SHORT_OBJECT_ARRAY;
}
- return result;
+ return setAll(new Short[array.length], i -> Short.valueOf(array[i]));
}
- // Boolean array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Booleans to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Booleans to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
+ *
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
+ *
*
- * @param array a {@code Boolean} array, may be {@code null}
- * @return a {@code boolean} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Boolean} array, may be {@code null}.
+ * @return A {@code boolean} array, {@code null} if null array input.
*/
public static boolean[] toPrimitive(final Boolean[] array) {
- if (array == null) {
- return null;
- } else if (array.length == 0) {
- return EMPTY_BOOLEAN_ARRAY;
- }
- final boolean[] result = new boolean[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = array[i].booleanValue();
- }
- return result;
+ return toPrimitive(array, false);
}
/**
- * Converts an array of object Booleans to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Booleans to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Boolean} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code boolean} array, {@code null} if null array input
+ * @param array A {@link Boolean} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code boolean} array, {@code null} if null array input.
*/
public static boolean[] toPrimitive(final Boolean[] array, final boolean valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_BOOLEAN_ARRAY;
}
final boolean[] result = new boolean[array.length];
for (int i = 0; i < array.length; i++) {
final Boolean b = array[i];
- result[i] = (b == null ? valueForNull : b.booleanValue());
+ result[i] = b == null ? valueForNull : b.booleanValue();
}
return result;
}
- // Byte array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Bytes to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Bytes to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Byte} array, may be {@code null}
- * @return a {@code byte} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Byte} array, may be {@code null}.
+ * @return A {@code byte} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static byte[] toPrimitive(final Byte[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_BYTE_ARRAY;
}
final byte[] result = new byte[array.length];
@@ -8971,43 +9261,45 @@ public static byte[] toPrimitive(final Byte[] array) {
}
/**
- * Converts an array of object Bytes to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Bytes to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Byte} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code byte} array, {@code null} if null array input
+ * @param array A {@link Byte} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code byte} array, {@code null} if null array input.
*/
public static byte[] toPrimitive(final Byte[] array, final byte valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_BYTE_ARRAY;
}
final byte[] result = new byte[array.length];
for (int i = 0; i < array.length; i++) {
final Byte b = array[i];
- result[i] = (b == null ? valueForNull : b.byteValue());
+ result[i] = b == null ? valueForNull : b.byteValue();
}
return result;
}
- // Character array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Characters to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Characters to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Character} array, may be {@code null}
- * @return a {@code char} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Character} array, may be {@code null}.
+ * @return A {@code char} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static char[] toPrimitive(final Character[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_CHAR_ARRAY;
}
final char[] result = new char[array.length];
@@ -9018,43 +9310,45 @@ public static char[] toPrimitive(final Character[] array) {
}
/**
- * Converts an array of object Character to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Character to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Character} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code char} array, {@code null} if null array input
+ * @param array A {@link Character} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code char} array, {@code null} if null array input.
*/
public static char[] toPrimitive(final Character[] array, final char valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_CHAR_ARRAY;
}
final char[] result = new char[array.length];
for (int i = 0; i < array.length; i++) {
final Character b = array[i];
- result[i] = (b == null ? valueForNull : b.charValue());
+ result[i] = b == null ? valueForNull : b.charValue();
}
return result;
}
- // Double array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Doubles to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Doubles to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Double} array, may be {@code null}
- * @return a {@code double} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Double} array, may be {@code null}.
+ * @return A {@code double} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static double[] toPrimitive(final Double[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_DOUBLE_ARRAY;
}
final double[] result = new double[array.length];
@@ -9065,43 +9359,45 @@ public static double[] toPrimitive(final Double[] array) {
}
/**
- * Converts an array of object Doubles to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Doubles to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Double} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code double} array, {@code null} if null array input
+ * @param array A {@link Double} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code double} array, {@code null} if null array input.
*/
public static double[] toPrimitive(final Double[] array, final double valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_DOUBLE_ARRAY;
}
final double[] result = new double[array.length];
for (int i = 0; i < array.length; i++) {
final Double b = array[i];
- result[i] = (b == null ? valueForNull : b.doubleValue());
+ result[i] = b == null ? valueForNull : b.doubleValue();
}
return result;
}
- // Float array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Floats to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Floats to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Float} array, may be {@code null}
- * @return a {@code float} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Float} array, may be {@code null}.
+ * @return A {@code float} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static float[] toPrimitive(final Float[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_FLOAT_ARRAY;
}
final float[] result = new float[array.length];
@@ -9112,43 +9408,45 @@ public static float[] toPrimitive(final Float[] array) {
}
/**
- * Converts an array of object Floats to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Floats to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Float} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code float} array, {@code null} if null array input
+ * @param array A {@link Float} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code float} array, {@code null} if null array input.
*/
public static float[] toPrimitive(final Float[] array, final float valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_FLOAT_ARRAY;
}
final float[] result = new float[array.length];
for (int i = 0; i < array.length; i++) {
final Float b = array[i];
- result[i] = (b == null ? valueForNull : b.floatValue());
+ result[i] = b == null ? valueForNull : b.floatValue();
}
return result;
}
- // Int array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Integers to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Integers to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Integer} array, may be {@code null}
- * @return an {@code int} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Integer} array, may be {@code null}.
+ * @return An {@code int} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static int[] toPrimitive(final Integer[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_INT_ARRAY;
}
final int[] result = new int[array.length];
@@ -9159,43 +9457,45 @@ public static int[] toPrimitive(final Integer[] array) {
}
/**
- * Converts an array of object Integer to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Integer to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Integer} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return an {@code int} array, {@code null} if null array input
+ * @param array A {@link Integer} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return An {@code int} array, {@code null} if null array input.
*/
public static int[] toPrimitive(final Integer[] array, final int valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_INT_ARRAY;
}
final int[] result = new int[array.length];
for (int i = 0; i < array.length; i++) {
final Integer b = array[i];
- result[i] = (b == null ? valueForNull : b.intValue());
+ result[i] = b == null ? valueForNull : b.intValue();
}
return result;
}
- // Long array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Longs to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Longs to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Long} array, may be {@code null}
- * @return a {@code long} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Long} array, may be {@code null}.
+ * @return A {@code long} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static long[] toPrimitive(final Long[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_LONG_ARRAY;
}
final long[] result = new long[array.length];
@@ -9206,35 +9506,38 @@ public static long[] toPrimitive(final Long[] array) {
}
/**
- * Converts an array of object Long to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Long to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Long} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code long} array, {@code null} if null array input
+ * @param array A {@link Long} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code long} array, {@code null} if null array input.
*/
public static long[] toPrimitive(final Long[] array, final long valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_LONG_ARRAY;
}
final long[] result = new long[array.length];
for (int i = 0; i < array.length; i++) {
final Long b = array[i];
- result[i] = (b == null ? valueForNull : b.longValue());
+ result[i] = b == null ? valueForNull : b.longValue();
}
return result;
}
/**
- * Create an array of primitive type from an array of wrapper types.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Create an array of primitive type from an array of wrapper types.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array an array of wrapper object
- * @return an array of the corresponding primitive type, or the original array
+ * @param array An array of wrapper object.
+ * @return An array of the corresponding primitive type, or the original array.
* @since 3.5
*/
public static Object toPrimitive(final Object array) {
@@ -9243,6 +9546,15 @@ public static Object toPrimitive(final Object array) {
}
final Class ct = array.getClass().getComponentType();
final Class pt = ClassUtils.wrapperToPrimitive(ct);
+ if (Boolean.TYPE.equals(pt)) {
+ return toPrimitive((Boolean[]) array);
+ }
+ if (Character.TYPE.equals(pt)) {
+ return toPrimitive((Character[]) array);
+ }
+ if (Byte.TYPE.equals(pt)) {
+ return toPrimitive((Byte[]) array);
+ }
if (Integer.TYPE.equals(pt)) {
return toPrimitive((Integer[]) array);
}
@@ -9261,21 +9573,21 @@ public static Object toPrimitive(final Object array) {
return array;
}
- // Short array converters
- // ----------------------------------------------------------------------
/**
- * Converts an array of object Shorts to primitives.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Shorts to primitives.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Short} array, may be {@code null}
- * @return a {@code byte} array, {@code null} if null array input
- * @throws NullPointerException if array content is {@code null}
+ * @param array A {@link Short} array, may be {@code null}.
+ * @return A {@code byte} array, {@code null} if null array input.
+ * @throws NullPointerException if an array element is {@code null}.
*/
public static short[] toPrimitive(final Short[] array) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_SHORT_ARRAY;
}
final short[] result = new short[array.length];
@@ -9286,125 +9598,110 @@ public static short[] toPrimitive(final Short[] array) {
}
/**
- * Converts an array of object Short to primitives handling {@code null}.
- *
- *
This method returns {@code null} for a {@code null} input array.
+ * Converts an array of object Short to primitives handling {@code null}.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array a {@code Short} array, may be {@code null}
- * @param valueForNull the value to insert if {@code null} found
- * @return a {@code byte} array, {@code null} if null array input
+ * @param array A {@link Short} array, may be {@code null}.
+ * @param valueForNull The value to insert if {@code null} found.
+ * @return A {@code byte} array, {@code null} if null array input.
*/
public static short[] toPrimitive(final Short[] array, final short valueForNull) {
if (array == null) {
return null;
- } else if (array.length == 0) {
+ }
+ if (array.length == 0) {
return EMPTY_SHORT_ARRAY;
}
final short[] result = new short[array.length];
for (int i = 0; i < array.length; i++) {
final Short b = array[i];
- result[i] = (b == null ? valueForNull : b.shortValue());
+ result[i] = b == null ? valueForNull : b.shortValue();
}
return result;
}
- // Basic methods handling multi-dimensional arrays
- //-----------------------------------------------------------------------
/**
- * Outputs an array as a String, treating {@code null} as an empty array.
- *
- *
Multi-dimensional arrays are handled correctly, including
+ * Outputs an array as a String, treating {@code null} as an empty array.
+ *
+ * Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays.
+ *
+ *
+ * The format is that of Java source code, for example {@code {a,b}}.
+ *
*
- * The format is that of Java source code, for example {@code {a,b}}.
- *
- * @param array the array to get a toString for, may be {@code null}
- * @return a String representation of the array, '{}' if null array input
+ * @param array The array to get a toString for, may be {@code null}.
+ * @return A String representation of the array, '{}' if null array input.
*/
public static String toString(final Object array) {
return toString(array, "{}");
}
/**
- *
Outputs an array as a String handling {@code null}s.
- *
- *
Multi-dimensional arrays are handled correctly, including
+ * Outputs an array as a String handling {@code null}s.
+ *
+ * Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays.
+ *
+ *
+ * The format is that of Java source code, for example {@code {a,b}}.
+ *
*
- * The format is that of Java source code, for example {@code {a,b}}.
- *
- * @param array the array to get a toString for, may be {@code null}
- * @param stringIfNull the String to return if the array is {@code null}
- * @return a String representation of the array
+ * @param array The array to get a toString for, may be {@code null}.
+ * @param stringIfNull The String to return if the array is {@code null}.
+ * @return A String representation of the array.
*/
public static String toString(final Object array, final String stringIfNull) {
- if (array == null) {
- return stringIfNull;
- }
- return new ToStringBuilder(array, ToStringStyle.SIMPLE_STYLE).append(array).toString();
+ return array != null ? new ToStringBuilder(array, ToStringStyle.SIMPLE_STYLE).append(array).toString() : stringIfNull;
}
/**
- *
Returns an array containing the string representation of each element in the argument array.
- *
- * This method returns {@code null} for a {@code null} input array.
+ * Returns an array containing the string representation of each element in the argument array.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the {@code Object[]} to be processed, may be null
- * @return {@code String[]} of the same size as the source with its element's string representation,
- * {@code null} if null array input
- * @throws NullPointerException if array contains {@code null}
+ * @param array The {@code Object[]} to be processed, may be {@code null}.
+ * @return {@code String[]} of the same size as the source with its element's string representation, {@code null} if null array input.
* @since 3.6
*/
public static String[] toStringArray(final Object[] array) {
- if (array == null) {
- return null;
- } else if (array.length == 0) {
- return EMPTY_STRING_ARRAY;
- }
-
- final String[] result = new String[array.length];
- for (int i = 0; i < array.length; i++) {
- result[i] = array[i].toString();
- }
-
- return result;
+ return toStringArray(array, "null");
}
/**
- * Returns an array containing the string representation of each element in the argument
- * array handling {@code null} elements.
- *
- * This method returns {@code null} for a {@code null} input array.
+ * Returns an array containing the string representation of each element in the argument array handling {@code null} elements.
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param array the Object[] to be processed, may be null
- * @param valueForNullElements the value to insert if {@code null} is found
- * @return a {@code String} array, {@code null} if null array input
+ * @param array The Object[] to be processed, may be {@code null}.
+ * @param valueForNullElements The value to insert if {@code null} is found.
+ * @return A {@link String} array, {@code null} if null array input.
* @since 3.6
*/
public static String[] toStringArray(final Object[] array, final String valueForNullElements) {
- if (null == array) {
+ if (array == null) {
return null;
- } else if (array.length == 0) {
- return EMPTY_STRING_ARRAY;
}
-
- final String[] result = new String[array.length];
- for (int i = 0; i < array.length; i++) {
- final Object object = array[i];
- result[i] = (object == null ? valueForNullElements : object.toString());
+ if (array.length == 0) {
+ return EMPTY_STRING_ARRAY;
}
-
- return result;
+ return map(array, String.class, e -> Objects.toString(e, valueForNullElements));
}
/**
- * ArrayUtils instances should NOT be constructed in standard programming.
- * Instead, the class should be used as {@code ArrayUtils.clone(new int[] {2})}.
+ * ArrayUtils instances should NOT be constructed in standard programming. Instead, the class should be used as {@code ArrayUtils.clone(new int[] {2})}.
+ *
+ * This constructor is public to permit tools that require a JavaBean instance to operate.
+ *
*
- * This constructor is public to permit tools that require a JavaBean instance
- * to operate.
+ * @deprecated TODO Make private in 4.0.
*/
+ @Deprecated
public ArrayUtils() {
- super();
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/AutoCloseables.java b/src/main/java/org/apache/commons/lang3/AutoCloseables.java
new file mode 100644
index 00000000000..a62495fbad6
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/AutoCloseables.java
@@ -0,0 +1,146 @@
+/*
+ * 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.io.Closeable;
+import java.util.function.Consumer;
+
+import org.apache.commons.lang3.function.Consumers;
+import org.apache.commons.lang3.function.FailableConsumer;
+
+/**
+ * Static operations on {@link AutoCloseable}.
+ *
+ * For {@link Closeable}-specific methods, see Apache Commons IO's
+ * IOUtils .
+ *
+ *
+ * @since 3.21.0
+ */
+public class AutoCloseables {
+
+ /**
+ * Closes the given {@link AutoCloseable} as a null-safe operation.
+ *
+ * @param closeable The resource to close, may be null.
+ * @throws Exception Thrown if an error occurs.
+ */
+ public static void close(final AutoCloseable closeable) throws Exception {
+ if (closeable != null) {
+ closeable.close();
+ }
+ }
+
+ /**
+ * Closes the given {@link AutoCloseable} as a null-safe operation.
+ *
+ * @param closeable The resource to close, may be null.
+ * @param consumer Consume the Exception thrown by {@link AutoCloseable#close()}.
+ * @throws Exception As thrown by the consumer.
+ */
+ public static void close(final AutoCloseable closeable, final FailableConsumer consumer) throws Exception {
+ if (closeable != null) {
+ try {
+ closeable.close();
+ } catch (final Exception e) {
+ FailableConsumer.accept(consumer, e);
+ }
+ }
+ }
+
+ /**
+ * Closes an {@link AutoCloseable}, never throwing an {@link Exception}.
+ *
+ * Equivalent to {@link AutoCloseable#close()}, except any exceptions will be ignored.
+ *
+ *
+ * @param closeable The objects to close, may be null or already closed.
+ * @see Throwable#addSuppressed(Throwable)
+ */
+ public static void closeQuietly(final AutoCloseable closeable) {
+ closeQuietly(closeable, (Consumer) null);
+ }
+
+ /**
+ * Closes the given {@link AutoCloseable} as a null-safe operation while consuming Exception by the given {@code consumer}.
+ *
+ * @param closeable The resource to close, may be null.
+ * @param consumer Consumes the Exception thrown by {@link AutoCloseable#close()}.
+ */
+ public static void closeQuietly(final AutoCloseable closeable, final Consumer consumer) {
+ if (closeable != null) {
+ try {
+ closeable.close();
+ } catch (final Exception e) {
+ Consumers.accept(consumer, e);
+ }
+ }
+ }
+
+ /**
+ * Closes an iterable of {@link AutoCloseable}, never throwing an {@link Exception}.
+ *
+ * Equivalent calling {@link AutoCloseable#close()} on each element, except any exceptions will be ignored.
+ *
+ *
+ * @param closeables The objects to close, may be null or already closed.
+ * @see #closeQuietly(AutoCloseable)
+ */
+ public static void closeQuietly(final Iterable closeables) {
+ if (closeables != null) {
+ closeables.forEach(AutoCloseables::closeQuietly);
+ }
+ }
+
+ /**
+ * Closes a {@link Closeable} unconditionally and adds any exception thrown by the {@code close()} to the given Throwable.
+ *
+ * For example:
+ *
+ *
+ *
+ * AutoCloseable autoCloseable = ...;
+ * try {
+ * // process autoCloseable.
+ * } catch (Exception e) {
+ * // Handle exception.
+ * throw AutoCloseables.closeQuietlySuppress(autoCloseable, e);
+ * }
+ *
+ *
+ * Also consider using a try-with-resources statement where appropriate.
+ *
+ *
+ * @param The Throwable type.
+ * @param closeable The object to close, may be null or already closed.
+ * @param throwable Add the exception throw by the closeable to the given Throwable.
+ * @return The given Throwable.
+ * @see Throwable#addSuppressed(Throwable)
+ */
+ public static T closeQuietlySuppress(final Closeable closeable, final T throwable) {
+ closeQuietly(closeable, throwable::addSuppressed);
+ return throwable;
+ }
+
+ /**
+ * No instances needed.
+ */
+ private AutoCloseables() {
+ // empty
+ }
+}
diff --git a/src/main/java/org/apache/commons/lang3/BitField.java b/src/main/java/org/apache/commons/lang3/BitField.java
index dc70df4a5d8..28adb9ae9c8 100644
--- a/src/main/java/org/apache/commons/lang3/BitField.java
+++ b/src/main/java/org/apache/commons/lang3/BitField.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,
@@ -14,309 +14,425 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.lang3;
/**
- * Supports operations on bit-mapped fields. Instances of this class can be
- * used to store a flag or data within an {@code int}, {@code short} or
- * {@code byte}.
- *
- * Each {@code BitField} is constructed with a mask value, which indicates
- * the bits that will be used to store and retrieve the data for that field.
- * For instance, the mask {@code 0xFF} indicates the least-significant byte
- * should be used to store the data.
- *
- * As an example, consider a car painting machine that accepts
- * paint instructions as integers. Bit fields can be used to encode this:
- *
- *
- * // blue, green and red are 1 byte values (0-255) stored in the three least
- * // significant bytes
- * BitField blue = new BitField(0xFF);
- * BitField green = new BitField(0xFF00);
- * BitField red = new BitField(0xFF0000);
+ * Supports operations on bit-mapped fields. Instances of this class can be used to store a flag or data within an {@code int}, {@code short} or {@code byte}.
+ *
+ * Each {@link BitField} is constructed with a mask value, which indicates the bits that will be used to store and retrieve the data for that field. For
+ * instance, the mask {@code 0xFF} indicates the least-significant byte should be used to store the data.
+ *
+ *
+ * As an example, consider a car painting machine that accepts paint instructions as integers. Bit fields can be used to encode this:
+ *
*
- * // anyColor is a flag triggered if any color is used
- * BitField anyColor = new BitField(0xFFFFFF);
+ *
*
- * // isMetallic is a single bit flag
- * BitField isMetallic = new BitField(0x1000000);
- *
+ * // blue, green and red are 1 byte values (0-255) stored in the three least
+ * // significant bytes
+ * BitField blue = new BitField(0xFF);
*
- * Using these {@code BitField} instances, a paint instruction can be
- * encoded into an integer:
+ * BitField green = new BitField(0xFF00);
*
- *
- * int paintInstruction = 0;
- * paintInstruction = red.setValue(paintInstruction, 35);
- * paintInstruction = green.setValue(paintInstruction, 100);
- * paintInstruction = blue.setValue(paintInstruction, 255);
- *
+ * BitField red = new BitField(0xFF0000);
*
- * Flags and data can be retrieved from the integer:
+ * // anyColor is a flag triggered if any color is used
+ * BitField anyColor = new BitField(0xFFFFFF);
*
- *
- * // Prints true if red, green or blue is non-zero
- * System.out.println(anyColor.isSet(paintInstruction)); // prints true
+ * // isMetallic is a single bit flag
+ * BitField isMetallic = new BitField(0x1000000);
+ *
+ *
+ * Using these {@link BitField} instances, a paint instruction can be encoded into an integer:
+ *
*
- * // Prints value of red, green and blue
- * System.out.println(red.getValue(paintInstruction)); // prints 35
- * System.out.println(green.getValue(paintInstruction)); // prints 100
- * System.out.println(blue.getValue(paintInstruction)); // prints 255
+ *
+ * int paintInstruction = 0;
+ * paintInstruction = red.setValue(paintInstruction, 35);
+ * paintInstruction = green.setValue(paintInstruction, 100);
+ * paintInstruction = blue.setValue(paintInstruction, 255);
+ *
+ *
+ * Flags and data can be retrieved from the integer:
+ *
*
- * // Prints true if isMetallic was set
- * System.out.println(isMetallic.isSet(paintInstruction)); // prints false
- *
+ *
+ * // Prints true if red, green or blue is non-zero
+ * System.out.println(anyColor.isSet(paintInstruction)); // prints true
+ * // Prints value of red, green and blue
+ * System.out.println(red.getValue(paintInstruction)); // prints 35
+ * System.out.println(green.getValue(paintInstruction)); // prints 100
+ * System.out.println(blue.getValue(paintInstruction)); // prints 255
+ * // Prints true if isMetallic was set
+ * System.out.println(isMetallic.isSet(paintInstruction)); // prints false
+ *
*
* @since 2.0
*/
public class BitField {
- private final int _mask;
- private final int _shift_count;
+ private final long mask;
+
+ private final int shiftCount;
/**
- * Creates a BitField instance.
+ * Creates a BitField instance.
*
- * @param mask the mask specifying which bits apply to this
- * BitField. Bits that are set in this mask are the bits
- * that this BitField operates on
+ * @param mask The mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
*/
public BitField(final int mask) {
- _mask = mask;
- _shift_count = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask);
+ this.mask = Integer.toUnsignedLong(mask);
+ this.shiftCount = this.mask == 0 ? 0 : Long.numberOfTrailingZeros(this.mask);
}
/**
- * Obtains the value for the specified BitField, appropriately
- * shifted right.
+ * Creates a BitField instance.
+ *
+ * If any bit above bit 31 is set in the mask, the resulting field can only be used with the {@code long} holder accessors; the {@code int}, {@code short}
+ * and {@code byte} holder accessors throw {@link IllegalStateException} for such a field, because those holder types cannot contain the masked bits and
+ * would otherwise silently answer wrongly (shift counts are truncated mod 32 and negative holders are sign-extended into bits 32-63).
+ *
*
- * Many users of a BitField will want to treat the specified
- * bits as an int value, and will not want to be aware that the
- * value is stored as a BitField (and so shifted left so many
- * bits).
+ * @param mask The mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
+ * @since 3.21.0
+ */
+ public BitField(final long mask) {
+ this.mask = mask;
+ this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask);
+ }
+
+ /**
+ * Clears the bits.
*
- * @see #setValue(int,int)
- * @param holder the int data containing the bits we're interested
- * in
- * @return the selected bits, shifted right appropriately
+ * @param holder The int data containing the bits we're interested in.
+ * @return The value of holder with the specified bits cleared (set to {@code 0}).
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public int getValue(final int holder) {
- return getRawValue(holder) >> _shift_count;
+ public int clear(final int holder) {
+ return (int) (holder & ~intMask());
}
/**
- * Obtains the value for the specified BitField, appropriately
- * shifted right, as a short.
+ * Clears the bits.
*
- * Many users of a BitField will want to treat the specified
- * bits as an int value, and will not want to be aware that the
- * value is stored as a BitField (and so shifted left so many
- * bits).
+ * @param holder The long data containing the bits we're interested in.
+ * @return The value of holder with the specified bits cleared (set to {@code 0}).
+ * @since 3.21.0
+ */
+ public long clear(final long holder) {
+ return holder & ~mask;
+ }
+
+ /**
+ * Clears the bits.
*
- * @see #setShortValue(short,short)
- * @param holder the short data containing the bits we're
- * interested in
- * @return the selected bits, shifted right appropriately
+ * @param holder The byte data containing the bits we're interested in.
+ * @return The value of holder with the specified bits cleared (set to {@code 0}).
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public short getShortValue(final short holder) {
- return (short) getValue(holder);
+ public byte clearByte(final byte holder) {
+ return (byte) clear(holder);
+ }
+
+ /**
+ * Clears the bits.
+ *
+ * @param holder The short data containing the bits we're interested in.
+ * @return The value of holder with the specified bits cleared (set to {@code 0}).
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
+ */
+ public short clearShort(final short holder) {
+ return (short) clear(holder);
}
/**
- * Obtains the value for the specified BitField, unshifted.
+ * Gets the value for the specified BitField, unshifted.
*
- * @param holder the int data containing the bits we're
- * interested in
- * @return the selected bits
+ * @param holder The int data containing the bits we're interested in.
+ * @return The selected bits.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
public int getRawValue(final int holder) {
- return holder & _mask;
+ return (int) (holder & intMask());
}
/**
- * Obtains the value for the specified BitField, unshifted.
+ * Gets the value for the specified BitField, unshifted.
*
- * @param holder the short data containing the bits we're
- * interested in
- * @return the selected bits
+ * @param holder The long data containing the bits we're interested in.
+ * @return The selected bits.
+ * @since 3.21.0
+ */
+ public long getRawValue(final long holder) {
+ return holder & mask;
+ }
+
+ /**
+ * Obtains the value for the specified BitField, unshifted.
+ *
+ * @param holder The short data containing the bits we're interested in.
+ * @return The selected bits.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
public short getShortRawValue(final short holder) {
return (short) getRawValue(holder);
}
/**
- * Returns whether the field is set or not.
- *
- * This is most commonly used for a single-bit field, which is
- * often used to represent a boolean value; the results of using
- * it for a multi-bit field is to determine whether *any* of its
- * bits are set.
+ * Gets the value for the specified BitField, appropriately shifted right, as a short.
+ *
+ * Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and
+ * so shifted left so many bits).
+ *
*
- * @param holder the int data containing the bits we're interested
- * in
- * @return {@code true} if any of the bits are set,
- * else {@code false}
+ * @param holder The short data containing the bits we're interested in.
+ * @return The selected bits, shifted right appropriately.
+ * @see #setShortValue(short,short)
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public boolean isSet(final int holder) {
- return (holder & _mask) != 0;
+ public short getShortValue(final short holder) {
+ return (short) getValue(holder);
}
/**
- * Returns whether all of the bits are set or not.
+ * Gets the value for the specified BitField, appropriately shifted right.
+ *
+ * Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and
+ * so shifted left so many bits).
+ *
*
- * This is a stricter test than {@link #isSet(int)},
- * in that all of the bits in a multi-bit set must be set
- * for this method to return {@code true}.
- *
- * @param holder the int data containing the bits we're
- * interested in
- * @return {@code true} if all of the bits are set,
- * else {@code false}
+ * @param holder The int data containing the bits we're interested in.
+ * @return The selected bits, shifted right appropriately.
+ * @see #setValue(int,int)
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public boolean isAllSet(final int holder) {
- return (holder & _mask) == _mask;
+ public int getValue(final int holder) {
+ return getRawValue(holder) >>> shiftCount;
}
/**
- * Replaces the bits with new values.
+ * Gets the value for the specified BitField, appropriately shifted right.
+ *
+ * Many users of a BitField will want to treat the specified bits as an long value, and will not want to be aware that the value is stored as a BitField (and
+ * so shifted left so many bits).
+ *
*
- * @see #getValue(int)
- * @param holder the int data containing the bits we're
- * interested in
- * @param value the new value for the specified bits
- * @return the value of holder with the bits from the value
- * parameter replacing the old bits
+ * @param holder The long data containing the bits we're interested in.
+ * @return The selected bits, shifted right appropriately.
+ * @see #setValue(long,long)
+ * @since 3.21.0
*/
- public int setValue(final int holder, final int value) {
- return (holder & ~_mask) | ((value << _shift_count) & _mask);
+ public long getValue(final long holder) {
+ return getRawValue(holder) >>> shiftCount;
}
/**
- * Replaces the bits with new values.
+ * Verifies that this field's mask fits in an {@code int} holder before an {@code int}, {@code short} or {@code byte} accessor uses it.
+ *
+ * Without this check, a mask with bits above bit 31 makes the narrow accessors silently wrong: the {@code int} shift count is truncated mod 32, and a
+ * negative narrow holder is sign-extended to 64 bits before the {@code long} mask is applied, reporting above-bit-31 flags as set even though the holder
+ * type cannot contain them.
+ *
*
- * @see #getShortValue(short)
- * @param holder the short data containing the bits we're
- * interested in
- * @param value the new value for the specified bits
- * @return the value of holder with the bits from the value
- * parameter replacing the old bits
+ * @return the mask, guaranteed to fit in 32 bits.
+ * @throws IllegalStateException if the mask has bits set above bit 31.
*/
- public short setShortValue(final short holder, final short value) {
- return (short) setValue(holder, value);
+ private long intMask() {
+ if (mask >>> Integer.SIZE != 0) {
+ throw new IllegalStateException("BitField mask 0x" + Long.toHexString(mask) + " exceeds 32 bits; use the long accessors for this field.");
+ }
+ return mask;
}
/**
- * Clears the bits.
+ * Tests whether all of the bits are set or not.
+ *
+ * This is a stricter test than {@link #isSet(int)}, in that all of the bits in a multi-bit set must be set for this method to return {@code true}.
+ *
*
- * @param holder the int data containing the bits we're
- * interested in
- * @return the value of holder with the specified bits cleared
- * (set to {@code 0})
+ * @param holder The int data containing the bits we're interested in.
+ * @return {@code true} if all of the bits are set, else {@code false}.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public int clear(final int holder) {
- return holder & ~_mask;
+ public boolean isAllSet(final int holder) {
+ final long intMask = intMask();
+ return (holder & intMask) == intMask;
}
/**
- * Clears the bits.
+ * Tests whether all of the bits are set or not.
+ *
+ * This is a stricter test than {@link #isSet(long)}, in that all of the bits in a multi-bit set must be set for this method to return {@code true}.
+ *
*
- * @param holder the short data containing the bits we're
- * interested in
- * @return the value of holder with the specified bits cleared
- * (set to {@code 0})
+ * @param holder The long data containing the bits we're interested in.
+ * @return {@code true} if all of the bits are set, else {@code false}.
+ * @since 3.21.0
*/
- public short clearShort(final short holder) {
- return (short) clear(holder);
+ public boolean isAllSet(final long holder) {
+ return (holder & mask) == mask;
}
/**
- * Clears the bits.
+ * Tests whether the field is set or not.
+ *
+ * This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to
+ * determine whether any of its bits are set.
+ *
*
- * @param holder the byte data containing the bits we're
- * interested in
+ * @param holder The int data containing the bits we're interested in
+ * @return {@code true} if any of the bits are set, else {@code false}
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
+ */
+ public boolean isSet(final int holder) {
+ return (holder & intMask()) != 0;
+ }
+
+ /**
+ * Tests whether the field is set or not.
+ *
+ * This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to
+ * determine whether any of its bits are set.
+ *
*
- * @return the value of holder with the specified bits cleared
- * (set to {@code 0})
+ * @param holder The long data containing the bits we're interested in
+ * @return {@code true} if any of the bits are set, else {@code false}
+ * @since 3.21.0
*/
- public byte clearByte(final byte holder) {
- return (byte) clear(holder);
+ public boolean isSet(final long holder) {
+ return (holder & mask) != 0;
}
/**
- * Sets the bits.
+ * Sets the bits.
*
- * @param holder the int data containing the bits we're
- * interested in
- * @return the value of holder with the specified bits set
- * to {@code 1}
+ * @param holder The int data containing the bits we're interested in.
+ * @return The value of holder with the specified bits set to {@code 1}.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
public int set(final int holder) {
- return holder | _mask;
+ return (int) (holder | intMask());
}
/**
- * Sets the bits.
+ * Sets the bits.
*
- * @param holder the short data containing the bits we're
- * interested in
- * @return the value of holder with the specified bits set
- * to {@code 1}
+ * @param holder The long data containing the bits we're interested in.
+ * @return The value of holder with the specified bits set to {@code 1}.
+ * @since 3.21.0
*/
- public short setShort(final short holder) {
- return (short) set(holder);
+ public long set(final long holder) {
+ return holder | mask;
}
/**
- * Sets the bits.
+ * Sets a boolean BitField.
*
- * @param holder the byte data containing the bits we're
- * interested in
+ * @param holder The int data containing the bits we're interested in.
+ * @param flag indicating whether to set or clear the bits.
+ * @return The value of holder with the specified bits set or cleared.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
+ */
+ public int setBoolean(final int holder, final boolean flag) {
+ return flag ? set(holder) : clear(holder);
+ }
+
+ /**
+ * Sets a boolean BitField.
+ *
+ * @param holder The long data containing the bits we're interested in.
+ * @param flag indicating whether to set or clear the bits.
+ * @return The value of holder with the specified bits set or cleared.
+ * @since 3.21.0
+ */
+ public long setBoolean(final long holder, final boolean flag) {
+ return flag ? set(holder) : clear(holder);
+ }
+
+ /**
+ * Sets the bits.
*
- * @return the value of holder with the specified bits set
- * to {@code 1}
+ * @param holder The byte data containing the bits we're interested in
+ * @return The value of holder with the specified bits set to {@code 1}
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
public byte setByte(final byte holder) {
return (byte) set(holder);
}
/**
- * Sets a boolean BitField.
+ * Sets a boolean BitField.
*
- * @param holder the int data containing the bits we're
- * interested in
- * @param flag indicating whether to set or clear the bits
- * @return the value of holder with the specified bits set or
- * cleared
+ * @param holder The byte data containing the bits we're interested in.
+ * @param flag indicating whether to set or clear the bits.
+ * @return The value of holder with the specified bits set or cleared.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public int setBoolean(final int holder, final boolean flag) {
- return flag ? set(holder) : clear(holder);
+ public byte setByteBoolean(final byte holder, final boolean flag) {
+ return flag ? setByte(holder) : clearByte(holder);
+ }
+
+ /**
+ * Sets the bits.
+ *
+ * @param holder The short data containing the bits we're interested in.
+ * @return The value of holder with the specified bits set to {@code 1}.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
+ */
+ public short setShort(final short holder) {
+ return (short) set(holder);
}
/**
- * Sets a boolean BitField.
+ * Sets a boolean BitField.
*
- * @param holder the short data containing the bits we're
- * interested in
- * @param flag indicating whether to set or clear the bits
- * @return the value of holder with the specified bits set or
- * cleared
+ * @param holder The short data containing the bits we're interested in.
+ * @param flag indicating whether to set or clear the bits.
+ * @return The value of holder with the specified bits set or cleared.
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
public short setShortBoolean(final short holder, final boolean flag) {
return flag ? setShort(holder) : clearShort(holder);
}
/**
- * Sets a boolean BitField.
+ * Sets the bits with new values.
*
- * @param holder the byte data containing the bits we're
- * interested in
- * @param flag indicating whether to set or clear the bits
- * @return the value of holder with the specified bits set or
- * cleared
+ * @param holder The short data containing the bits we're interested in
+ * @param value The new value for the specified bits
+ * @return The value of holder with the bits from the value parameter replacing the old bits
+ * @see #getShortValue(short)
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
*/
- public byte setByteBoolean(final byte holder, final boolean flag) {
- return flag ? setByte(holder) : clearByte(holder);
+ public short setShortValue(final short holder, final short value) {
+ return (short) setValue(holder, value);
+ }
+
+ /**
+ * Sets the bits with new values.
+ *
+ * @param holder The int data containing the bits we're interested in.
+ * @param value The new value for the specified bits.
+ * @return The value of holder with the bits from the value parameter replacing the old bits.
+ * @see #getValue(int)
+ * @throws IllegalStateException if this field's mask has bits set above bit 31 (only possible via {@link #BitField(long)}) and so cannot be represented in this holder type.
+ */
+ public int setValue(final int holder, final int value) {
+ final long intMask = intMask();
+ return (int) (holder & ~intMask | value << shiftCount & intMask);
}
+ /**
+ * Sets the bits with new values.
+ *
+ * @param holder The long data containing the bits we're interested in.
+ * @param value The new value for the specified bits.
+ * @return The value of holder with the bits from the value parameter replacing the old bits.
+ * @see #getValue(long)
+ * @since 3.21.0
+ */
+ public long setValue(final long holder, final long value) {
+ return holder & ~mask | value << shiftCount & mask;
+ }
}
diff --git a/src/main/java/org/apache/commons/lang3/BooleanUtils.java b/src/main/java/org/apache/commons/lang3/BooleanUtils.java
index 9dbcc65634b..d25fc524ff3 100644
--- a/src/main/java/org/apache/commons/lang3/BooleanUtils.java
+++ b/src/main/java/org/apache/commons/lang3/BooleanUtils.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,98 +16,165 @@
*/
package org.apache.commons.lang3;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.function.Consumer;
+
import org.apache.commons.lang3.math.NumberUtils;
/**
- * Operations on boolean primitives and Boolean objects.
+ * Operations on boolean primitives and Boolean 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.0
*/
public class BooleanUtils {
+ private static final List BOOLEAN_LIST = Collections.unmodifiableList(Arrays.asList(Boolean.FALSE, Boolean.TRUE));
+
/**
- * {@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"}.
*
- * NOTE: This returns {@code null} and will throw a {@code NullPointerException}
- * if unboxed to a boolean.
+ * @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"}.
+ *
+ * @since 3.12.0
+ */
+ public static final String YES = "yes";
+
+ /**
+ * Performs an 'and' operation on a set of booleans.
*
*
- * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
- * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
- * BooleanUtils.negate(null) = 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
*
*
- * @param bool the Boolean to negate, may be null
- * @return the negated Boolean, or {@code null} if {@code null} input
+ * @param array An array of {@code 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 negate(final Boolean bool) {
- if (bool == null) {
- return null;
+ public static boolean and(final boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ for (final boolean element : array) {
+ if (!element) {
+ return false;
+ }
}
- return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
+ return true;
}
- // boolean Boolean methods
- //-----------------------------------------------------------------------
/**
- * 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.
*
- * BooleanUtils.isTrue(Boolean.TRUE) = true
- * BooleanUtils.isTrue(Boolean.FALSE) = false
- * BooleanUtils.isTrue(null) = false
+ * 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.and(null, null) = Boolean.FALSE
*
+ *
+ * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return 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
+ * @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 isTrue(final Boolean bool) {
- return Boolean.TRUE.equals(bool);
+ public static Boolean and(final Boolean... array) {
+ ObjectUtils.requireNonEmpty(array, "array");
+ return and(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
}
/**
- * Checks if a {@code Boolean} value is not {@code true},
- * handling {@code null} by returning {@code true}.
+ * Returns a new array of possible values (like an enum would).
*
- *
- * BooleanUtils.isNotTrue(Boolean.TRUE) = false
- * BooleanUtils.isNotTrue(Boolean.FALSE) = true
- * BooleanUtils.isNotTrue(null) = true
- *
+ * @return A new array of possible values (like an enum would).
+ * @since 3.12.0
+ */
+ public static Boolean[] booleanValues() {
+ return new Boolean[] {Boolean.FALSE, Boolean.TRUE};
+ }
+
+ /**
+ * Compares two {@code boolean} values. This is the same functionality as provided in Java 7.
*
- * @param bool the boolean to check, null returns {@code true}
- * @return {@code true} if the input is null or false
- * @since 2.3
+ * @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
*/
- public static boolean isNotTrue(final Boolean bool) {
- return !isTrue(bool);
+ public static int compare(final boolean x, final boolean y) {
+ if (x == y) {
+ return 0;
+ }
+ return x ? 1 : -1;
}
/**
- * Checks if a {@code Boolean} value is {@code false},
- * handling {@code null} by returning {@code false}.
+ * Performs the given action for each Boolean {@link BooleanUtils#values()}.
+ *
+ * @param action The action to be performed for each element
+ * @since 3.13.0
+ */
+ public static void forEach(final Consumer action) {
+ values().forEach(action);
+ }
+
+ /**
+ * Checks if a {@link Boolean} value is {@code false},
+ * handling {@code null} by returning {@code false}.
*
*
* BooleanUtils.isFalse(Boolean.TRUE) = false
@@ -115,7 +182,7 @@ public static boolean isNotTrue(final Boolean bool) {
* BooleanUtils.isFalse(null) = false
*
*
- * @param bool the boolean to check, null returns {@code false}
+ * @param bool The boolean to check, null returns {@code false}
* @return {@code true} only if the input is non-{@code null} and {@code false}
* @since 2.1
*/
@@ -124,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,7 +200,7 @@ public static boolean isFalse(final Boolean bool) {
* BooleanUtils.isNotFalse(null) = true
*
*
- * @param bool the boolean to check, null returns {@code true}
+ * @param bool The boolean to check, null returns {@code true}
* @return {@code true} if the input is {@code null} or {@code true}
* @since 2.3
*/
@@ -141,113 +208,218 @@ 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.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
+ * BooleanUtils.isTrue(Boolean.TRUE) = true
+ * BooleanUtils.isTrue(Boolean.FALSE) = false
+ * BooleanUtils.isTrue(null) = 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}
+ * @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;
}
- // Integer to Boolean methods
- //-----------------------------------------------------------------------
/**
- * Converts an int to a boolean using the convention that {@code zero}
- * is {@code false}, everything else is {@code 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.
+ *
+ *
+ * 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)));
+ }
+
+ /**
+ * 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}, everything else is {@code true}.
- *
+ * 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}, every other numeric value is {@code true}.
+ * 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 method may return {@code null} and may throw a {@code NullPointerException}
- * if unboxed to a {@code 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.
@@ -260,9 +432,9 @@ public static Boolean toBooleanObject(final Integer value) {
* BooleanUtils.toBoolean(2, 2, 0) = true
*
*
- * @param value the {@code Integer} to convert
- * @param trueValue the value to match for {@code true}
- * @param falseValue the value to match for {@code false}
+ * @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 {@code value} does not match neither
* {@code trueValue} no {@code falseValue}
@@ -278,7 +450,7 @@ public static boolean toBoolean(final int value, final int trueValue, final int
}
/**
- * 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
@@ -288,9 +460,9 @@ public static boolean toBoolean(final int value, final int trueValue, final int
* BooleanUtils.toBoolean(null, null, Integer.valueOf(0)) = true
*
*
- * @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 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}
* @return {@code true} or {@code false}
* @throws IllegalArgumentException if no match
*/
@@ -311,238 +483,235 @@ public static boolean toBoolean(final Integer value, final Integer trueValue, fi
}
/**
- * Converts an int to a Boolean specifying the conversion values.
+ * Converts a String to a boolean (optimized for performance).
*
- * NOTE: This method may return {@code null} and may throw a {@code NullPointerException}
- * if unboxed to a {@code boolean}.
+ * {@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
+ * (case insensitive) will return {@code true}. Otherwise,
+ * {@code false} is returned.
*
- * The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
- * finally for the {@code nullValue}.
+ * 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.
*
*
- * 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
+ * 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 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
+ * @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;
- }
- 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 method may return {@code null} and may throw a {@code NullPointerException}
- * if unboxed to a {@code boolean}.
+ * Converts a String to a Boolean throwing an exception if no match found.
*
- * The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
- * finally for the {@code nullValue}.
- **
*
- * 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
+ * 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;
}
- 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 true} is {@code 1} and {@code false} is {@code 0}.
+ * 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 true} is {@code 1} and {@code false} is {@code 0}.
+ * 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 method may return {@code null} and may throw a {@code NullPointerException}
+ *
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]
@@ -556,22 +725,24 @@ 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
*
*
- * @param str the String to check; upper and lower case are treated as the same
- * @return the Boolean value of the string, {@code null} if no match or {@code null} input
+ * @param str The String to check; upper and lower case are treated as the same
+ * @return The Boolean value of the string, {@code null} if no match or {@code null} input
*/
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) {
@@ -581,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;
@@ -594,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;
@@ -609,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;
@@ -627,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;
@@ -642,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;
@@ -655,9 +828,9 @@ 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 method may return {@code null} and may throw a {@code NullPointerException}
+ *
NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
* if unboxed to a {@code boolean}.
*
*
@@ -672,11 +845,11 @@ public static Boolean toBooleanObject(final String str) {
* 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}
- * @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
+ * @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}
+ * @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
*/
@@ -702,373 +875,309 @@ 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;
}
- 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 check
- * @return {@code 'yes'}, {@code 'no'}, or {@code null}
+ * @param bool The Boolean to convert
+ * @return one if Boolean.TRUE, zero if Boolean.FALSE, {@code null} if {@code null}
*/
- public static String toStringYesNo(final Boolean bool) {
- return toString(bool, "yes", "no", 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 a String returning one of the input Strings.
+ * Converts a Boolean to an Integer specifying the conversion values.
*
*
- * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
- * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
- * BooleanUtils.toString(null, "true", "false", null) = null;
+ * 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 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}
- * @param nullString the String to return if {@code null}, may be {@code null}
- * @return one of the three input Strings
+ * @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 String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
+ public static Integer toIntegerObject(final Boolean bool, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
if (bool == null) {
- return nullString;
+ return nullValue;
}
- return bool.booleanValue() ? trueString : falseString;
+ return bool.booleanValue() ? trueValue : falseValue;
}
- // boolean to String methods
- //-----------------------------------------------------------------------
/**
- * Converts a boolean to a String returning {@code 'true'}
- * or {@code 'false'}.
+ * Converts a boolean to a String returning one of the input Strings.
*
*
- * BooleanUtils.toStringTrueFalse(true) = "true"
- * BooleanUtils.toStringTrueFalse(false) = "false"
+ * BooleanUtils.toString(true, "true", "false") = "true"
+ * BooleanUtils.toString(false, "true", "false") = "false"
*
*
- * @param bool the Boolean to check
- * @return {@code 'true'}, {@code 'false'}, or {@code null}
+ * @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
*/
- public static String toStringTrueFalse(final boolean bool) {
- return toString(bool, "true", "false");
+ 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.
+ *
+ *
+ * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
+ * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
+ * BooleanUtils.toString(null, "true", "false", null) = null;
+ *
+ *
+ * @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}
+ * @param nullString The String to return if {@code null}, may be {@code null}
+ * @return one of the three input Strings
+ */
+ public static String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
+ if (bool == null) {
+ return nullString;
+ }
+ return bool.booleanValue() ? trueString : falseString;
}
/**
- * 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"
* BooleanUtils.toStringOnOff(false) = "off"
*
*
- * @param bool the Boolean to check
+ * @param bool The Boolean to check
* @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}
+ * @param bool The Boolean to check
+ * @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
+ * @param bool The Boolean to check
+ * @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' operation 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 the result of the logical 'and' operation. That is {@code false}
- * if any of the parameters is {@code false} and {@code true} otherwise.
- * @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' operation 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 the result of the logical 'and' operation. That is {@code false}
- * if any of the parameters is {@code false} and {@code true} otherwise.
- * @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' operation 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 any of the arguments is {@code true}, and it returns {@code false} otherwise.
- * @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) {
- 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' operation on an array of Booleans.
- *
- *
- * 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
- *
+ * Returns an unmodifiable list of Booleans {@code [false, true]}.
*
- * @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 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, 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 the result of the xor operations
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @param array An array of {@code boolean}s
+ * @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) {
- 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) {
@@ -1079,51 +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.FALSE, 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 the result of the xor operations
- * @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(final boolean x, final boolean y) {
- if (x == y) {
- return 0;
- }
- return x ? 1 : -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..e3e7f008ad0
--- /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 9f0d2e0ca55..75c61931a18 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,18 +19,19 @@
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.
@@ -40,57 +41,57 @@
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
+ * @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.
@@ -107,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 6a416bb632a..b1dbb9816cc 100644
--- a/src/main/java/org/apache/commons/lang3/CharRange.java
+++ b/src/main/java/org/apache/commons/lang3/CharRange.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,72 +16,138 @@
*/
package org.apache.commons.lang3;
+import java.io.IOException;
+import java.io.InvalidObjectException;
+import java.io.ObjectInputStream;
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
// 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;
+ private static final class CharacterIterator implements Iterator {
- /** 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;
+ /** The current character */
+ private char current;
- /** Cached toString. */
- private transient String iToString;
+ 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.isEmpty()) {
+ // This range is an empty set
+ hasNext = false;
+ } else if (range.negated) {
+ if (range.isStartMin()) {
+ current = (char) (range.end + 1);
+ } else {
+ current = Character.MIN_VALUE;
+ }
+ } 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.isEndMax()) {
+ 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;
- }
+ private static final long serialVersionUID = 2L;
- this.start = start;
- this.end = end;
- this.negated = negated;
- }
+ /** 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,97 +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.
+ *
+ * A negated range includes everything except that defined by the
+ * 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)
+ * @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) {
- Validate.isTrue(range != null, "The Range must not be null");
+ Objects.requireNonNull(range, "range");
if (negated) {
if (range.negated) {
return start >= range.start && end <= range.end;
@@ -187,19 +266,29 @@ public boolean contains(final CharRange range) {
return range.end < start || range.start > end;
}
if (range.negated) {
- return start == 0 && end == Character.MAX_VALUE;
+ // range denotes [0, range.start - 1] union [range.end + 1, Character.MAX_VALUE]
+ if (range.isEmpty()) {
+ return true; // range denotes the empty set
+ }
+ if (range.isStartMin()) {
+ // range denotes [range.end + 1, Character.MAX_VALUE]
+ return isEndMax() && start <= range.end + 1;
+ }
+ if (range.isEndMax()) {
+ // range denotes [0, range.start - 1]
+ return isStartMin() && end + 1 >= range.start;
+ }
+ return isStartMin() && isEndMax();
}
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.
+ * 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
+ * @param obj The object to compare to.
+ * @return true if equal.
*/
@Override
public boolean equals(final Object obj) {
@@ -214,44 +303,73 @@ public boolean equals(final Object obj) {
}
/**
- * Gets a hashCode compatible with the equals method.
+ * 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
+ * @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.
+ * Checks if this range denotes the empty set.
*
- * @return string representation of this range
+ * A plain (non-negated) range always contains at least one character and is
+ * therefore never empty. A negated range is empty if and only if it excludes the
+ * entire character space, i.e. if it was created via
+ * {@code isNotIn(Character.MIN_VALUE, Character.MAX_VALUE)}.
+ *
+ * @return {@code true} if this range contains no characters, {@code false} otherwise.
*/
- @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;
+ boolean isEmpty() {
+ return negated && isStartMin() && isEndMax();
+ }
+
+ private boolean isEndMax() {
+ return end == Character.MAX_VALUE;
+ }
+
+ /**
+ * Is this {@link CharRange} negated.
+ *
+ * A negated range includes everything except that defined by the
+ * start and end characters.
+ *
+ * @return {@code true} if negated.
+ */
+ public boolean isNegated() {
+ return negated;
+ }
+
+ private boolean isStartMin() {
+ return start == Character.MIN_VALUE;
}
- // 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
+ *
+ * @return An iterator to the chars represented by this range
* @since 2.5
*/
@Override
@@ -260,98 +378,40 @@ public Iterator iterator() {
}
/**
- * Character {@link Iterator}.
- * #NotThreadSafe#
+ * Re-asserts the {@code start <= end} invariant after default deserialization. The constructor reverses reversed endpoints, so a legitimately serialized
+ * instance always has {@code start <= end}; a stream that violates this did not come from the constructor and is rejected.
+ *
+ * @param in See {@link Serializable}.
+ * @throws IOException See {@link Serializable}.
+ * @throws ClassNotFoundException See {@link Serializable}.
+ * @throws InvalidObjectException If {@code start} is greater than {@code end}.
*/
- 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;
- }
+ private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
+ in.defaultReadObject();
+ if (start > end) {
+ throw new InvalidObjectException("CharRange start is greater than end.");
}
+ }
- /**
- * 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;
+ /**
+ * Gets a string representation of the character range.
+ *
+ * @return string representation of this range.
+ */
+ @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) {
- 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 58c04536e46..2d07f55bb5f 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
@@ -28,73 +28,120 @@ 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.
+ * Whether the running JDK folds a supplementary code point split across a surrogate pair when comparing case insensitively in
+ * {@link String#regionMatches(boolean, int, String, int, int)}. JDKs up to and including Java 11 compare surrogate by surrogate and never match such a
+ * pair; later JDKs fold the whole code point. Probing what {@link String} actually does (rather than gating on a version constant) keeps every
+ * {@link CharSequence} type in step with {@link String} on whatever JDK is running. DESERET CAPITAL LETTER LONG I (U+10400) folds to its small form
+ * (U+10428).
*/
- public CharSequenceUtils() {
- super();
+ private static final boolean STRING_FOLDS_SUPPLEMENTARY_CASE = new String(Character.toChars(0x10400)).regionMatches(true, 0,
+ new String(Character.toChars(0x10428)), 0, 2);
+
+ static final int TO_STRING_LIMIT = 16;
+
+ 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 true;
}
- //-----------------------------------------------------------------------
/**
- * Returns a new {@code CharSequence} that is a subsequence of this
- * sequence starting with the {@code char} value at the specified index.
+ * Tests whether two code points are equal ignoring case, matching the folding used by {@link String#regionMatches(boolean, int, String, int, int)}.
*
- * 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 cp1 The first code point.
+ * @param cp2 The second code point.
+ * @return whether the code points are equal ignoring case.
+ */
+ private static boolean equalsIgnoreCase(final int cp1, final int cp2) {
+ final int u1 = Character.toUpperCase(cp1);
+ final int u2 = Character.toUpperCase(cp2);
+ return u1 == u2 || Character.toLowerCase(u1) == Character.toLowerCase(u2);
+ }
+
+ /**
+ * Used by the indexOf(CharSequence methods) as a green implementation of indexOf.
+ *
+ * {@link CharSequence} types without a dedicated branch are scanned in place rather than materialized with {@code toString()}: for builder
+ * types (for example {@code org.apache.commons.lang3.text.StrBuilder}), {@code toString()} copies the whole buffer, and callers that invoke
+ * this method once per occurrence (such as {@code deleteAll}/{@code replaceAll}) would multiply that copy into allocation-quadratic churn.
+ *
*
- * @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()}
+ * @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.
*/
- public static CharSequence subSequence(final CharSequence cs, final int start) {
- return cs == null ? null : cs.subSequence(start, cs.length());
+ 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);
+ }
+ // Direct scan without copying cs; matches the semantics of String.indexOf(String, int).
+ final int len1 = cs.length();
+ final int len2 = searchChar.length();
+ final int from = Math.max(start, 0);
+ if (len2 == 0) {
+ return Math.min(from, len1);
+ }
+ if (len2 > len1 - from) {
+ return StringUtils.INDEX_NOT_FOUND;
+ }
+ final char char0 = searchChar.charAt(0);
+ final int max = len1 - len2;
+ for (int i = from; i <= max; i++) {
+ if (cs.charAt(i) == char0 && checkLaterThan1(cs, searchChar, len2, i)) {
+ return i;
+ }
+ }
+ return StringUtils.INDEX_NOT_FOUND;
}
- //-----------------------------------------------------------------------
/**
- * Returns the index within {@code cs} of the first occurrence of the
- * specified character, starting the search at the specified index.
+ * 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)
- * k such that:
- *
- * (this.codePointAt(k ) == searchChar) && (k >= start)
- * k such that:
+ *
*
+ *
+ * (this.charAt(k ) == searchChar) && (k >= start)
+ *
*
- * 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
- * {@code 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.
+ * is true. For other values of {@code searchChar}, it is the smallest value k such that:
+ *
*
- * All indices are specified in {@code char} values
- * (Unicode code units).
+ *
+ * (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 {@code CharSequence} to be processed, not null
- * @param searchChar the char to be searched for
- * @param start the start index, negative starts at the string start
- * @return the index where the search char was found, -1 if not found
- * @since 3.6 updated to behave more like {@code String}
+ * @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 indexOf(final CharSequence cs, final int searchChar, int start) {
if (cs instanceof String) {
@@ -110,6 +157,7 @@ static int indexOf(final CharSequence cs, final int searchChar, int start) {
return i;
}
}
+ return NOT_FOUND;
}
//supplementary characters (LANG1300)
if (searchChar <= Character.MAX_CODE_POINT) {
@@ -126,51 +174,106 @@ static int indexOf(final CharSequence cs, final int searchChar, int start) {
}
/**
- * Used by the indexOf(CharSequence methods) as a green implementation of indexOf.
+ * 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 indexOf(final CharSequence cs, final CharSequence searchChar, final int start) {
- return cs.toString().indexOf(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).indexOf((String) searchChar, start);
-// } else {
-// // TODO: Implement rather than convert to String
-// return cs.toString().indexOf(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;
+ }
+ }
}
/**
- * 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)
- * k such that:
- *
- * (this.codePointAt(k ) == searchChar) && (k <= start)
- * k such that:
*
- * All indices are specified in {@code char} values
- * (Unicode code units).
+ *
+ * (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
- * @param searchChar the char to be searched for
- * @param start the start index, negative returns -1, beyond length starts at end
- * @return the index where the search char was found, -1 if not found
- * @since 3.6 updated to behave more like {@code String}
+ *
+ * (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 int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
if (cs instanceof String) {
@@ -189,16 +292,15 @@ static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
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--) {
+ // A supplementary code point spans two chars, so its high surrogate can start no later
+ // than sz - 2; clamp the search origin instead of bailing out when start is the last index.
+ for (int i = Math.min(start, sz - 2); i >= 0; i--) {
final char high = cs.charAt(i);
final char low = cs.charAt(i + 1);
if (chars[0] == high && chars[1] == low) {
@@ -210,97 +312,146 @@ 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
- */
- 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);
-// }
- }
-
- /**
- * Green implementation of toCharArray.
+ * Tests if two string regions are equal.
*
- * @param cs the {@code CharSequence} to be processed
- * @return the resulting char array
+ * @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 char[] toCharArray(final CharSequence cs) {
- if (cs instanceof String) {
- return ((String) cs).toCharArray();
- }
- final int sz = cs.length();
- final char[] array = new char[cs.length()];
- for (int i = 0; i < sz; i++) {
- array[i] = cs.charAt(i);
- }
- return array;
- }
-
- /**
- * Green implementation of regionMatches.
- *
- * @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
- */
- 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++);
-
+ final int end1 = thisStart + length;
+ final int end2 = start + length;
+ int index1 = thisStart;
+ int index2 = start;
+ while (index1 < end1 && index2 < end2) {
+ final char c1 = cs.charAt(index1);
+ final char c2 = substring.charAt(index2);
if (c1 == c2) {
+ index1++;
+ index2++;
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)) {
- return false;
+ // The same case-insensitive check as String#regionMatches(boolean, int, String, int, int).
+ if (!equalsIgnoreCase(c1, c2)) {
+ // Only fold a supplementary code point split across a surrogate pair where String itself does, so
+ // every CharSequence type gives the same result that String does on the running JDK (see field).
+ if (!STRING_FOLDS_SUPPLEMENTARY_CASE) {
+ return false;
+ }
+ int cp1 = c1;
+ if (Character.isHighSurrogate(c1)) {
+ if (index1 + 1 < end1 && Character.isLowSurrogate(cs.charAt(index1 + 1))) {
+ cp1 = Character.toCodePoint(c1, cs.charAt(index1 + 1));
+ index1++;
+ }
+ } else if (Character.isLowSurrogate(c1) && index1 > thisStart && Character.isHighSurrogate(cs.charAt(index1 - 1))) {
+ cp1 = Character.toCodePoint(cs.charAt(index1 - 1), c1);
+ }
+ int cp2 = c2;
+ if (Character.isHighSurrogate(c2)) {
+ if (index2 + 1 < end2 && Character.isLowSurrogate(substring.charAt(index2 + 1))) {
+ cp2 = Character.toCodePoint(c2, substring.charAt(index2 + 1));
+ index2++;
+ }
+ } else if (Character.isLowSurrogate(c2) && index2 > start && Character.isHighSurrogate(substring.charAt(index2 - 1))) {
+ cp2 = Character.toCodePoint(substring.charAt(index2 - 1), c2);
+ }
+ if (!equalsIgnoreCase(cp1, cp2)) {
+ return false;
+ }
}
+ index1++;
+ index2++;
}
-
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 795511553ad..b2504323cd8 100644
--- a/src/main/java/org/apache/commons/lang3/CharSet.java
+++ b/src/main/java/org/apache/commons/lang3/CharSet.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,16 +19,18 @@
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 {
@@ -42,37 +44,45 @@ public class CharSet implements Serializable {
/**
* 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<>());
@@ -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,10 +115,10 @@ 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
@@ -148,13 +154,13 @@ public class CharSet implements Serializable {
*
*
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]);
@@ -165,24 +171,27 @@ public static CharSet getInstance(final String... 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.
+ * Lock object for synchronizing access.
+ */
+ private final Serializable lock = new SerializableObject();
+
+ /**
+ * 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();
- for (final String s : set) {
- add(s);
- }
+ 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
*/
@@ -190,7 +199,6 @@ protected void add(final String str) {
if (str == null) {
return;
}
-
final int len = str.length();
int pos = 0;
while (pos < len) {
@@ -215,49 +223,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[0]);
- }
-
- //-----------------------------------------------------------------------
- /**
- * 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) {
- synchronized(set) {
- for (final CharRange range : set) {
- if (range.contains(ch)) {
- return true;
- }
- }
+ synchronized (lock) {
+ 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
@@ -273,9 +271,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
@@ -284,9 +294,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 b3580b7c25d..bab79e081c7 100644
--- a/src/main/java/org/apache/commons/lang3/CharSetUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharSetUtils.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,22 +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 {
/**
- * 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
@@ -42,14 +45,14 @@ public class CharSetUtils {
* 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);
@@ -62,8 +65,8 @@ public static boolean containsAny(final String str, final String... set) {
}
/**
- * 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
@@ -74,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
+ * @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);
@@ -101,19 +104,12 @@ public static int count(final String str, final String... set) {
* @return whether or not the String is empty
*/
private static boolean deepEmpty(final String[] strings) {
- if (strings != null) {
- for (final String s : strings) {
- if (StringUtils.isNotEmpty(s)) {
- return false;
- }
- }
- }
- return true;
+ return Streams.of(strings).allMatch(StringUtils::isEmpty);
}
/**
- * 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
@@ -124,21 +120,25 @@ private static boolean deepEmpty(final String[] strings) {
* 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
+ * @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.
+ * Takes an argument in set-syntax, see evaluateSet,
+ * and keeps any of characters present in the specified string.
*
*
* CharSetUtils.keep(null, *) = null
@@ -149,10 +149,10 @@ public static String delete(final String str, final String... set) {
* CharSetUtils.keep("hello", "le") = "ell"
*
*
- * @see CharSet#getInstance(java.lang.String...) for set-syntax.
+ * @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
+ * @return The modified String, {@code null} if null string input
* @since 2.0
*/
public static String keep(final String str, final String... set) {
@@ -166,12 +166,12 @@ public static String keep(final String str, final String... set) {
}
/**
- * Implementation of delete and keep
+ * Implements delete and keep.
*
* @param str String to modify characters within
* @param set String[] set of characters to modify
* @param expect whether to evaluate on match, or non-match
- * @return the modified String, not null
+ * @return The modified String, not null
*/
private static String modify(final String str, final String[] set, final boolean expect) {
final CharSet chars = CharSet.getInstance(set);
@@ -186,8 +186,8 @@ private static String modify(final String str, final String[] set, final boolean
}
/**
- * Squeezes any repetitions of a character that is mentioned in the
- * supplied set.
+ * Squeezes any repetitions of a character that is mentioned in the
+ * supplied set.
*
*
* CharSetUtils.squeeze(null, *) = null
@@ -198,13 +198,13 @@ private static String modify(final String str, final String[] set, final boolean
* 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
+ * @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
*/
public static String squeeze(final String str, final String... set) {
- if (StringUtils.isEmpty(str) || deepEmpty(set)) {
+ if (isEmpty(str, set)) {
return str;
}
final CharSet chars = CharSet.getInstance(set);
@@ -212,7 +212,7 @@ public static String squeeze(final String str, final String... set) {
final char[] chrs = str.toCharArray();
final int sz = chrs.length;
char lastChar = chrs[0];
- char ch = ' ';
+ char ch;
Character inChars = null;
Character notInChars = null;
buffer.append(lastChar);
@@ -237,13 +237,15 @@ public static String squeeze(final String str, final String... set) {
}
/**
- * CharSetUtils instances should NOT be constructed in standard programming.
- * Instead, the class should be used as {@code CharSetUtils.evaluateSet(null);}.
+ * 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() {
- super();
}
}
diff --git a/src/main/java/org/apache/commons/lang3/CharUtils.java b/src/main/java/org/apache/commons/lang3/CharUtils.java
index 3c8ad3e6688..bb345a936d8 100644
--- a/src/main/java/org/apache/commons/lang3/CharUtils.java
+++ b/src/main/java/org/apache/commons/lang3/CharUtils.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,35 +16,38 @@
*/
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 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').
+ * Linefeed character LF ({@code '\n'}, Unicode 000a).
*
- * @see JLF: Escape Sequences
+ * @see JLF: Escape Sequences
* for Character and String Literals
* @since 2.2
*/
public static final char LF = '\n';
/**
- * {@code \u000d} carriage return CR ('\r').
+ * Carriage return character CR ('\r', Unicode 000d).
*
- * @see JLF: Escape Sequences
+ * @see JLF: Escape Sequences
* for Character and String Literals
* @since 2.2
*/
@@ -57,89 +60,287 @@ public class CharUtils {
*/
public static final char NUL = '\0';
- static {
- for (char c = 0; c < CHAR_STRING_ARRAY.length; c++) {
- CHAR_STRING_ARRAY[c] = String.valueOf(c);
- }
+ /**
+ * 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.
+ * Tests whether the character is ASCII 7 bit alphabetic.
*
- * For ASCII 7 bit characters, this uses a cache that will return the
- * same Character object each time.
+ *
+ * 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);
+ }
+
+ /**
+ * Tests whether the character is ASCII 7 bit alphabetic lower case.
*
*
- * CharUtils.toCharacterObject(' ') = ' '
- * CharUtils.toCharacterObject('A') = 'A'
+ * CharUtils.isAsciiAlphaLower('a') = true
+ * CharUtils.isAsciiAlphaLower('A') = false
+ * CharUtils.isAsciiAlphaLower('3') = false
+ * CharUtils.isAsciiAlphaLower('-') = false
+ * CharUtils.isAsciiAlphaLower('\n') = false
+ * CharUtils.isAsciiAlphaLower('©') = 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 97 and 122 inclusive
*/
- @Deprecated
- public static Character toCharacterObject(final char ch) {
- return Character.valueOf(ch);
+ public static boolean isAsciiAlphaLower(final char ch) {
+ return ch >= 'a' && ch <= 'z';
}
/**
- * Converts the String to a Character using the first character, returning
- * null for empty Strings.
+ * Tests whether the character is ASCII 7 bit alphanumeric character.
*
- * For ASCII 7 bit characters, this uses a cache that will return the
- * same Character object each time.
+ *
+ * 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.toCharacterObject(null) = null
- * CharUtils.toCharacterObject("") = null
- * CharUtils.toCharacterObject("A") = 'A'
- * CharUtils.toCharacterObject("BA") = 'B'
+ * CharUtils.isAsciiAlphaUpper('a') = false
+ * CharUtils.isAsciiAlphaUpper('A') = true
+ * CharUtils.isAsciiAlphaUpper('3') = false
+ * CharUtils.isAsciiAlphaUpper('-') = false
+ * CharUtils.isAsciiAlphaUpper('\n') = false
+ * CharUtils.isAsciiAlphaUpper('©') = 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 65 and 90 inclusive
*/
- public static Character toCharacterObject(final String str) {
- if (StringUtils.isEmpty(str)) {
- return null;
- }
- return Character.valueOf(str.charAt(0));
+ 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;
+ }
+
+ /**
+ * 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 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 code point to check.
+ * @return true if between 48 and 57 inclusive.
+ * @since 3.21.0
+ */
+ public static boolean isAsciiNumeric(final int 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 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 code point to test.
+ * @return true if character is a hexadecimal character.
+ * @since 3.21.0
+ */
+ public static boolean isHex(final int 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 byte to check.
+ * @return true if the given char is the character representation of one of the digits from 0 to 7.
+ * @since 3.21.0
+ */
+ public static boolean isOctal(final byte ch) {
+ return ch >= '0' && ch <= '7';
+ }
+
+ /**
+ * 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}.
+ * 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
+ * @param ch The character to convert
+ * @return The char value of the Character
+ * @throws NullPointerException if the Character is null
*/
public static char toChar(final Character ch) {
- Validate.isTrue(ch != null, "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'
@@ -147,41 +348,38 @@ public static char toChar(final Character ch) {
* CharUtils.toChar('A', 'X') = 'A'
*
*
- * @param ch the character to convert
- * @param defaultValue the value to use if the Character is null
- * @return the char value of the Character or the default if null
+ * @param ch The character to convert
+ * @param defaultValue The value to use if the Character is null
+ * @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
+ * @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) {
- Validate.isTrue(StringUtils.isNotEmpty(str), "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'
@@ -190,21 +388,50 @@ public static char toChar(final String str) {
* CharUtils.toChar("BA", 'X') = 'B'
*
*
- * @param str the character to convert
- * @param defaultValue the value to use if the Character is null
- * @return the char value of the first letter of the String or the default if null
+ * @param str The character to convert
+ * @param defaultValue The value to use if the Character is null
+ * @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.
+ * 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.
*
@@ -213,8 +440,8 @@ public static char toChar(final String str, final char defaultValue) {
* CharUtils.toIntValue('A') throws IllegalArgumentException
*
*
- * @param ch the character to convert
- * @return the int value of the character
+ * @param ch The character to convert
+ * @return The int value of the character
* @throws IllegalArgumentException if the character is not ASCII numeric
*/
public static int toIntValue(final char ch) {
@@ -225,8 +452,8 @@ public static int toIntValue(final char ch) {
}
/**
- * Converts the character to the Integer it represents, throwing an
- * exception if the character is not numeric.
+ * 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.
*
@@ -235,41 +462,38 @@ public static int toIntValue(final char ch) {
* CharUtils.toIntValue('A', -1) = -1
*
*
- * @param ch the character to convert
- * @param defaultValue the default value to use if the character is not numeric
- * @return the int value of the character
+ * @param ch The character to convert
+ * @param defaultValue The default value to use if the character is not numeric
+ * @return The int value of the character
*/
public static int toIntValue(final char ch, final int defaultValue) {
- if (!isAsciiNumeric(ch)) {
- 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.
+ * 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
+ * @param ch The character to convert, not null
+ * @return The int value of the character
+ * @throws NullPointerException if the Character is null
+ * @throws IllegalArgumentException if the Character is not ASCII numeric
*/
public static int toIntValue(final Character ch) {
- Validate.isTrue(ch != null, "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.
+ * 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.
*
@@ -279,20 +503,16 @@ public static int toIntValue(final Character ch) {
* CharUtils.toIntValue('A', -1) = -1
*
*
- * @param ch the character to convert
- * @param defaultValue the default value to use if the character is not numeric
- * @return the int value of the character
+ * @param ch The character to convert
+ * @param defaultValue The default value to use if the character is not numeric
+ * @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.
@@ -302,18 +522,18 @@ public static int toIntValue(final Character ch, final int defaultValue) {
* CharUtils.toString('A') = "A"
*
*
- * @param ch the character to convert
- * @return a String containing the one specified character
+ * @param ch The character to convert
+ * @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.
@@ -326,19 +546,15 @@ public static String toString(final char ch) {
* CharUtils.toString('A') = "A"
*
*
- * @param ch the character to convert
- * @return a String containing the one specified character
+ * @param ch The character to convert
+ * @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.
*
@@ -347,19 +563,19 @@ public static String toString(final Character ch) {
* CharUtils.unicodeEscaped('A') = "\u0041"
*
*
- * @param ch the character to convert
- * @return the escaped Unicode string
+ * @param ch The character to convert
+ * @return The escaped Unicode string
*/
public static String unicodeEscaped(final char ch) {
return "\\u" +
- HEX_DIGITS[(ch >> 12) & 15] +
- HEX_DIGITS[(ch >> 8) & 15] +
- HEX_DIGITS[(ch >> 4) & 15] +
- HEX_DIGITS[(ch) & 15];
+ 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.
*
@@ -371,180 +587,24 @@ public static String unicodeEscaped(final char ch) {
* CharUtils.unicodeEscaped('A') = "\u0041"
*
*
- * @param ch the character to convert, may be null
- * @return the escaped Unicode string, null if null input
+ * @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';
+ return ch != null ? unicodeEscaped(ch.charValue()) : null;
}
/**
- * 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
- *
+ * {@link CharUtils} instances should NOT be constructed in standard programming.
+ * Instead, the class should be used as {@code CharUtils.toString('c');}.
*
- * @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);
- }
-
- /**
- * Compares two {@code char} values numerically. This is the same functionality as provided in Java 7.
+ * This constructor is public to permit tools that require a JavaBean instance
+ * to operate.
*
- * @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
+ * @deprecated TODO Make private in 4.0.
*/
- public static int compare(final char x, final 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
index c80bb90a377..7f7c2ebe45d 100644
--- a/src/main/java/org/apache/commons/lang3/Charsets.java
+++ b/src/main/java/org/apache/commons/lang3/Charsets.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,
@@ -32,13 +32,13 @@
*
* @since 3.10
*/
-class Charsets {
+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.
+ * @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;
@@ -47,8 +47,8 @@ static Charset toCharset(final Charset 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.
+ * @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
*/
@@ -59,8 +59,8 @@ static Charset toCharset(final String 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.
+ * @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
index 95cdd2aabab..a970508dad1 100644
--- a/src/main/java/org/apache/commons/lang3/ClassLoaderUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ClassLoaderUtils.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,10 @@
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}.
@@ -27,27 +29,62 @@
*/
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 formated string.
+ * @return The formatted string.
*/
public static String toString(final ClassLoader classLoader) {
if (classLoader instanceof URLClassLoader) {
return toString((URLClassLoader) classLoader);
}
- return classLoader.toString();
+ return Objects.toString(classLoader);
}
/**
- * Converts the given URLClassLoader to a String in the format
- * {@code "URLClassLoader.toString() + [URL1, URL2, ...]"}.
+ * Converts the given URLClassLoader to a String in the format {@code "URLClassLoader.toString() + [URL1, URL2, ...]"}.
*
* @param classLoader to URLClassLoader to convert.
- * @return the formated string.
+ * @return The formatted string.
*/
public static String toString(final URLClassLoader classLoader) {
- return classLoader + Arrays.toString(classLoader.getURLs());
+ 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..4956ce08eec 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 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.
+ * @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 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 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.
+ * @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 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 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.
+ * @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 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 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.
+ * @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 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 4b90ab2973e..302d6269c54 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,41 +18,82 @@
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.regex.Pattern;
+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 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 Pattern ARRAY_TAIL_PATTERN = Pattern.compile("(?:\\[\\])+");
+
+ private static final Comparator> COMPARATOR = (o1, o2) -> Objects.compare(getName(o1), getName(o2), String::compareTo);
+
/**
* The package separator character: {@code '.' == {@value}}.
*/
@@ -74,411 +115,217 @@ public enum Interfaces {
public static final String INNER_CLASS_SEPARATOR = String.valueOf(INNER_CLASS_SEPARATOR_CHAR);
/**
- * Maps names of primitives to their corresponding primitive {@code Class}es.
+ * Maps names of primitives to their corresponding primitive {@link Class}es.
*/
- private static final Map> namePrimitiveMap = new HashMap<>();
+ private static final Map> NAME_PRIMITIVE_MAP = new HashMap<>();
+
static {
- namePrimitiveMap.put("boolean", Boolean.TYPE);
- namePrimitiveMap.put("byte", Byte.TYPE);
- namePrimitiveMap.put("char", Character.TYPE);
- namePrimitiveMap.put("short", Short.TYPE);
- namePrimitiveMap.put("int", Integer.TYPE);
- namePrimitiveMap.put("long", Long.TYPE);
- namePrimitiveMap.put("double", Double.TYPE);
- namePrimitiveMap.put("float", Float.TYPE);
- namePrimitiveMap.put("void", Void.TYPE);
+ 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 {@code Class}es to their corresponding wrapper {@code Class}.
+ * Maps primitive {@link Class}es to their corresponding wrapper {@link Class}.
*/
- private static final Map, Class> primitiveWrapperMap = new HashMap<>();
+ 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<>();
+ 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;
- // 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");
- 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);
- }
+ private static final Map REVERSE_ABBREVIATION_MAP;
- /**
- * 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();
+ /** Feed abbreviation maps. */
+ static {
+ 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 of the {@code object} without the package name or names.
- *
- * The method looks up the class of the object and then converts the name of the class invoking
- * {@link #getShortClassName(Class)} (see relevant notes there).
+ * Gets the class comparator, comparing by class name.
*
- * @param object the class to get the short name for, may be {@code null}
- * @param valueIfNull the value to return if the object is {@code null}
- * @return the class name of the object without the package name, or {@code valueIfNull}
- * if the argument {@code object} is {@code null}
+ * @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.
*
- * This method simply gets the name using {@code Class.getName()} and then calls
- * {@link #getShortClassName(Class)}. See relevant notes there.
+ *
+ * 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. If the class
- * is an inner class then the returned value will contain the outer class
- * or classes separated with {@code .} (dot) character.
+ * @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.
- *
- * The string passed in is assumed to be a class name - it is not checked. The string has to be formatted the way
- * as the JDK method {@code Class.getName()} returns it, and not the usual way as we write it, for example in import
- * statements, or as it is formatted by {@code Class.getCanonicalName()}.
- *
- * The difference is is significant only in case of classes that are inner classes of some other
- * classes. In this case the separator between the outer and inner class (possibly on multiple hierarchy level) has
- * to be {@code $} (dollar sign) and not {@code .} (dot), as it is returned by {@code Class.getName()}
- *
- * Note that this method is called from the {@link #getShortClassName(Class)} method using the string
- * returned by {@code Class.getName()}.
+ * Given a {@link List} of class names, this method converts them into classes.
*
- * Note that this method differs from {@link #getSimpleName(Class)} in that this will
- * return, for example {@code "Map.Entry"} whilst the {@code java.lang.Class} variant will simply
- * return {@code "Entry"}. In this example the argument {@code className} is the string
- * {@code java.util.Map$Entry} (note the {@code $} sign.
+ *
+ * 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. It has to be formatted as returned by
- * {@code Class.getName()} and not {@code Class.getCanonicalName()}
- * @return the class name of the class without the package name or an empty string. If the class is
- * an inner class then value contains the outer class or classes and the separator is replaced
- * to be {@code .} (dot) character.
+ * @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;
- }
-
- /**
- * Null-safe version of {@code cls.getSimpleName()}
- *
- * @param cls the class for which to get the simple name; may be null
- * @return the simple class name or the empty string in case the argument is {@code null}
- * @since 3.0
- * @see Class#getSimpleName()
- */
- public static String getSimpleName(final Class cls) {
- return getSimpleName(cls, StringUtils.EMPTY);
- }
-
- /**
- * Null-safe version of {@code cls.getSimpleName()}
- *
- * @param cls the class for which to get the simple name; may be null
- * @param valueIfNull the value to return if null
- * @return the simple class name or {@code valueIfNull} if the
- * argument {@code cls} is {@code null}
- * @since 3.0
- * @see Class#getSimpleName()
- */
- public static String getSimpleName(final Class cls, String valueIfNull) {
- return cls == null ? valueIfNull : cls.getSimpleName();
- }
-
- /**
- * Null-safe version of {@code object.getClass().getSimpleName()}
- *
- * It is to note that this method is overloaded and in case the argument {@code object} is a
- * {@code Class} object then the {@link #getSimpleName(Class)} will be invoked. If this is
- * a significant possibility then the caller should check this case and call {@code
- * getSimpleName(Class.class)} or just simply use the string literal {@code "Class"}, which
- * is the result of the method in that case.
- *
- * @param object the object for which to get the simple class name; may be null
- * @return the simple class name or the empty string in case the argument is {@code null}
- * @since 3.7
- * @see Class#getSimpleName()
- */
- public static String getSimpleName(final Object object) {
- return getSimpleName(object, StringUtils.EMPTY);
- }
-
- /**
- * Null-safe version of {@code object.getClass().getSimpleName()}
- *
- * @param object the object for which to get the simple class name; may be null
- * @param valueIfNull the value to return if {@code object} is {@code null}
- * @return the simple class name or {@code valueIfNull} if the
- * argument {@code object} is {@code null}
- * @since 3.0
- * @see Class#getSimpleName()
- */
- public static String getSimpleName(final Object object, final String valueIfNull) {
- return object == null ? valueIfNull : object.getClass().getSimpleName();
- }
-
- /**
- * Null-safe version of {@code cls.getName()}
- *
- * @param cls the class for which to get the class name; may be null
- * @return the class name or the empty string in case the argument is {@code null}
- * @since 3.7
- * @see Class#getSimpleName()
- */
- public static String getName(final Class cls) {
- return getName(cls, StringUtils.EMPTY);
- }
-
- /**
- * Null-safe version of {@code cls.getName()}
- *
- * @param cls the class for which to get the class name; may be null
- * @param valueIfNull the return value if the argument {@code cls} is {@code null}
- * @return the class name or {@code valueIfNull}
- * @since 3.7
- * @see Class#getName()
- */
- public static String getName(final Class cls, final String valueIfNull) {
- return cls == null ? valueIfNull : cls.getName();
- }
-
- /**
- * Null-safe version of {@code object.getClass().getName()}
- *
- * @param object the object for which to get the class name; may be null
- * @return the class name or the empty String
- * @since 3.7
- * @see Class#getSimpleName()
- */
- public static String getName(final Object object) {
- return getName(object, StringUtils.EMPTY);
- }
-
- /**
- * Null-safe version of {@code object.getClass().getSimpleName()}
- *
- * @param object the object for which to get the class name; may be null
- * @param valueIfNull the value to return if {@code object} is {@code null}
- * @return the class name or {@code valueIfNull}
- * @since 3.0
- * @see Class#getName()
- */
- public static String getName(final Object object, final String valueIfNull) {
- return object == null ? valueIfNull : object.getClass().getName();
- }
-
- // Package name
- // ----------------------------------------------------------------------
- /**
- * Gets the package name of an {@code Object}.
- *
- * @param object the class to get the package name for, may be null
- * @param valueIfNull the value to return if null
- * @return the package name of the object, or the null value
- */
- public static String getPackageName(final Object object, final String valueIfNull) {
- if (object == null) {
- return valueIfNull;
- }
- return getPackageName(object.getClass());
- }
-
- /**
- * Gets the package name of a {@code Class}.
- *
- * @param cls the class to get the package name for, may be {@code null}.
- * @return the package name or an empty string
- */
- public static String getPackageName(final Class cls) {
- if (cls == null) {
- return StringUtils.EMPTY;
- }
- return getPackageName(cls.getName());
- }
-
- /**
- * Gets the package name from a {@code String}.
- *
- * The string passed in is assumed to be a class name - it is not checked.
- * If the class is unpackaged, return an empty string.
- *
- * @param className the className to get the package name for, may be {@code null}
- * @return the package name or an empty string
- */
- public static String getPackageName(String className) {
- if (StringUtils.isEmpty(className)) {
- return StringUtils.EMPTY;
- }
-
- // Strip array encoding
- while (className.charAt(0) == '[') {
- className = className.substring(1);
- }
- // Strip Object type encoding
- if (className.charAt(0) == 'L' && className.charAt(className.length() - 1) == ';') {
- className = className.substring(1);
- }
-
- final int i = className.lastIndexOf(PACKAGE_SEPARATOR_CHAR);
- if (i == -1) {
- return StringUtils.EMPTY;
- }
- return className.substring(0, i);
+ });
+ return classes;
}
- // Abbreviated name
- // ----------------------------------------------------------------------
/**
- * Gets the abbreviated name of a {@code Class}.
+ * Gets the abbreviated name of a {@link Class}.
*
- * @param cls the class to get the abbreviated name for, may be {@code null}
- * @param lengthHint the desired length of the abbreviated name
- * @return the abbreviated name or an empty string
- * @throws IllegalArgumentException if len <= 0
+ * @param cls The class to get the abbreviated name for, may be {@code null}.
+ * @param lengthHint The desired length of the abbreviated name.
+ * @return The abbreviated name or an empty string.
+ * @throws IllegalArgumentException if len <= 0.
* @see #getAbbreviatedName(String, int)
* @since 3.4
*/
public static String getAbbreviatedName(final Class cls, final int lengthHint) {
- if (cls == null) {
- return StringUtils.EMPTY;
- }
- return getAbbreviatedName(cls.getName(), lengthHint);
+ if (cls == null) {
+ return StringUtils.EMPTY;
+ }
+ return getAbbreviatedName(cls.getName(), lengthHint);
}
/**
- * Gets the abbreviated class name from a {@code String}.
+ * Gets the abbreviated class name from a {@link String}.
*
- * The string passed in is assumed to be a class name - it is not checked.
+ *
+ * The string passed in is assumed to be a class name - it is not checked.
+ *
*
- * The abbreviation algorithm will shorten the class name, usually without
- * significant loss of meaning.
+ *
+ * The abbreviation algorithm will shorten the class name, usually without significant loss of meaning.
+ *
*
- * The abbreviated class name will always include the complete package hierarchy.
- * If enough space is available, rightmost sub-packages will be displayed in full
- * length. The abbreviated package names will be shortened to a single character.
- * Only package names are shortened, the class simple name remains untouched. (See examples.)
- * The result will be longer than the desired length only if all the package names
- * shortened to a single character plus the class simple name with the separating dots
- * together are longer than the desired length. In other words, when the class name
- * cannot be shortened to the desired length.
- * If the class name can be shortened then
- * the final length will be at most {@code lengthHint} characters.
- * If the {@code lengthHint} is zero or negative then the method
- * throws exception. If you want to achieve the shortest possible version then
- * use {@code 1} as a {@code lengthHint}.
+ *
+ * The abbreviated class name will always include the complete package hierarchy. If enough space is available,
+ * rightmost sub-packages will be displayed in full length. The abbreviated package names will be shortened to a single
+ * character.
+ *
+ *
+ * Only package names are shortened, the class simple name remains untouched. (See examples.)
+ *
+ *
+ * The result will be longer than the desired length only if all the package names shortened to a single character plus
+ * the class simple name with the separating dots together are longer than the desired length. In other words, when the
+ * class name cannot be shortened to the desired length.
+ *
+ *
+ * If the class name can be shortened then the final length will be at most {@code lengthHint} characters.
+ *
+ *
+ * If the {@code lengthHint} is zero or negative then the method throws exception. If you want to achieve the shortest
+ * possible version then use {@code 1} as a {@code lengthHint}.
+ *
*
*
* Examples
- * className len return null 1 "" "java.lang.String" 5 "j.l.String" "java.lang.String" 15 "j.lang.String" "java.lang.String" 30 "java.lang.String" "org.apache.commons.lang3.ClassUtils" 18 "o.a.c.l.ClassUtils"
+ * className
+ * len
+ * return
+ *
+ *
+ * null
+ * 1
+ * ""
+ *
+ *
+ * "java.lang.String"
+ * 5
+ * "j.l.String"
+ *
+ *
+ * "java.lang.String"
+ * 15
+ * "j.lang.String"
+ *
+ *
+ * "java.lang.String"
+ * 30
+ * "java.lang.String"
+ *
+ *
+ * "org.apache.commons.lang3.ClassUtils"
+ * 18
+ * "o.a.c.l.ClassUtils"
+ *
*
*
- * @param className the className to get the abbreviated name for, may be {@code null}
- * @param lengthHint the desired length of the abbreviated name
- * @return the abbreviated name or an empty string if the specified
- * class name is {@code null} or empty string. The abbreviated name may be
- * longer than the desired length if it cannot be abbreviated to the desired length.
- * @throws IllegalArgumentException if {@code len <= 0}
+ * @param className The className to get the abbreviated name for, may be {@code null}.
+ * @param lengthHint The desired length of the abbreviated name.
+ * @return The abbreviated name or an empty string if the specified class name is {@code null} or empty string. The
+ * abbreviated name may be longer than the desired length if it cannot be abbreviated to the desired length.
+ * @throws IllegalArgumentException if {@code len <= 0}.
* @since 3.4
*/
public static String getAbbreviatedName(final String className, final int lengthHint) {
@@ -502,8 +349,7 @@ public static String getAbbreviatedName(final String className, final int length
}
++target;
- if (useFull(runAheadTarget, source, abbreviated.length, lengthHint)
- || target > runAheadTarget) {
+ if (useFull(runAheadTarget, source, abbreviated.length, lengthHint) || target > runAheadTarget) {
target = runAheadTarget;
}
@@ -516,1046 +362,1513 @@ public static String getAbbreviatedName(final String className, final int length
}
/**
- * Decides if the part that was just copied to its destination
- * location in the work array can be kept as it was copied or must be
- * abbreviated. It must be kept when the part is the last one, which
- * is the simple name of the class. In this case the {@code source}
- * index, from where the characters are copied points one position
- * after the last character, a.k.a. {@code source ==
- * originalLength}
- *
- * If the part is not the last one then it can be kept
- * unabridged if the number of the characters copied so far plus
- * the character that are to be copied is less than or equal to the
- * desired length.
- *
- * @param runAheadTarget the target index (where the characters were
- * copied to) pointing after the last character
- * copied when the current part was copied
- * @param source the source index (where the characters were
- * copied from) pointing after the last
- * character copied when the current part was
- * copied
- * @param originalLength the original length of the class full name,
- * which is abbreviated
- * @param desiredLength the desired length of the abbreviated class
- * name
- * @return {@code true} if it can be kept in its original length
- * {@code false} if the current part has to be abbreviated and
- */
- private static boolean useFull(final int runAheadTarget,
- final int source,
- final int originalLength,
- final int desiredLength) {
- return source >= originalLength ||
- runAheadTarget + originalLength - source <= desiredLength;
- }
-
- // Superclasses/Superinterfaces
- // ----------------------------------------------------------------------
- /**
- * Gets a {@code List} of superclasses for the given class.
- *
- * @param cls the class to look up, may be {@code null}
- * @return the {@code List} of superclasses in order going up from this one
- * {@code null} if null input
- */
- public static List> getAllSuperclasses(final Class cls) {
- if (cls == null) {
- return null;
- }
- final List> classes = new ArrayList<>();
- Class superclass = cls.getSuperclass();
- while (superclass != null) {
- classes.add(superclass);
- superclass = superclass.getSuperclass();
- }
- return classes;
- }
-
- /**
- * Gets a {@code List} of all interfaces implemented by the given
- * class and its superclasses.
+ * Gets a {@link List} of all interfaces implemented by the given class and its superclasses.
*
- * The order is determined by looking through each interface in turn as
- * declared in the source file and following its hierarchy up. Then each
- * superclass is considered in the same way. Later duplicates are ignored,
- * so the order is maintained.
+ *
+ * The order is determined by looking through each interface in turn as declared in the source file and following its
+ * hierarchy up. Then each superclass is considered in the same way. Later duplicates are ignored, so the order is
+ * maintained.
+ *
*
- * @param cls the class to look up, may be {@code null}
- * @return the {@code List} of interfaces in order,
- * {@code null} if null input
+ * @param cls The class to look up, may be {@code null}.
+ * @return The {@link List} of interfaces in order, {@code null} if null input.
*/
public static List> getAllInterfaces(final Class cls) {
if (cls == null) {
return null;
}
-
final LinkedHashSet> interfacesFound = new LinkedHashSet<>();
getAllInterfaces(cls, interfacesFound);
-
return new ArrayList<>(interfacesFound);
}
/**
- * Get the interfaces for the specified class.
+ * Gets the interfaces for the specified class.
*
- * @param cls the class to look up, may be {@code null}
- * @param interfacesFound the {@code Set} of interfaces for the class
+ * @param cls The class to look up, may be {@code null}.
+ * @param interfacesFound The {@link Set} of interfaces for the class.
*/
- private static void getAllInterfaces(Class cls, final HashSet> interfacesFound) {
+ private static void getAllInterfaces(Class cls, final Set> interfacesFound) {
while (cls != null) {
- final Class[] interfaces = cls.getInterfaces();
-
- for (final Class i : interfaces) {
+ for (final Class i : cls.getInterfaces()) {
if (interfacesFound.add(i)) {
getAllInterfaces(i, interfacesFound);
}
}
-
cls = cls.getSuperclass();
- }
- }
+ }
+ }
- // Convert list
- // ----------------------------------------------------------------------
/**
- * Given a {@code List} of class names, this method converts them into classes.
+ * Gets a {@link List} of superclasses for the given class.
*
- * A new {@code List} is returned. If the class name cannot be found, {@code null}
- * is stored in the {@code List}. If the class name in the {@code List} is
- * {@code null}, {@code null} is stored in the output {@code List}.
+ *
+ * The first entry is the superclass of the given class.
+ * The last entry is {@link Object}'s class.
+ *
*
- * @param classNames the classNames to change
- * @return a {@code List} of Class objects corresponding to the class names,
- * {@code null} if null input
- * @throws ClassCastException if classNames contains a non String entry
+ * @param cls The class to look up, may be {@code null}.
+ * @return The {@link List} of superclasses in order going up from this one {@code null} if null input.
*/
- public static List> convertClassNamesToClasses(final List classNames) {
- if (classNames == null) {
+ public static List> getAllSuperclasses(final Class cls) {
+ if (cls == null) {
return null;
}
- final List> classes = new ArrayList<>(classNames.size());
- for (final String className : classNames) {
- try {
- classes.add(Class.forName(className));
- } catch (final Exception ex) {
- classes.add(null);
- }
+ final List> classes = new ArrayList<>();
+ Class superclass = cls.getSuperclass();
+ while (superclass != null) {
+ classes.add(superclass);
+ superclass = superclass.getSuperclass();
}
return classes;
}
/**
- * Given a {@code List} of {@code Class} objects, this method converts
- * them into class names.
- *
- * A new {@code List} is returned. {@code null} objects will be copied into
- * the returned list as {@code null}.
+ * Gets the canonical class name for a {@link Class}.
*
- * @param classes the classes to change
- * @return a {@code List} of class names corresponding to the Class objects,
- * {@code null} if null input
- * @throws ClassCastException if {@code classes} contains a non-{@code Class} entry
+ * @param cls The class for which to get the canonical class name; may be null.
+ * @return The canonical name of the class, or the empty String.
+ * @since 3.7
+ * @see Class#getCanonicalName()
*/
- public static List convertClassesToClassNames(final List> classes) {
- if (classes == null) {
- return null;
- }
- final List classNames = new ArrayList<>(classes.size());
- for (final Class cls : classes) {
- if (cls == null) {
- classNames.add(null);
- } else {
- classNames.add(cls.getName());
- }
- }
- return classNames;
+ public static String getCanonicalName(final Class cls) {
+ return getCanonicalName(cls, StringUtils.EMPTY);
}
- // Is assignable
- // ----------------------------------------------------------------------
/**
- * Checks if an array of Classes can be assigned to another array of Classes.
- *
- * This method calls {@link #isAssignable(Class, Class) isAssignable} for each
- * Class pair in the input arrays. It can be used to check if a set of arguments
- * (the first parameter) are suitably compatible with a set of method parameter types
- * (the second parameter).
- *
- * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this
- * method takes into account widenings of primitive classes and
- * {@code null}s.
- *
- * Primitive widenings allow an int to be assigned to a {@code long},
- * {@code float} or {@code double}. This method returns the correct
- * result for these cases.
- *
- * {@code Null} may be assigned to any reference type. This method will
- * return {@code true} if {@code null} is passed in and the toClass is
- * non-primitive.
- *
- * Specifically, this method tests whether the type represented by the
- * specified {@code Class} parameter can be converted to the type
- * represented by this {@code Class} object via an identity conversion
- * widening primitive or widening reference conversion. See
- * The Java Language Specification
+ * Gets the canonical name for a {@link Class}.
*
- * Since Lang 3.0, this method will default behavior for
- * calculating assignability between primitive and wrapper types corresponding
- * to the running Java version ; i.e. autoboxing will be the default
- * behavior in VMs running Java versions > 1.5.
- *
- * @param classArray the array of Classes to check, may be {@code null}
- * @param toClassArray the array of Classes to try to assign into, may be {@code null}
- * @return {@code true} if assignment possible
+ * @param cls The class for which to get the canonical class name; may be null.
+ * @param valueIfNull The return value if null.
+ * @return The canonical name of the class, or {@code valueIfNull}.
+ * @since 3.7
+ * @see Class#getCanonicalName()
*/
- public static boolean isAssignable(final Class[] classArray, final Class... toClassArray) {
- return isAssignable(classArray, toClassArray, true);
+ public static String getCanonicalName(final Class cls, final String valueIfNull) {
+ if (cls == null) {
+ return valueIfNull;
+ }
+ final String canonicalName = cls.getCanonicalName();
+ return canonicalName == null ? valueIfNull : canonicalName;
}
/**
- * Checks if an array of Classes can be assigned to another array of Classes.
+ * Gets the canonical name for an {@link Object}.
*
- * This method calls {@link #isAssignable(Class, Class) isAssignable} for each
- * Class pair in the input arrays. It can be used to check if a set of arguments
- * (the first parameter) are suitably compatible with a set of method parameter types
- * (the second parameter).
- *
- * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this
- * method takes into account widenings of primitive classes and
- * {@code null}s.
+ * @param object The object for which to get the canonical class name; may be null.
+ * @return The canonical name of the object, or the empty String.
+ * @since 3.7
+ * @see Class#getCanonicalName()
+ */
+ public static String getCanonicalName(final Object object) {
+ return getCanonicalName(object, StringUtils.EMPTY);
+ }
+
+ /**
+ * Gets the canonical name for an {@link Object}.
*
- * Primitive widenings allow an int to be assigned to a {@code long},
- * {@code float} or {@code double}. This method returns the correct
- * result for these cases.
+ * @param object The object for which to get the canonical class name; may be null.
+ * @param valueIfNull The return value if null.
+ * @return The canonical name of the object or {@code valueIfNull}.
+ * @since 3.7
+ * @see Class#getCanonicalName()
+ */
+ public static String getCanonicalName(final Object object, final String valueIfNull) {
+ if (object == null) {
+ return valueIfNull;
+ }
+ final String canonicalName = object.getClass().getCanonicalName();
+ return canonicalName == null ? valueIfNull : canonicalName;
+ }
+
+ /**
+ * Converts a given name of class into canonical format. If name of class is not a name of array class it returns
+ * unchanged name.
*
- * {@code Null} may be assigned to any reference type. This method will
- * return {@code true} if {@code null} is passed in and the toClass is
- * non-primitive.
+ *
+ * The method does not change the {@code $} separators in case the class is inner class.
+ *
*
- * Specifically, this method tests whether the type represented by the
- * specified {@code Class} parameter can be converted to the type
- * represented by this {@code Class} object via an identity conversion
- * widening primitive or widening reference conversion. See
- * The Java Language Specification
+ *
+ * Example:
+ *
+ * {@code getCanonicalName("[I") = "int[]"}
+ * {@code getCanonicalName("[Ljava.lang.String;") = "java.lang.String[]"}
+ * {@code getCanonicalName("java.lang.String") = "java.lang.String"}
+ *
+ *
*
- * @param classArray the array of Classes to check, may be {@code null}
- * @param toClassArray the array of Classes to try to assign into, may be {@code null}
- * @param autoboxing whether to use implicit autoboxing/unboxing between primitives and wrappers
- * @return {@code true} if assignment possible
+ * @param name The name of class.
+ * @return canonical form of class name.
+ * @throws IllegalArgumentException if the class name is invalid.
*/
- public static boolean isAssignable(Class[] classArray, Class[] toClassArray, final boolean autoboxing) {
- if (!ArrayUtils.isSameLength(classArray, toClassArray)) {
- return false;
+ private static String getCanonicalName(final String name) {
+ String className = StringUtils.deleteWhitespace(name);
+ if (className == null) {
+ return null;
+ }
+ int dim = 0;
+ final int len = className.length();
+ while (dim < len && className.charAt(dim) == '[') {
+ dim++;
+ if (dim > MAX_DIMENSIONS) {
+ throw new IllegalArgumentException(String.format("Maximum array dimension %d exceeded", MAX_DIMENSIONS));
+ }
}
- if (classArray == null) {
- classArray = ArrayUtils.EMPTY_CLASS_ARRAY;
+ if (dim >= len) {
+ throw new IllegalArgumentException(String.format("Invalid class name %s", name));
}
- if (toClassArray == null) {
- toClassArray = ArrayUtils.EMPTY_CLASS_ARRAY;
+ if (dim < 1) {
+ return className;
}
- for (int i = 0; i < classArray.length; i++) {
- if (!isAssignable(classArray[i], toClassArray[i], autoboxing)) {
- return false;
+ className = className.substring(dim);
+ if (className.startsWith("L")) {
+ if (!className.endsWith(";") || className.length() < 3) {
+ throw new IllegalArgumentException(String.format("Invalid class name %s", name));
}
+ className = className.substring(1, className.length() - 1);
+ } else if (className.length() == 1) {
+ final String primitive = REVERSE_ABBREVIATION_MAP.get(className.substring(0, 1));
+ if (primitive == null) {
+ throw new IllegalArgumentException(String.format("Invalid class name %s", name));
+ }
+ className = primitive;
+ } else {
+ throw new IllegalArgumentException(String.format("Invalid class name %s", name));
}
- return true;
- }
-
- /**
- * Returns whether the given {@code type} is a primitive or primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character},
- * {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
- *
- * @param type
- * The class to query or null.
- * @return true if the given {@code type} is a primitive or primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character},
- * {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
- * @since 3.1
- */
- public static boolean isPrimitiveOrWrapper(final Class type) {
- if (type == null) {
- return false;
+ final StringBuilder canonicalClassNameBuffer = new StringBuilder(className.length() + dim * 2);
+ canonicalClassNameBuffer.append(className);
+ for (int i = 0; i < dim; i++) {
+ canonicalClassNameBuffer.append("[]");
}
- return type.isPrimitive() || isPrimitiveWrapper(type);
+ return canonicalClassNameBuffer.toString();
}
/**
- * Returns whether the given {@code type} is a primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character}, {@link Short},
- * {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
+ * Gets the (initialized) class represented by {@code className} using the {@code classLoader}. This implementation
+ * supports the syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}",
+ * "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}".
+ *
+ * The provided class name is normalized by removing all whitespace. This is especially helpful when handling XML element values in which whitespace has not
+ * been collapsed.
+ *
+ *
+ * Security note: because all whitespace is deleted before the class is resolved (and a failing {@code '.'} may be retried as {@code '$'}
+ * for inner classes), many distinct input strings resolve to the same class, while {@link Class#forName(String)} performs no such normalization. Validating
+ * an untrusted class name by string comparison before calling this method is therefore unsound: for example, {@code " java.lang.Runtime"} fails a
+ * naive {@code startsWith("java.")} denylist check on the raw string, yet loads {@code java.lang.Runtime}. Validate the class name after
+ * normalization, validate the resolved {@link Class} object itself, or use {@link #getClassStrict(ClassLoader, String, boolean)} which performs no
+ * whitespace normalization.
+ *
*
- * @param type
- * The class to query or null.
- * @return true if the given {@code type} is a primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character}, {@link Short},
- * {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
- * @since 3.1
+ * @param classLoader The class loader to use to load the class.
+ * @param className The class name.
+ * @return The class represented by {@code className} using the {@code classLoader}.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @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
*/
- public static boolean isPrimitiveWrapper(final Class type) {
- return wrapperPrimitiveMap.containsKey(type);
+ public static Class getClass(final ClassLoader classLoader, final String className) throws ClassNotFoundException {
+ return getClass(classLoader, className, true);
}
/**
- * Checks if one {@code Class} can be assigned to a variable of
- * another {@code Class}.
- *
- * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method,
- * this method takes into account widenings of primitive classes and
- * {@code null}s.
- *
- * Primitive widenings allow an int to be assigned to a long, float or
- * double. This method returns the correct result for these cases.
- *
- * {@code Null} may be assigned to any reference type. This method
- * will return {@code true} if {@code null} is passed in and the
- * toClass is non-primitive.
- *
- * Specifically, this method tests whether the type represented by the
- * specified {@code Class} parameter can be converted to the type
- * represented by this {@code Class} object via an identity conversion
- * widening primitive or widening reference conversion. See
- * The Java Language Specification
- *
- * Since Lang 3.0, this method will default behavior for
- * calculating assignability between primitive and wrapper types corresponding
- * to the running Java version ; i.e. autoboxing will be the default
- * behavior in VMs running Java versions > 1.5.
+ * Gets the class represented by {@code className} using the {@code classLoader}. This implementation supports the
+ * syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}", "{@code [Ljava.util.Map.Entry;}", and
+ * "{@code [Ljava.util.Map$Entry;}".
+ *
+ * The provided class name is normalized by removing all whitespace. This is especially helpful when handling XML element values in which whitespace has not
+ * been collapsed.
+ *
+ *
+ * Security note: because all whitespace is deleted before the class is resolved (and a failing {@code '.'} may be retried as {@code '$'}
+ * for inner classes), many distinct input strings resolve to the same class, while {@link Class#forName(String)} performs no such normalization. Validating
+ * an untrusted class name by string comparison before calling this method is therefore unsound: for example, {@code " java.lang.Runtime"} fails a
+ * naive {@code startsWith("java.")} denylist check on the raw string, yet loads {@code java.lang.Runtime}. Validate the class name after
+ * normalization, validate the resolved {@link Class} object itself, or use {@link #getClassStrict(ClassLoader, String, boolean)} which performs no
+ * whitespace normalization.
+ *
*
- * @param cls the Class to check, may be null
- * @param toClass the Class to try to assign into, returns false if null
- * @return {@code true} if assignment possible
- */
- public static boolean isAssignable(final Class cls, final Class toClass) {
- return isAssignable(cls, toClass, true);
+ * @param classLoader The class loader to use to load the class.
+ * @param className The class name.
+ * @param initialize whether the class must be initialized.
+ * @return The class represented by {@code className} using the {@code classLoader}.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @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
+ */
+ public static Class getClass(final ClassLoader classLoader, final String className, final boolean initialize) throws ClassNotFoundException {
+ return getClass(classLoader, className, initialize, true);
}
/**
- * Checks if one {@code Class} can be assigned to a variable of
- * another {@code Class}.
- *
- * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method,
- * this method takes into account widenings of primitive classes and
- * {@code null}s.
- *
- * Primitive widenings allow an int to be assigned to a long, float or
- * double. This method returns the correct result for these cases.
+ * Implements {@link #getClass(ClassLoader, String, boolean)} and {@link #getClassStrict(ClassLoader, String, boolean)}.
*
- * {@code Null} may be assigned to any reference type. This method
- * will return {@code true} if {@code null} is passed in and the
- * toClass is non-primitive.
- *
- * Specifically, this method tests whether the type represented by the
- * specified {@code Class} parameter can be converted to the type
- * represented by this {@code Class} object via an identity conversion
- * widening primitive or widening reference conversion. See
- * The Java Language Specification
- *
- * @param cls the Class to check, may be null
- * @param toClass the Class to try to assign into, returns false if null
- * @param autoboxing whether to use implicit autoboxing/unboxing between primitives and wrappers
- * @return {@code true} if assignment possible
+ * @param classLoader The class loader to use to load the class.
+ * @param className The class name.
+ * @param initialize whether the class must be initialized.
+ * @param normalizeWhitespace whether to delete all whitespace from the class name before resolving it.
+ * @return The class represented by {@code className} using the {@code classLoader}.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
*/
- public static boolean isAssignable(Class cls, final Class toClass, final boolean autoboxing) {
- if (toClass == null) {
- return false;
- }
- // have to check for null, as isAssignableFrom doesn't
- if (cls == null) {
- return !toClass.isPrimitive();
- }
- //autoboxing:
- if (autoboxing) {
- if (cls.isPrimitive() && !toClass.isPrimitive()) {
- cls = primitiveToWrapper(cls);
- if (cls == null) {
- return false;
- }
- }
- if (toClass.isPrimitive() && !cls.isPrimitive()) {
- cls = wrapperToPrimitive(cls);
- if (cls == null) {
- return false;
+ private static Class getClass(final ClassLoader classLoader, final String className, final boolean initialize, final boolean normalizeWhitespace)
+ throws ClassNotFoundException {
+ // This method was re-written to avoid recursion and stack overflows found by fuzz testing.
+ String next = className;
+ int lastDotIndex = -1;
+ do {
+ try {
+ final Class clazz = getPrimitiveClass(next);
+ return clazz != null ? clazz : Class.forName(normalizeWhitespace ? toCleanName(next) : toEncodedName(next), initialize, classLoader);
+ } catch (final ClassNotFoundException ex) {
+ lastDotIndex = next.lastIndexOf(PACKAGE_SEPARATOR_CHAR);
+ if (lastDotIndex != -1) {
+ next = next.substring(0, lastDotIndex) + INNER_CLASS_SEPARATOR_CHAR + next.substring(lastDotIndex + 1);
}
}
- }
- if (cls.equals(toClass)) {
- return true;
- }
- if (cls.isPrimitive()) {
- if (!toClass.isPrimitive()) {
- return false;
- }
- if (Integer.TYPE.equals(cls)) {
- return Long.TYPE.equals(toClass)
- || Float.TYPE.equals(toClass)
- || Double.TYPE.equals(toClass);
- }
- if (Long.TYPE.equals(cls)) {
- return Float.TYPE.equals(toClass)
- || Double.TYPE.equals(toClass);
- }
- if (Boolean.TYPE.equals(cls)) {
- return false;
- }
- if (Double.TYPE.equals(cls)) {
- return false;
- }
- if (Float.TYPE.equals(cls)) {
- return Double.TYPE.equals(toClass);
- }
- if (Character.TYPE.equals(cls)) {
- return Integer.TYPE.equals(toClass)
- || Long.TYPE.equals(toClass)
- || Float.TYPE.equals(toClass)
- || Double.TYPE.equals(toClass);
- }
- if (Short.TYPE.equals(cls)) {
- return Integer.TYPE.equals(toClass)
- || Long.TYPE.equals(toClass)
- || Float.TYPE.equals(toClass)
- || Double.TYPE.equals(toClass);
- }
- if (Byte.TYPE.equals(cls)) {
- return Short.TYPE.equals(toClass)
- || Integer.TYPE.equals(toClass)
- || Long.TYPE.equals(toClass)
- || Float.TYPE.equals(toClass)
- || Double.TYPE.equals(toClass);
- }
- // should never get here
- return false;
- }
- return toClass.isAssignableFrom(cls);
+ } while (lastDotIndex != -1);
+ throw new ClassNotFoundException(className);
}
/**
- * Converts the specified primitive Class object to its corresponding
- * wrapper Class object.
- *
- * NOTE: From v2.2, this method handles {@code Void.TYPE},
- * returning {@code Void.TYPE}.
+ * Gets the (initialized) class represented by {@code className} using the current thread's context class loader.
+ * This implementation supports the syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}",
+ * "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}".
+ *
+ * The provided class name is normalized by removing all whitespace. This is especially helpful when handling XML element values in which whitespace has not
+ * been collapsed.
+ *
+ *
+ * Security note: because all whitespace is deleted before the class is resolved (and a failing {@code '.'} may be retried as {@code '$'}
+ * for inner classes), many distinct input strings resolve to the same class, while {@link Class#forName(String)} performs no such normalization. Validating
+ * an untrusted class name by string comparison before calling this method is therefore unsound: for example, {@code " java.lang.Runtime"} fails a
+ * naive {@code startsWith("java.")} denylist check on the raw string, yet loads {@code java.lang.Runtime}. Validate the class name after
+ * normalization, validate the resolved {@link Class} object itself, or use {@link #getClassStrict(ClassLoader, String, boolean)} which performs no
+ * whitespace normalization.
+ *
*
- * @param cls the class to convert, may be null
- * @return the wrapper class for {@code cls} or {@code cls} if
- * {@code cls} is not a primitive. {@code null} if null input.
- * @since 2.1
+ * @param className The class name
+ * @return The class represented by {@code className} using the current thread's context class loader
+ * @throws NullPointerException if the className is null
+ * @throws ClassNotFoundException if the class is not found
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @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
*/
- public static Class primitiveToWrapper(final Class cls) {
- Class convertedClass = cls;
- if (cls != null && cls.isPrimitive()) {
- convertedClass = primitiveWrapperMap.get(cls);
- }
- return convertedClass;
+ public static Class getClass(final String className) throws ClassNotFoundException {
+ return getClass(className, true);
}
/**
- * Converts the specified array of primitive Class objects to an array of
- * its corresponding wrapper Class objects.
+ * Gets the class represented by {@code className} using the current thread's context class loader. This
+ * implementation supports the syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}",
+ * "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}".
+ *
+ * The provided class name is normalized by removing all whitespace. This is especially helpful when handling XML element values in which whitespace has not
+ * been collapsed.
+ *
+ *
+ * Security note: because all whitespace is deleted before the class is resolved (and a failing {@code '.'} may be retried as {@code '$'}
+ * for inner classes), many distinct input strings resolve to the same class, while {@link Class#forName(String)} performs no such normalization. Validating
+ * an untrusted class name by string comparison before calling this method is therefore unsound: for example, {@code " java.lang.Runtime"} fails a
+ * naive {@code startsWith("java.")} denylist check on the raw string, yet loads {@code java.lang.Runtime}. Validate the class name after
+ * normalization, validate the resolved {@link Class} object itself, or use {@link #getClassStrict(ClassLoader, String, boolean)} which performs no
+ * whitespace normalization.
+ *
*
- * @param classes the class array to convert, may be null or empty
- * @return an array which contains for each given class, the wrapper class or
- * the original class if class is not a primitive. {@code null} if null input.
- * Empty array if an empty array passed in.
- * @since 2.1
+ * @param className The class name.
+ * @param initialize whether the class must be initialized.
+ * @return The class represented by {@code className} using the current thread's context class loader.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @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
*/
- public static Class[] primitivesToWrappers(final Class... classes) {
- if (classes == null) {
- return null;
- }
-
- if (classes.length == 0) {
- return classes;
- }
-
- final Class[] convertedClasses = new Class[classes.length];
- for (int i = 0; i < classes.length; i++) {
- convertedClasses[i] = primitiveToWrapper(classes[i]);
- }
- return convertedClasses;
+ public static Class getClass(final String className, final boolean initialize) throws ClassNotFoundException {
+ final ClassLoader contextCL = Thread.currentThread().getContextClassLoader();
+ final ClassLoader loader = contextCL == null ? ClassUtils.class.getClassLoader() : contextCL;
+ return getClass(loader, className, initialize);
}
/**
- * Converts the specified wrapper class to its corresponding primitive
- * class.
- *
- * This method is the counter part of {@code primitiveToWrapper()}.
- * If the passed in class is a wrapper class for a primitive type, this
- * primitive type will be returned (e.g. {@code Integer.TYPE} for
- * {@code Integer.class}). For other classes, or if the parameter is
- * null , the return value is null .
+ * Gets the class represented by {@code className} using the {@code classLoader}, without normalizing the class name.
+ *
+ * Unlike {@link #getClass(ClassLoader, String, boolean)}, this method does not delete whitespace from the class name: a name that differs from
+ * the intended binary name only by whitespace throws {@link ClassNotFoundException}, matching {@link Class#forName(String, boolean, ClassLoader)}. Use
+ * this variant when the class name may come from an untrusted source, so that host-side string validation of the raw name cannot be bypassed through
+ * whitespace the loader would otherwise silently remove.
+ *
+ *
+ * The syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}", "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}"
+ * are still supported: a failing {@code '.'} is retried as {@code '$'} to find inner classes, so more than one dotted spelling can still resolve to the
+ * same inner class. When validating untrusted names, prefer validating the resolved {@link Class} object.
+ *
*
- * @param cls the class to convert, may be null
- * @return the corresponding primitive type if {@code cls} is a
- * wrapper class, null otherwise
- * @see #primitiveToWrapper(Class)
- * @since 2.4
- */
- public static Class wrapperToPrimitive(final Class cls) {
- return wrapperPrimitiveMap.get(cls);
+ * @param classLoader The class loader to use to load the class.
+ * @param className The class name.
+ * @param initialize whether the class must be initialized.
+ * @return The class represented by {@code className} using the {@code classLoader}.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @see Class#forName(String, boolean, ClassLoader)
+ * @see #getClass(ClassLoader, String, boolean)
+ * @since 3.21.0
+ */
+ public static Class getClassStrict(final ClassLoader classLoader, final String className, final boolean initialize) throws ClassNotFoundException {
+ return getClass(classLoader, className, initialize, false);
}
/**
- * Converts the specified array of wrapper Class objects to an array of
- * its corresponding primitive Class objects.
+ * Gets the (initialized) class represented by {@code className} using the current thread's context class loader, without normalizing the class name.
+ *
+ * Unlike {@link #getClass(String)}, this method does not delete whitespace from the class name: a name that differs from the intended binary
+ * name only by whitespace throws {@link ClassNotFoundException}, matching {@link Class#forName(String)}. Use this variant when the class name may come
+ * from an untrusted source, so that host-side string validation of the raw name cannot be bypassed through whitespace the loader would otherwise silently
+ * remove.
+ *
+ *
+ * The syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}", "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}"
+ * are still supported: a failing {@code '.'} is retried as {@code '$'} to find inner classes, so more than one dotted spelling can still resolve to the
+ * same inner class. When validating untrusted names, prefer validating the resolved {@link Class} object.
+ *
*
- * This method invokes {@code wrapperToPrimitive()} for each element
- * of the passed in array.
+ * @param className The class name.
+ * @return The class represented by {@code className} using the current thread's context class loader.
+ * @throws NullPointerException if the className is null.
+ * @throws ClassNotFoundException if the class is not found.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @see Class#forName(String)
+ * @see #getClass(String)
+ * @since 3.21.0
+ */
+ public static Class getClassStrict(final String className) throws ClassNotFoundException {
+ final ClassLoader contextCL = Thread.currentThread().getContextClassLoader();
+ final ClassLoader loader = contextCL == null ? ClassUtils.class.getClassLoader() : contextCL;
+ return getClassStrict(loader, className, true);
+ }
+
+ /**
+ * Delegates to {@link Class#getComponentType()} using generics.
*
- * @param classes the class array to convert, may be null or empty
- * @return an array which contains for each given class, the primitive class or
- * null if the original class is not a wrapper class. {@code null} if null input.
- * Empty array if an empty array passed in.
- * @see #wrapperToPrimitive(Class)
- * @since 2.4
+ * @param The array class type.
+ * @param cls A class or null.
+ * @return The array component type or null.
+ * @see Class#getComponentType()
+ * @since 3.13.0
*/
- public static Class[] wrappersToPrimitives(final Class... classes) {
- if (classes == null) {
- return null;
- }
-
- if (classes.length == 0) {
- return classes;
- }
-
- final Class[] convertedClasses = new Class[classes.length];
- for (int i = 0; i < classes.length; i++) {
- convertedClasses[i] = wrapperToPrimitive(classes[i]);
- }
- return convertedClasses;
+ @SuppressWarnings("unchecked")
+ public static Class getComponentType(final Class cls) {
+ return cls == null ? null : (Class) cls.getComponentType();
}
- // Inner class
- // ----------------------------------------------------------------------
/**
- * Is the specified class an inner class or static nested class.
+ * Null-safe version of {@code cls.getName()}
*
- * @param cls the class to check, may be null
- * @return {@code true} if the class is an inner or static nested class,
- * false if not or {@code null}
+ * @param cls The class for which to get the class name; may be null.
+ * @return The class name or the empty string in case the argument is {@code null}.
+ * @since 3.7
+ * @see Class#getSimpleName()
*/
- public static boolean isInnerClass(final Class cls) {
- return cls != null && cls.getEnclosingClass() != null;
+ public static String getName(final Class cls) {
+ return getName(cls, StringUtils.EMPTY);
}
- // Class loading
- // ----------------------------------------------------------------------
/**
- * Returns the class represented by {@code className} using the
- * {@code classLoader}. This implementation supports the syntaxes
- * "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}",
- * "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}".
+ * Null-safe version of {@code cls.getName()}
*
- * @param classLoader the class loader to use to load the class
- * @param className the class name
- * @param initialize whether the class must be initialized
- * @return the class represented by {@code className} using the {@code classLoader}
- * @throws ClassNotFoundException if the class is not found
+ * @param cls The class for which to get the class name; may be null.
+ * @param valueIfNull The return value if the argument {@code cls} is {@code null}.
+ * @return The class name or {@code valueIfNull}
+ * @since 3.7
+ * @see Class#getName()
*/
- public static Class getClass(
- final ClassLoader classLoader, final String className, final boolean initialize) throws ClassNotFoundException {
- try {
- Class clazz;
- if (namePrimitiveMap.containsKey(className)) {
- clazz = namePrimitiveMap.get(className);
- } else {
- clazz = Class.forName(toCanonicalName(className), initialize, classLoader);
- }
- return clazz;
- } catch (final ClassNotFoundException ex) {
- // allow path separators (.) as inner class name separators
- final int lastDotIndex = className.lastIndexOf(PACKAGE_SEPARATOR_CHAR);
-
- if (lastDotIndex != -1) {
- try {
- return getClass(classLoader, className.substring(0, lastDotIndex) +
- INNER_CLASS_SEPARATOR_CHAR + className.substring(lastDotIndex + 1),
- initialize);
- } catch (final ClassNotFoundException ex2) { // NOPMD
- // ignore exception
- }
- }
+ public static String getName(final Class cls, final String valueIfNull) {
+ return getName(cls, valueIfNull, false);
+ }
- throw ex;
- }
+ static String getName(final Class cls, final String valueIfNull, final boolean simple) {
+ return cls == null ? valueIfNull : simple ? cls.getSimpleName() : cls.getName();
}
/**
- * Returns the (initialized) class represented by {@code className}
- * using the {@code classLoader}. This implementation supports
- * the syntaxes "{@code java.util.Map.Entry[]}",
- * "{@code java.util.Map$Entry[]}", "{@code [Ljava.util.Map.Entry;}",
- * and "{@code [Ljava.util.Map$Entry;}".
+ * Null-safe version of {@code object.getClass().getName()}
*
- * @param classLoader the class loader to use to load the class
- * @param className the class name
- * @return the class represented by {@code className} using the {@code classLoader}
- * @throws ClassNotFoundException if the class is not found
+ * @param object The object for which to get the class name; may be null.
+ * @return The class name or the empty String.
+ * @since 3.7
+ * @see Class#getSimpleName()
*/
- public static Class getClass(final ClassLoader classLoader, final String className) throws ClassNotFoundException {
- return getClass(classLoader, className, true);
+ public static String getName(final Object object) {
+ return getName(object, StringUtils.EMPTY);
}
/**
- * Returns the (initialized) class represented by {@code className}
- * using the current thread's context class loader. This implementation
- * supports the syntaxes "{@code java.util.Map.Entry[]}",
- * "{@code java.util.Map$Entry[]}", "{@code [Ljava.util.Map.Entry;}",
- * and "{@code [Ljava.util.Map$Entry;}".
+ * Null-safe version of {@code object.getClass().getSimpleName()}
*
- * @param className the class name
- * @return the class represented by {@code className} using the current thread's context class loader
- * @throws ClassNotFoundException if the class is not found
+ * @param object The object for which to get the class name; may be null.
+ * @param valueIfNull The value to return if {@code object} is {@code null}.
+ * @return The class name or {@code valueIfNull}.
+ * @since 3.0
+ * @see Class#getName()
*/
- public static Class getClass(final String className) throws ClassNotFoundException {
- return getClass(className, true);
+ public static String getName(final Object object, final String valueIfNull) {
+ return object == null ? valueIfNull : object.getClass().getName();
}
/**
- * Returns the class represented by {@code className} using the
- * current thread's context class loader. This implementation supports the
- * syntaxes "{@code java.util.Map.Entry[]}", "{@code java.util.Map$Entry[]}",
- * "{@code [Ljava.util.Map.Entry;}", and "{@code [Ljava.util.Map$Entry;}".
+ * Gets the package name from the canonical name of a {@link Class}.
*
- * @param className the class name
- * @param initialize whether the class must be initialized
- * @return the class represented by {@code className} using the current thread's context class loader
- * @throws ClassNotFoundException if the class is not found
+ * @param cls The class to get the package name for, may be {@code null}.
+ * @return The package name or an empty string.
+ * @since 2.4
*/
- public static Class getClass(final String className, final boolean initialize) throws ClassNotFoundException {
- final ClassLoader contextCL = Thread.currentThread().getContextClassLoader();
- final ClassLoader loader = contextCL == null ? ClassUtils.class.getClassLoader() : contextCL;
- return getClass(loader, className, initialize);
+ public static String getPackageCanonicalName(final Class cls) {
+ if (cls == null) {
+ return StringUtils.EMPTY;
+ }
+ return getPackageCanonicalName(cls.getName());
}
- // Public method
- // ----------------------------------------------------------------------
/**
- * Returns the desired Method much like {@code Class.getMethod}, however
- * it ensures that the returned Method is from a public class or interface and not
- * from an anonymous inner class. This means that the Method is invokable and
- * doesn't fall foul of Java bug
- * 4071957 ).
+ * Gets the package name from the class name of an {@link Object}.
*
- *
- * Set set = Collections.unmodifiableSet(...);
- * Method method = ClassUtils.getPublicMethod(set.getClass(), "isEmpty", new Class[0]);
- * Object result = method.invoke(set, new Object[]);
- *
+ * @param object The class to get the package name for, may be null.
+ * @param valueIfNull The value to return if null.
+ * @return The package name of the object, or the null value.
+ * @since 2.4
+ */
+ public static String getPackageCanonicalName(final Object object, final String valueIfNull) {
+ if (object == null) {
+ return valueIfNull;
+ }
+ return getPackageCanonicalName(object.getClass().getName());
+ }
+
+ /**
+ * Gets the package name from the class name.
+ *
+ *
+ * The string passed in is assumed to be a class name - it is not checked.
+ *
+ *
+ * If the class is in the default package, return an empty string.
+ *
+ *
+ * @param name The name to get the package name for, may be {@code null}.
+ * @return The package name or an empty string.
+ * @since 2.4
+ */
+ public static String getPackageCanonicalName(final String name) {
+ return getPackageName(getCanonicalName(name));
+ }
+
+ /**
+ * Gets the package name of a {@link Class}.
+ *
+ * @param cls The class to get the package name for, may be {@code null}.
+ * @return The package name or an empty string
+ */
+ public static String getPackageName(final Class cls) {
+ if (cls == null) {
+ return StringUtils.EMPTY;
+ }
+ return getPackageName(cls.getName());
+ }
+
+ /**
+ * Gets the package name of an {@link Object}.
*
- * @param cls the class to check, not null
- * @param methodName the name of the method
- * @param parameterTypes the list of parameters
- * @return the method
- * @throws NullPointerException if the class is null
- * @throws SecurityException if a security violation occurred
- * @throws NoSuchMethodException if the method is not found in the given class
- * or if the method doesn't conform with the requirements
+ * @param object The class to get the package name for, may be null.
+ * @param valueIfNull The value to return if null.
+ * @return The package name of the object, or the null value.
*/
- public static Method getPublicMethod(final Class cls, final String methodName, final Class... parameterTypes)
- throws NoSuchMethodException {
+ public static String getPackageName(final Object object, final String valueIfNull) {
+ if (object == null) {
+ return valueIfNull;
+ }
+ return getPackageName(object.getClass());
+ }
+ /**
+ * Gets the package name from a {@link String}.
+ *
+ *
+ * The string passed in is assumed to be a class name.
+ *
+ *
+ * If the class is unpackaged, return an empty string.
+ *
+ *
+ * @param className The className to get the package name for, may be {@code null}.
+ * @return The package name or an empty string.
+ */
+ public static String getPackageName(String className) {
+ if (StringUtils.isEmpty(className)) {
+ return StringUtils.EMPTY;
+ }
+ int i = 0;
+ // Strip array encoding
+ while (className.charAt(i) == '[') {
+ i++;
+ }
+ className = className.substring(i);
+ // Strip Object type encoding
+ if (className.charAt(0) == 'L' && className.charAt(className.length() - 1) == ';') {
+ className = className.substring(1);
+ }
+ i = className.lastIndexOf(PACKAGE_SEPARATOR_CHAR);
+ if (i == -1) {
+ return StringUtils.EMPTY;
+ }
+ return className.substring(0, i);
+ }
+
+ /**
+ * Gets the primitive class for the given class name, for example "byte".
+ *
+ * @param className The primitive class for the given class name.
+ * @return The primitive class.
+ */
+ static Class getPrimitiveClass(final String className) {
+ return NAME_PRIMITIVE_MAP.get(className);
+ }
+
+ /**
+ * Gets the desired Method much like {@code Class.getMethod}, however it ensures that the returned Method is from a
+ * public class or interface and not from an anonymous inner class. This means that the Method is invokable and doesn't
+ * fall foul of Java bug (4071957 ).
+ *
+ *
+ * {@code Set set = Collections.unmodifiableSet(...);
+ * Method method = ClassUtils.getPublicMethod(set.getClass(), "isEmpty", new Class[0]);
+ * Object result = method.invoke(set, new Object[]);}
+ *
+ *
+ * @param cls The class to check, not null.
+ * @param methodName The name of the method.
+ * @param parameterTypes The list of parameters.
+ * @return The method.
+ * @throws NullPointerException if the class is null.
+ * @throws SecurityException if a security violation occurred.
+ * @throws NoSuchMethodException if the method is not found in the given class or if the method doesn't conform with the
+ * requirements.
+ */
+ public static Method getPublicMethod(final Class cls, final String methodName, final Class... parameterTypes) throws NoSuchMethodException {
final Method declaredMethod = cls.getMethod(methodName, parameterTypes);
- if (Modifier.isPublic(declaredMethod.getDeclaringClass().getModifiers())) {
+ if (isPublic(declaredMethod.getDeclaringClass())) {
return declaredMethod;
}
-
- final List> candidateClasses = new ArrayList<>();
- candidateClasses.addAll(getAllInterfaces(cls));
+ final List> candidateClasses = new ArrayList<>(getAllInterfaces(cls));
candidateClasses.addAll(getAllSuperclasses(cls));
-
for (final Class candidateClass : candidateClasses) {
- if (!Modifier.isPublic(candidateClass.getModifiers())) {
+ if (!isPublic(candidateClass)) {
continue;
}
- Method candidateMethod;
- try {
- candidateMethod = candidateClass.getMethod(methodName, parameterTypes);
- } catch (final NoSuchMethodException ex) {
- continue;
+ final Method candidateMethod;
+ try {
+ candidateMethod = candidateClass.getMethod(methodName, parameterTypes);
+ } catch (final NoSuchMethodException ex) {
+ continue;
+ }
+ if (Modifier.isPublic(candidateMethod.getDeclaringClass().getModifiers())) {
+ return candidateMethod;
+ }
+ }
+ throw new NoSuchMethodException("Can't find a public method for " + methodName + " " + ArrayUtils.toString(parameterTypes));
+ }
+
+ /**
+ * Gets the canonical name minus the package name from a {@link Class}.
+ *
+ * @param cls The class for which to get the short canonical class name; may be null.
+ * @return The canonical name without the package name or an empty string.
+ * @since 2.4
+ * @see Class#getCanonicalName()
+ */
+ public static String getShortCanonicalName(final Class cls) {
+ return cls == null ? StringUtils.EMPTY : getShortCanonicalName(cls.getCanonicalName());
+ }
+
+ /**
+ * Gets the canonical name minus the package name for an {@link Object}.
+ *
+ * @param object The class to get the short name for, may be null.
+ * @param valueIfNull The value to return if null.
+ * @return The canonical name of the object without the package name, or the null value.
+ * @since 2.4
+ * @see Class#getCanonicalName()
+ */
+ public static String getShortCanonicalName(final Object object, final String valueIfNull) {
+ return object == null ? valueIfNull : getShortCanonicalName(object.getClass());
+ }
+
+ /**
+ * Gets the canonical name minus the package name from a String.
+ *
+ *
+ * The string passed in is assumed to be a class name - it is not checked.
+ *
+ *
+ *
+ * Note that this method is mainly designed to handle the arrays and primitives properly. If the class is an inner class
+ * then the result value will not contain the outer classes. This way the behavior of this method is different from
+ * {@link #getShortClassName(String)}. The argument in that case is class name and not canonical name and the return
+ * value retains the outer classes.
+ *
+ *
+ *
+ * Note that there is no way to reliably identify the part of the string representing the package hierarchy and the part
+ * that is the outer class or classes in case of an inner class. Trying to find the class would require reflective call
+ * and the class itself may not even be on the class path. Relying on the fact that class names start with capital
+ * letter and packages with lower case is heuristic.
+ *
+ *
+ *
+ * It is recommended to use {@link #getShortClassName(String)} for cases when the class is an inner class and use this
+ * method for cases it is designed for.
+ *
+ *
+ *
+ * Examples
+ *
+ * return value
+ * input
+ *
+ *
+ * {@code ""}
+ * {@code (String) null}
+ *
+ *
+ * {@code "Map.Entry"}
+ * {@code java.util.Map.Entry.class.getName()}
+ *
+ *
+ * {@code "Entry"}
+ * {@code java.util.Map.Entry.class.getCanonicalName()}
+ *
+ *
+ * {@code "ClassUtils"}
+ * {@code "org.apache.commons.lang3.ClassUtils"}
+ *
+ *
+ * {@code "ClassUtils[]"}
+ * {@code "[Lorg.apache.commons.lang3.ClassUtils;"}
+ *
+ *
+ * {@code "ClassUtils[][]"}
+ * {@code "[[Lorg.apache.commons.lang3.ClassUtils;"}
+ *
+ *
+ * {@code "ClassUtils[]"}
+ * {@code "org.apache.commons.lang3.ClassUtils[]"}
+ *
+ *
+ * {@code "ClassUtils[][]"}
+ * {@code "org.apache.commons.lang3.ClassUtils[][]"}
+ *
+ *
+ * {@code "int[]"}
+ * {@code "[I"}
+ *
+ *
+ * {@code "int[]"}
+ * {@code int[].class.getCanonicalName()}
+ *
+ *
+ * {@code "int[]"}
+ * {@code int[].class.getName()}
+ *
+ *
+ * {@code "int[][]"}
+ * {@code "[[I"}
+ *
+ *
+ * {@code "int[]"}
+ * {@code "int[]"}
+ *
+ *
+ * {@code "int[][]"}
+ * {@code "int[][]"}
+ *
+ *
+ *
+ * @param canonicalName The class name to get the short name for.
+ * @return The canonical name of the class without the package name or an empty string.
+ * @since 2.4
+ */
+ public static String getShortCanonicalName(final String canonicalName) {
+ return getShortClassName(getCanonicalName(canonicalName));
+ }
+
+ /**
+ * Gets the class name minus the package name from a {@link Class}.
+ *
+ * @param cls The class to get the short name for.
+ * @return The class name without the package name or an empty string. If the class is an inner class then the returned
+ * value will contain the outer class or classes separated with {@code .} (dot) character.
+ */
+ public static String getShortClassName(final Class cls) {
+ if (cls == null) {
+ return StringUtils.EMPTY;
+ }
+ int dim = 0;
+ Class c = cls;
+ while (c.isArray()) {
+ dim++;
+ c = c.getComponentType();
+ }
+ String base;
+ // c.isAnonymousClass() / isLocalClass() and the getDeclaringClass() chain
+ // can both throw NoClassDefFoundError when the enclosing class is
+ // missing from the classpath, so the try/catch wraps the whole block.
+ try {
+ // Preserve legacy behavior for anonymous/local classes (keeps compiler ordinals: $13, $10Named, etc.)
+ if (c.isAnonymousClass() || c.isLocalClass()) {
+ base = getShortClassName(c.getName());
+ } else {
+ final Deque parts = new ArrayDeque<>();
+ Class x = c;
+ while (x != null) {
+ parts.push(x.getSimpleName());
+ x = x.getDeclaringClass();
+ }
+ base = String.join(".", parts);
+ }
+ } catch (final NoClassDefFoundError ignored) {
+ base = getShortClassName(c.getName());
+ }
+ return base + StringUtils.repeat("[]", dim);
+ }
+
+ /**
+ * Gets the class name of the {@code object} without the package name or names.
+ *
+ * @param object The class to get the short name for, may be {@code null}.
+ * @param valueIfNull The value to return if the object is {@code null}.
+ * @return The class name of the object without the package name, or {@code valueIfNull} if the argument {@code object}
+ * is {@code null}.
+ */
+ public static String getShortClassName(final Object object, final String valueIfNull) {
+ if (object == null) {
+ return valueIfNull;
+ }
+ return getShortClassName(object.getClass());
+ }
+
+ /**
+ * Gets the class name minus the package name from a String.
+ *
+ *
+ * The string passed in is assumed to be a class name - it is not checked. The string has to be formatted the way as the
+ * JDK method {@code Class.getName()} returns it, and not the usual way as we write it, for example in import
+ * statements, or as it is formatted by {@code Class.getCanonicalName()}.
+ *
+ *
+ *
+ * The difference is significant only in case of classes that are inner classes of some other classes. In this case
+ * the separator between the outer and inner class (possibly on multiple hierarchy level) has to be {@code $} (dollar
+ * sign) and not {@code .} (dot), as it is returned by {@code Class.getName()}
+ *
+ *
+ *
+ * Note that this method is called from the {@link #getShortClassName(Class)} method using the string returned by
+ * {@code Class.getName()}.
+ *
+ *
+ *
+ * Note that this method differs from {@link #getSimpleName(Class)} in that this will return, for example
+ * {@code "Map.Entry"} whilst the {@link Class} variant will simply return {@code "Entry"}. In this example
+ * the argument {@code className} is the string {@code java.util.Map$Entry} (note the {@code $} sign).
+ *
+ *
+ * @param className The className to get the short name for. It has to be formatted as returned by
+ * {@code Class.getName()} and not {@code Class.getCanonicalName()}.
+ * @return The class name of the class without the package name or an empty string. If the class is an inner class then
+ * value contains the outer class or classes and the separator is replaced to be {@code .} (dot) character.
+ */
+ public static String getShortClassName(String className) {
+ if (StringUtils.isEmpty(className)) {
+ return StringUtils.EMPTY;
+ }
+ 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 (REVERSE_ABBREVIATION_MAP.containsKey(className)) {
+ className = REVERSE_ABBREVIATION_MAP.get(className);
+ }
+ }
+ 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;
+ }
+
+ /**
+ * Null-safe version of {@code cls.getSimpleName()}
+ *
+ * @param cls The class for which to get the simple name; may be null.
+ * @return The simple class name or the empty string in case the argument is {@code null}.
+ * @since 3.0
+ * @see Class#getSimpleName()
+ */
+ public static String getSimpleName(final Class cls) {
+ return getSimpleName(cls, StringUtils.EMPTY);
+ }
+
+ /**
+ * Null-safe version of {@code cls.getSimpleName()}
+ *
+ * @param cls The class for which to get the simple name; may be null.
+ * @param valueIfNull The value to return if null.
+ * @return The simple class name or {@code valueIfNull} if the argument {@code cls} is {@code null}.
+ * @since 3.0
+ * @see Class#getSimpleName()
+ */
+ public static String getSimpleName(final Class cls, final String valueIfNull) {
+ return cls == null ? valueIfNull : cls.getSimpleName();
+ }
+
+ /**
+ * Null-safe version of {@code object.getClass().getSimpleName()}
+ *
+ *
+ * It is to note that this method is overloaded and in case the argument {@code object} is a {@link Class} object then
+ * the {@link #getSimpleName(Class)} will be invoked. If this is a significant possibility then the caller should check
+ * this case and call {@code
+ * getSimpleName(Class.class)} or just simply use the string literal {@code "Class"}, which is the result of the method
+ * in that case.
+ *
+ *
+ * @param object The object for which to get the simple class name; may be null.
+ * @return The simple class name or the empty string in case the argument is {@code null}.
+ * @since 3.7
+ * @see Class#getSimpleName()
+ */
+ public static String getSimpleName(final Object object) {
+ return getSimpleName(object, StringUtils.EMPTY);
+ }
+
+ /**
+ * Null-safe version of {@code object.getClass().getSimpleName()}
+ *
+ * @param object The object for which to get the simple class name; may be null.
+ * @param valueIfNull The value to return if {@code object} is {@code null}.
+ * @return The simple class name or {@code valueIfNull} if the argument {@code object} is {@code null}.
+ * @since 3.0
+ * @see Class#getSimpleName()
+ */
+ public static String getSimpleName(final Object object, final String valueIfNull) {
+ return object == null ? valueIfNull : object.getClass().getSimpleName();
+ }
+
+ /**
+ * Gets an {@link Iterable} that can iterate over a class hierarchy in ascending (subclass to superclass) order,
+ * excluding interfaces.
+ *
+ * @param type The type to get the class hierarchy from.
+ * @return Iterable an Iterable over the class hierarchy of the given class.
+ * @since 3.2
+ */
+ public static Iterable> hierarchy(final Class type) {
+ return hierarchy(type, Interfaces.EXCLUDE);
+ }
+
+ /**
+ * Gets an {@link Iterable} that can iterate over a class hierarchy in ascending (subclass to superclass) order.
+ *
+ * @param type The type to get the class hierarchy from.
+ * @param interfacesBehavior switch indicating whether to include or exclude interfaces.
+ * @return Iterable an Iterable over the class hierarchy of the given class.
+ * @since 3.2
+ */
+ public static Iterable> hierarchy(final Class type, final Interfaces interfacesBehavior) {
+ final Iterable> classes = () -> {
+ final AtomicReference> next = new AtomicReference<>(type);
+ return new Iterator>() {
+
+ @Override
+ public boolean hasNext() {
+ return next.get() != null;
+ }
+
+ @Override
+ public Class next() {
+ return next.getAndUpdate(Class::getSuperclass);
+ }
+
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+ };
+ };
+ if (interfacesBehavior != Interfaces.INCLUDE) {
+ return classes;
+ }
+ return () -> {
+ final Set> seenInterfaces = new HashSet<>();
+ final Iterator> wrapped = classes.iterator();
+
+ return new Iterator>() {
+ Iterator> interfaces = Collections.emptyIterator();
+
+ @Override
+ public boolean hasNext() {
+ return interfaces.hasNext() || wrapped.hasNext();
+ }
+
+ @Override
+ public Class next() {
+ if (interfaces.hasNext()) {
+ final Class nextInterface = interfaces.next();
+ seenInterfaces.add(nextInterface);
+ return nextInterface;
+ }
+ final Class nextSuperclass = wrapped.next();
+ final Set> currentInterfaces = new LinkedHashSet<>();
+ walkInterfaces(currentInterfaces, nextSuperclass);
+ interfaces = currentInterfaces.iterator();
+ return nextSuperclass;
+ }
+
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+ private void walkInterfaces(final Set> addTo, final Class c) {
+ for (final Class iface : c.getInterfaces()) {
+ if (!seenInterfaces.contains(iface)) {
+ addTo.add(iface);
+ }
+ walkInterfaces(addTo, iface);
+ }
+ }
+
+ };
+ };
+ }
+
+ /**
+ * Tests whether one {@link Class} can be assigned to a variable of another {@link Class}.
+ *
+ *
+ * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this method takes into account widenings of
+ * primitive classes and {@code null}s.
+ *
+ *
+ *
+ * Primitive widenings allow an int to be assigned to a long, float or double. This method returns the correct result
+ * for these cases.
+ *
+ *
+ *
+ * {@code null} may be assigned to any reference type. This method will return {@code true} if {@code null} is passed in
+ * and the toClass is non-primitive.
+ *
+ *
+ *
+ * Specifically, this method tests whether the type represented by the specified {@link Class} parameter can be
+ * converted to the type represented by this {@link Class} object via an identity conversion widening primitive or
+ * widening reference conversion. See The Java Language
+ * Specification
+ *
+ *
+ * Since Lang 3.0, this method will default behavior for calculating assignability between primitive
+ * and wrapper types corresponding to the running Java version ; i.e. autoboxing will be the default behavior in
+ * VMs running Java versions > 1.5.
+ *
+ *
+ * @param cls The Class to check, may be null.
+ * @param toClass The Class to try to assign into, returns false if null.
+ * @return {@code true} if assignment possible.
+ */
+ public static boolean isAssignable(final Class cls, final Class toClass) {
+ return isAssignable(cls, toClass, true);
+ }
+
+ /**
+ * Tests whether one {@link Class} can be assigned to a variable of another {@link Class}.
+ *
+ *
+ * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this method takes into account widenings of
+ * primitive classes and {@code null}s.
+ *
+ *
+ *
+ * Primitive widenings allow an int to be assigned to a long, float or double. This method returns the correct result
+ * for these cases.
+ *
+ *
+ *
+ * {@code null} may be assigned to any reference type. This method will return {@code true} if {@code null} is passed in
+ * and the toClass is non-primitive.
+ *
+ *
+ *
+ * Specifically, this method tests whether the type represented by the specified {@link Class} parameter can be
+ * converted to the type represented by this {@link Class} object via an identity conversion widening primitive or
+ * widening reference conversion. See The Java Language
+ * Specification
+ *
+ * @param cls The Class to check, may be null.
+ * @param toClass The Class to try to assign into, returns false if null.
+ * @param autoboxing whether to use implicit autoboxing/unboxing between primitives and wrappers.
+ * @return {@code true} if assignment possible.
+ */
+ public static boolean isAssignable(Class cls, final Class toClass, final boolean autoboxing) {
+ if (toClass == null) {
+ return false;
+ }
+ // have to check for null, as isAssignableFrom doesn't
+ if (cls == null) {
+ return !toClass.isPrimitive();
+ }
+ // autoboxing:
+ if (autoboxing) {
+ if (cls.isPrimitive() && !toClass.isPrimitive()) {
+ cls = primitiveToWrapper(cls);
+ if (cls == null) {
+ return false;
+ }
+ }
+ if (toClass.isPrimitive() && !cls.isPrimitive()) {
+ cls = wrapperToPrimitive(cls);
+ if (cls == null) {
+ return false;
+ }
+ }
+ }
+ if (cls.equals(toClass)) {
+ return true;
+ }
+ if (cls.isPrimitive()) {
+ if (!toClass.isPrimitive()) {
+ return false;
+ }
+ if (Integer.TYPE.equals(cls)) {
+ return Long.TYPE.equals(toClass) || Float.TYPE.equals(toClass) || Double.TYPE.equals(toClass);
+ }
+ if (Long.TYPE.equals(cls)) {
+ return Float.TYPE.equals(toClass) || Double.TYPE.equals(toClass);
+ }
+ if (Boolean.TYPE.equals(cls)) {
+ return false;
+ }
+ if (Double.TYPE.equals(cls)) {
+ return false;
+ }
+ if (Float.TYPE.equals(cls)) {
+ return Double.TYPE.equals(toClass);
+ }
+ if (Character.TYPE.equals(cls) || Short.TYPE.equals(cls)) {
+ return Integer.TYPE.equals(toClass) || Long.TYPE.equals(toClass) || Float.TYPE.equals(toClass) || Double.TYPE.equals(toClass);
}
- if (Modifier.isPublic(candidateMethod.getDeclaringClass().getModifiers())) {
- return candidateMethod;
+ if (Byte.TYPE.equals(cls)) {
+ return Short.TYPE.equals(toClass) || Integer.TYPE.equals(toClass) || Long.TYPE.equals(toClass) || Float.TYPE.equals(toClass)
+ || Double.TYPE.equals(toClass);
}
+ // should never get here
+ return false;
}
-
- throw new NoSuchMethodException("Can't find a public method for " +
- methodName + " " + ArrayUtils.toString(parameterTypes));
+ return toClass.isAssignableFrom(cls);
}
- // ----------------------------------------------------------------------
/**
- * Converts a class name to a JLS style class name.
+ * Tests whether an array of Classes can be assigned to another array of Classes.
+ *
+ *
+ * This method calls {@link #isAssignable(Class, Class) isAssignable} for each Class pair in the input arrays. It can be
+ * used to check if a set of arguments (the first parameter) are suitably compatible with a set of method parameter
+ * types (the second parameter).
+ *
+ *
+ *
+ * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this method takes into account widenings of
+ * primitive classes and {@code null}s.
+ *
+ *
+ *
+ * Primitive widenings allow an int to be assigned to a {@code long}, {@code float} or {@code double}. This method
+ * returns the correct result for these cases.
+ *
+ *
+ *
+ * {@code null} may be assigned to any reference type. This method will return {@code true} if {@code null} is passed in
+ * and the toClass is non-primitive.
+ *
+ *
+ *
+ * Specifically, this method tests whether the type represented by the specified {@link Class} parameter can be
+ * converted to the type represented by this {@link Class} object via an identity conversion widening primitive or
+ * widening reference conversion. See The Java Language
+ * Specification
+ *
+ *
+ * Since Lang 3.0, this method will default behavior for calculating assignability between primitive
+ * and wrapper types corresponding to the running Java version ; i.e. autoboxing will be the default behavior in
+ * VMs running Java versions > 1.5.
+ *
*
- * @param className the class name
- * @return the converted name
+ * @param classArray The array of Classes to check, may be {@code null}.
+ * @param toClassArray The array of Classes to try to assign into, may be {@code null}.
+ * @return {@code true} if assignment possible.
*/
- private static String toCanonicalName(String className) {
- className = StringUtils.deleteWhitespace(className);
- Validate.notNull(className, "className must not be null.");
- if (className.endsWith("[]")) {
- final StringBuilder classNameBuffer = new StringBuilder();
- while (className.endsWith("[]")) {
- className = className.substring(0, className.length() - 2);
- classNameBuffer.append("[");
- }
- final String abbreviation = abbreviationMap.get(className);
- if (abbreviation != null) {
- classNameBuffer.append(abbreviation);
- } else {
- classNameBuffer.append("L").append(className).append(";");
- }
- className = classNameBuffer.toString();
- }
- return className;
+ public static boolean isAssignable(final Class[] classArray, final Class... toClassArray) {
+ return isAssignable(classArray, toClassArray, true);
}
/**
- * Converts an array of {@code Object} in to an array of {@code Class} objects.
- * If any of these objects is null, a null element will be inserted into the array.
+ * Tests whether an array of Classes can be assigned to another array of Classes.
*
- * This method returns {@code null} for a {@code null} input array.
+ *
+ * This method calls {@link #isAssignable(Class, Class) isAssignable} for each Class pair in the input arrays. It can be
+ * used to check if a set of arguments (the first parameter) are suitably compatible with a set of method parameter
+ * types (the second parameter).
+ *
*
- * @param array an {@code Object} array
- * @return a {@code Class} array, {@code null} if null array input
- * @since 2.4
+ *
+ * Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this method takes into account widenings of
+ * primitive classes and {@code null}s.
+ *
+ *
+ *
+ * Primitive widenings allow an int to be assigned to a {@code long}, {@code float} or {@code double}. This method
+ * returns the correct result for these cases.
+ *
+ *
+ *
+ * {@code null} may be assigned to any reference type. This method will return {@code true} if {@code null} is passed in
+ * and the toClass is non-primitive.
+ *
+ *
+ *
+ * Specifically, this method tests whether the type represented by the specified {@link Class} parameter can be
+ * converted to the type represented by this {@link Class} object via an identity conversion widening primitive or
+ * widening reference conversion. See The Java Language
+ * Specification
+ *
+ * @param classArray The array of Classes to check, may be {@code null}
+ * @param toClassArray The array of Classes to try to assign into, may be {@code null}
+ * @param autoboxing whether to use implicit autoboxing/unboxing between primitives and wrappers
+ * @return {@code true} if assignment possible
*/
- public static Class[] toClass(final Object... array) {
- if (array == null) {
- return null;
- } else if (array.length == 0) {
- return ArrayUtils.EMPTY_CLASS_ARRAY;
+ public static boolean isAssignable(Class[] classArray, Class[] toClassArray, final boolean autoboxing) {
+ if (!ArrayUtils.isSameLength(classArray, toClassArray)) {
+ return false;
}
- final Class[] classes = new Class[array.length];
- for (int i = 0; i < array.length; i++) {
- classes[i] = array[i] == null ? null : array[i].getClass();
+ classArray = ArrayUtils.nullToEmpty(classArray);
+ toClassArray = ArrayUtils.nullToEmpty(toClassArray);
+ for (int i = 0; i < classArray.length; i++) {
+ if (!isAssignable(classArray[i], toClassArray[i], autoboxing)) {
+ return false;
+ }
}
- return classes;
+ return true;
}
- // Short canonical name
- // ----------------------------------------------------------------------
/**
- * Gets the canonical name minus the package name for an {@code Object}.
+ * Tests whether the specified class an inner class or static nested class.
*
- * @param object the class to get the short name for, may be null
- * @param valueIfNull the value to return if null
- * @return the canonical name of the object without the package name, or the null value
- * @since 2.4
+ * @param cls The class to check, may be null.
+ * @return {@code true} if the class is an inner or static nested class, false if not or {@code null}.
*/
- public static String getShortCanonicalName(final Object object, final String valueIfNull) {
- if (object == null) {
- return valueIfNull;
- }
- return getShortCanonicalName(object.getClass().getName());
+ public static boolean isInnerClass(final Class cls) {
+ return cls != null && cls.getEnclosingClass() != null;
}
/**
- * Gets the canonical class name for a {@code Class}.
+ * Tests whether the given {@code type} is a primitive or primitive wrapper ({@link Boolean}, {@link Byte},
+ * {@link Character}, {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
*
- * @param cls the class for which to get the canonical class name; may be null
- * @return the canonical name of the class, or the empty String
- * @since 3.7
- * @see Class#getCanonicalName()
+ * @param type The class to query or null.
+ * @return true if the given {@code type} is a primitive or primitive wrapper ({@link Boolean}, {@link Byte},
+ * {@link Character}, {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
+ * @since 3.1
*/
- public static String getCanonicalName(final Class cls) {
- return getCanonicalName(cls, StringUtils.EMPTY);
+ public static boolean isPrimitiveOrWrapper(final Class type) {
+ return type != null && type.isPrimitive() || isPrimitiveWrapper(type);
}
/**
- * Gets the canonical name for a {@code Class}.
+ * Tests whether the given {@code type} is a primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character},
+ * {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
*
- * @param cls the class for which to get the canonical class name; may be null
- * @param valueIfNull the return value if null
- * @return the canonical name of the class, or {@code valueIfNull}
- * @since 3.7
- * @see Class#getCanonicalName()
+ * @param type The class to query or null.
+ * @return true if the given {@code type} is a primitive wrapper ({@link Boolean}, {@link Byte}, {@link Character},
+ * {@link Short}, {@link Integer}, {@link Long}, {@link Double}, {@link Float}).
+ * @since 3.1
*/
- public static String getCanonicalName(final Class cls, final String valueIfNull) {
- if (cls == null) {
- return valueIfNull;
- }
- final String canonicalName = cls.getCanonicalName();
- return canonicalName == null ? valueIfNull : canonicalName;
+ public static boolean isPrimitiveWrapper(final Class type) {
+ return WRAPPER_PRIMITIVE_MAP.containsKey(type);
}
/**
- * Gets the canonical name for an {@code Object}.
+ * Tests whether a {@link Class} is public.
*
- * @param object the object for which to get the canonical class name; may be null
- * @return the canonical name of the object, or the empty String
- * @since 3.7
- * @see Class#getCanonicalName()
+ * @param cls Class to test.
+ * @return {@code true} if {@code cls} is public.
+ * @since 3.13.0
*/
- public static String getCanonicalName(final Object object) {
- return getCanonicalName(object, StringUtils.EMPTY);
+ public static boolean isPublic(final Class cls) {
+ return Modifier.isPublic(cls.getModifiers());
}
/**
- * Gets the canonical name for an {@code Object}.
+ * Converts the specified array of primitive Class objects to an array of its corresponding wrapper Class objects.
*
- * @param object the object for which to get the canonical class name; may be null
- * @param valueIfNull the return value if null
- * @return the canonical name of the object or {@code valueIfNull}
- * @since 3.7
- * @see Class#getCanonicalName()
+ * @param classes The class array to convert, may be null or empty.
+ * @return An array which contains for each given class, the wrapper class or the original class if class is not a primitive. {@code null} if null input.
+ * Empty array if an empty array passed in.
+ * @since 2.1
*/
- public static String getCanonicalName(final Object object, final String valueIfNull) {
- if (object == null) {
- return valueIfNull;
+ public static Class[] primitivesToWrappers(final Class... classes) {
+ if (classes == null) {
+ return null;
}
- final String canonicalName = object.getClass().getCanonicalName();
- return canonicalName == null ? valueIfNull : canonicalName;
+ if (classes.length == 0) {
+ return classes;
+ }
+ return ArrayUtils.setAll(new Class[classes.length], i -> primitiveToWrapper(classes[i]));
}
/**
- * Gets the canonical name minus the package name from a {@code Class}.
+ * Converts the specified primitive Class object to its corresponding wrapper Class object.
*
- * @param cls the class for which to get the short canonical class name; may be null
- * @return the canonical name without the package name or an empty string
- * @since 2.4
+ *
+ * NOTE: From v2.2, this method handles {@code Void.TYPE}, returning {@code Void.TYPE}.
+ *
+ *
+ * @param cls The class to convert, may be null.
+ * @return The wrapper class for {@code cls} or {@code cls} if {@code cls} is not a primitive. {@code null} if null input.
+ * @since 2.1
*/
- public static String getShortCanonicalName(final Class cls) {
- if (cls == null) {
- return StringUtils.EMPTY;
- }
- return getShortCanonicalName(cls.getName());
+ public static Class primitiveToWrapper(final Class cls) {
+ return cls != null && cls.isPrimitive() ? PRIMITIVE_WRAPPER_MAP.get(cls) : cls;
}
/**
- * Gets the canonical name minus the package name from a String.
- *
- * The string passed in is assumed to be a class name - it is not checked.
- *
- * Note that this method is mainly designed to handle the arrays and primitives properly.
- * If the class is an inner class then the result value will not contain the outer classes.
- * This way the behavior of this method is different from {@link #getShortClassName(String)}.
- * The argument in that case is class name and not canonical name and the return value
- * retains the outer classes.
- *
- * Note that there is no way to reliably identify the part of the string representing the
- * package hierarchy and the part that is the outer class or classes in case of an inner class.
- * Trying to find the class would require reflective call and the class itself may not even be
- * on the class path. Relying on the fact that class names start with capital letter and packages
- * with lower case is heuristic.
+ * Converts an array of {@link Object} in to an array of {@link Class} objects. If any of these objects is null, a null element will be inserted into the
+ * array.
*
- * It is recommended to use {@link #getShortClassName(String)} for cases when the class
- * is an inner class and use this method for cases it is designed for.
- *
- *
- * Examples
- * return value input {@code ""} {@code (String)null} {@code "Map.Entry"} {@code java.util.Map.Entry.class.getName()} {@code "Entry"} {@code java.util.Map.Entry.class.getCanonicalName()} {@code "ClassUtils"} {@code "org.apache.commons.lang3.ClassUtils"} {@code "ClassUtils[]"} {@code "[Lorg.apache.commons.lang3.ClassUtils;"} {@code "ClassUtils[][]"} {@code "[[Lorg.apache.commons.lang3.ClassUtils;"} {@code "ClassUtils[]"} {@code "org.apache.commons.lang3.ClassUtils[]"} {@code "ClassUtils[][]"} {@code "org.apache.commons.lang3.ClassUtils[][]"} {@code "int[]"} {@code "[I"} {@code "int[]"} {@code int[].class.getCanonicalName()} {@code "int[]"} {@code int[].class.getName()} {@code "int[][]"} {@code "[[I"} {@code "int[]"} {@code "int[]"} {@code "int[][]"} {@code "int[][]"}
+ *
+ * This method returns {@code null} for a {@code null} input array.
+ *
*
- * @param canonicalName the class name to get the short name for
- * @return the canonical name of the class without the package name or an empty string
+ * @param array An {@link Object} array.
+ * @return A {@link Class} array, {@code null} if null array input.
* @since 2.4
*/
- public static String getShortCanonicalName(final String canonicalName) {
- return getShortClassName(getCanonicalName(canonicalName));
+ public static Class[] toClass(final Object... array) {
+ if (array == null) {
+ return null;
+ }
+ if (array.length == 0) {
+ return ArrayUtils.EMPTY_CLASS_ARRAY;
+ }
+ return ArrayUtils.setAll(new Class[array.length], i -> array[i] == null ? null : array[i].getClass());
}
- // Package name
- // ----------------------------------------------------------------------
/**
- * Gets the package name from the class name of an {@code Object}.
+ * Converts and cleans up a class name to a JLS style class name.
+ *
+ * The provided class name is normalized by removing all whitespace. This is especially helpful when handling XML element values in which whitespace has not
+ * been collapsed.
+ *
*
- * @param object the class to get the package name for, may be null
- * @param valueIfNull the value to return if null
- * @return the package name of the object, or the null value
- * @since 2.4
- */
- public static String getPackageCanonicalName(final Object object, final String valueIfNull) {
- if (object == null) {
- return valueIfNull;
- }
- return getPackageCanonicalName(object.getClass().getName());
+ * @param className The class name.
+ * @return The converted name.
+ * @throws NullPointerException if the className is null.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
+ * @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 String toCleanName(final String className) {
+ return toEncodedName(StringUtils.deleteWhitespace(className));
}
/**
- * Gets the package name from the canonical name of a {@code Class}.
+ * Converts a class name to a JLS style class name without normalizing whitespace.
*
- * @param cls the class to get the package name for, may be {@code null}.
- * @return the package name or an empty string
- * @since 2.4
+ * @param className The class name.
+ * @return The converted name.
+ * @throws NullPointerException if the className is null.
+ * @throws IllegalArgumentException Thrown if the class name represents an array with more dimensions than the JVM supports, 255.
+ * @throws IllegalArgumentException Thrown if the class name length is greater than 65,535.
*/
- public static String getPackageCanonicalName(final Class cls) {
- if (cls == null) {
- return StringUtils.EMPTY;
+ private static String toEncodedName(final String className) {
+ String canonicalName = className;
+ Objects.requireNonNull(canonicalName, "className");
+ if (canonicalName.isEmpty()) {
+ throw new IllegalArgumentException("Class name is empty");
}
- return getPackageCanonicalName(cls.getName());
+ final String encodedArrayOpen = "[";
+ final String encodedClassNameStart = "L";
+ final String encodedClassNameEnd = ";";
+ final boolean encodedName = canonicalName.startsWith(encodedArrayOpen) && canonicalName.endsWith(encodedClassNameEnd);
+ if (encodedName) {
+ final int arrIdx = canonicalName.indexOf(encodedClassNameStart);
+ if (arrIdx > MAX_JVM_ARRAY_DIMENSION) {
+ throw new IllegalArgumentException("Array dimension greater than JVM specification maximum of 255.");
+ }
+ if (arrIdx < 0) {
+ throw new IllegalArgumentException("Expected 'L' after '[' for an array style string.");
+ }
+ final int cnLen = canonicalName.length() - (arrIdx + 2); // account for the ending ';'
+ if (cnLen > MAX_CLASS_NAME_LENGTH) {
+ throw new IllegalArgumentException(String.format("Class name greater than maxium length %,d", MAX_CLASS_NAME_LENGTH));
+ }
+ }
+ final String arrayMarker = "[]";
+ final int arrIdx = canonicalName.indexOf(arrayMarker);
+ // The class name length without array markers.
+ final int cnLen = arrIdx > 0 ? arrIdx : canonicalName.length();
+ if (cnLen > MAX_CLASS_NAME_LENGTH && !encodedName) {
+ throw new IllegalArgumentException(String.format("Class name greater than maxium length %,d", MAX_CLASS_NAME_LENGTH));
+ }
+ if (canonicalName.endsWith(arrayMarker)) {
+ // Reject malformed inputs like "java.lang.String[]junk[]" or
+ // "java.lang.String[]][]" where the suffix is not composed of
+ // repeated "[]" pairs.
+ final String tail = canonicalName.substring(arrIdx);
+ if (!ARRAY_TAIL_PATTERN.matcher(tail).matches()) {
+ throw new IllegalArgumentException("Malformed array name: " + canonicalName);
+ }
+ final int dims = (canonicalName.length() - arrIdx) / 2;
+ if (dims > MAX_JVM_ARRAY_DIMENSION) {
+ throw new IllegalArgumentException("Array dimension greater than JVM specification maximum of 255.");
+ }
+ final StringBuilder classNameBuffer = new StringBuilder(StringUtils.repeat(encodedArrayOpen, dims));
+ canonicalName = canonicalName.substring(0, arrIdx);
+ final String abbreviation = ABBREVIATION_MAP.get(canonicalName);
+ if (abbreviation != null) {
+ classNameBuffer.append(abbreviation);
+ } else {
+ classNameBuffer.append(encodedClassNameStart).append(canonicalName).append(encodedClassNameEnd);
+ }
+ canonicalName = classNameBuffer.toString();
+ }
+ return canonicalName;
}
/**
- * Gets the package name from the class name.
+ * Decides if the part that was just copied to its destination location in the work array can be kept as it was copied
+ * or must be abbreviated. It must be kept when the part is the last one, which is the simple name of the class. In this
+ * case the {@code source} index, from where the characters are copied points one position after the last character,
+ * a.k.a. {@code source ==
+ * originalLength}
*
- * The string passed in is assumed to be a class name - it is not checked.
- * If the class is in the default package, return an empty string.
+ *
+ * If the part is not the last one then it can be kept unabridged if the number of the characters copied so far plus the
+ * character that are to be copied is less than or equal to the desired length.
+ *
*
- * @param name the name to get the package name for, may be {@code null}
- * @return the package name or an empty string
- * @since 2.4
+ * @param runAheadTarget The target index (where the characters were copied to) pointing after the last character copied
+ * when the current part was copied.
+ * @param source The source index (where the characters were copied from) pointing after the last character copied when
+ * the current part was copied.
+ * @param originalLength The original length of the class full name, which is abbreviated.
+ * @param desiredLength The desired length of the abbreviated class name.
+ * @return {@code true} if it can be kept in its original length; {@code false} if the current part has to be abbreviated.
*/
- public static String getPackageCanonicalName(final String name) {
- return getPackageName(getCanonicalName(name));
+ private static boolean useFull(final int runAheadTarget, final int source, final int originalLength, final int desiredLength) {
+ return source >= originalLength || runAheadTarget + originalLength - source <= desiredLength;
}
/**
- * Converts a given name of class into canonical format.
- * If name of class is not a name of array class it returns
- * unchanged name.
+ * Converts the specified array of wrapper Class objects to an array of its corresponding primitive Class objects.
*
- * The method does not change the {@code $} separators in case
- * the class is inner class.
- *
- * Example:
- *
- * {@code getCanonicalName("[I") = "int[]"}
- * {@code getCanonicalName("[Ljava.lang.String;") = "java.lang.String[]"}
- * {@code getCanonicalName("java.lang.String") = "java.lang.String"}
- *
+ *
+ * This method invokes {@code wrapperToPrimitive()} for each element of the passed in array.
*
*
- * @param className the name of class
- * @return canonical form of class name
+ * @param classes The class array to convert, may be null or empty.
+ * @return An array which contains for each given class, the primitive class or {@code null} if the original class is not a wrapper class.
+ * {@code null} if null input. Empty array if an empty array passed in.
+ * @see #wrapperToPrimitive(Class)
* @since 2.4
*/
- private static String getCanonicalName(String className) {
- className = StringUtils.deleteWhitespace(className);
- if (className == null) {
+ public static Class[] wrappersToPrimitives(final Class... classes) {
+ if (classes == null) {
return null;
}
- int dim = 0;
- while (className.startsWith("[")) {
- dim++;
- className = className.substring(1);
- }
- if (dim < 1) {
- return className;
- }
- if (className.startsWith("L")) {
- className = className.substring(
- 1,
- className.endsWith(";")
- ? className.length() - 1
- : className.length());
- } else {
- if (!className.isEmpty()) {
- className = reverseAbbreviationMap.get(className.substring(0, 1));
- }
- }
- final StringBuilder canonicalClassNameBuffer = new StringBuilder(className);
- for (int i = 0; i < dim; i++) {
- canonicalClassNameBuffer.append("[]");
+ if (classes.length == 0) {
+ return classes;
}
- return canonicalClassNameBuffer.toString();
+ return ArrayUtils.setAll(new Class[classes.length], i -> wrapperToPrimitive(classes[i]));
}
/**
- * Get an {@link Iterable} that can iterate over a class hierarchy in ascending (subclass to superclass) order,
- * excluding interfaces.
+ * Converts the specified wrapper class to its corresponding primitive class.
*
- * @param type the type to get the class hierarchy from
- * @return Iterable an Iterable over the class hierarchy of the given class
- * @since 3.2
+ *
+ * This method is the counter part of {@code primitiveToWrapper()}. If the passed in class is a wrapper class for a
+ * primitive type, this primitive type will be returned (e.g. {@code Integer.TYPE} for {@code Integer.class}). For other
+ * classes, or if the parameter is {@code null}, the return value is {@code null}.
+ *
+ *
+ * @param cls The class to convert, may be {@code null}.
+ * @return The corresponding primitive type if {@code cls} is a wrapper class, {@code null} otherwise.
+ * @see #primitiveToWrapper(Class)
+ * @since 2.4
*/
- public static Iterable> hierarchy(final Class type) {
- return hierarchy(type, Interfaces.EXCLUDE);
+ public static Class wrapperToPrimitive(final Class cls) {
+ return WRAPPER_PRIMITIVE_MAP.get(cls);
}
/**
- * Get an {@link Iterable} that can iterate over a class hierarchy in ascending (subclass to superclass) order.
+ * ClassUtils instances should NOT be constructed in standard programming. Instead, the class should be used as
+ * {@code ClassUtils.getShortClassName(cls)}.
*
- * @param type the type to get the class hierarchy from
- * @param interfacesBehavior switch indicating whether to include or exclude interfaces
- * @return Iterable an Iterable over the class hierarchy of the given class
- * @since 3.2
+ *
+ * This constructor is public to permit tools that require a JavaBean instance to operate.
+ *
+ *
+ * @deprecated TODO Make private in 4.0.
*/
- public static Iterable> hierarchy(final Class type, final Interfaces interfacesBehavior) {
- final Iterable> classes = () -> {
- final MutableObject> next = new MutableObject<>(type);
- return new Iterator>() {
-
- @Override
- public boolean hasNext() {
- return next.getValue() != null;
- }
-
- @Override
- public Class next() {
- final Class result = next.getValue();
- next.setValue(result.getSuperclass());
- return result;
- }
-
- @Override
- public void remove() {
- throw new UnsupportedOperationException();
- }
-
- };
- };
- if (interfacesBehavior != Interfaces.INCLUDE) {
- return classes;
- }
- return () -> {
- final Set> seenInterfaces = new HashSet<>();
- final Iterator> wrapped = classes.iterator();
-
- return new Iterator>() {
- Iterator> interfaces = Collections.>emptySet().iterator();
-
- @Override
- public boolean hasNext() {
- return interfaces.hasNext() || wrapped.hasNext();
- }
-
- @Override
- public Class next() {
- if (interfaces.hasNext()) {
- final Class nextInterface = interfaces.next();
- seenInterfaces.add(nextInterface);
- return nextInterface;
- }
- final Class nextSuperclass = wrapped.next();
- final Set> currentInterfaces = new LinkedHashSet<>();
- walkInterfaces(currentInterfaces, nextSuperclass);
- interfaces = currentInterfaces.iterator();
- return nextSuperclass;
- }
-
- private void walkInterfaces(final Set> addTo, final Class c) {
- for (final Class iface : c.getInterfaces()) {
- if (!seenInterfaces.contains(iface)) {
- addTo.add(iface);
- }
- walkInterfaces(addTo, iface);
- }
- }
-
- @Override
- public void remove() {
- throw new UnsupportedOperationException();
- }
-
- };
- };
+ @Deprecated
+ public ClassUtils() {
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/Conversion.java b/src/main/java/org/apache/commons/lang3/Conversion.java
index 18873d917b9..cf43e36c371 100644
--- a/src/main/java/org/apache/commons/lang3/Conversion.java
+++ b/src/main/java/org/apache/commons/lang3/Conversion.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,
@@ -14,19 +14,20 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.lang3;
import java.util.UUID;
-
/**
- *
* Static methods to convert a type into another, with endianness and bit ordering awareness.
- *
+ *
*
- * The methods names follow a naming rule:[source endianness][source bit ordering]To[destination endianness][destination bit ordering]}
+ * The methods names follow a naming rule:
*
+ * {@code
+ * [source endianness][source bit ordering]To[destination endianness][destination bit ordering]
+ * }
*
* Source/destination type fields is one of the following:
*
@@ -36,275 +37,170 @@
* int or intArray
* long or longArray
* hex: a String containing hexadecimal digits (lowercase in destination)
- * hexDigit: a Char containing a hexadecimal digit (lowercase in destination)
+ * hexDigit: a {@code char} containing a hexadecimal digit (lowercase in destination)
* uuid
*
*
- * Endianness field: little endian is the default, in this case the field is absent. In case of
- * big endian, the field is "Be".
+ *
+ * Bit ordering: LSB0 is the default, in this case the field is absent. In case of MSB0, the field is "Msb0" (Camel-case).
*
*
- * Example: intBeMsb0ToHex convert an int with big endian byte order and Msb0 bit order into its
- * hexadecimal string representation
+ * Example: intBeMsb0ToHex convert an {@code int} with big-endian byte order and MSB0 bit order into its hexadecimal string representation
*
*
- * Most of the methods provide only default encoding for destination, this limits the number of
- * ways to do one thing. Unless you are dealing with data from/to outside of the JVM platform,
- * you should not need to use "Be" and "Msb0" methods.
+ * Most of the methods provide only default encoding for destination, this limits the number of ways to do one thing. Unless you are dealing with data from/to
+ * outside of the JVM platform, you should not need to use "Be" and "Msb0" methods.
*
*
- * Development status: work on going, only a part of the little endian, Lsb0 methods implemented
- * so far.
+ * Development status: work on going, only a part of the little-endian, LSB0 methods implemented so far.
*
*
* @since 3.2
*/
-
public class Conversion {
- private static final boolean[] TTTT = {true, true, true, true};
- private static final boolean[] FTTT = {false, true, true, true};
- private static final boolean[] TFTT = {true, false, true, true};
- private static final boolean[] FFTT = {false, false, true, true};
- private static final boolean[] TTFT = {true, true, false, true};
- private static final boolean[] FTFT = {false, true, false, true};
- private static final boolean[] TFFT = {true, false, false, true};
- private static final boolean[] FFFT = {false, false, false, true};
- private static final boolean[] TTTF = {true, true, true, false};
- private static final boolean[] FTTF = {false, true, true, false};
- private static final boolean[] TFTF = {true, false, true, false};
- private static final boolean[] FFTF = {false, false, true, false};
- private static final boolean[] TTFF = {true, true, false, false};
- private static final boolean[] FTFF = {false, true, false, false};
- private static final boolean[] TFFF = {true, false, false, false};
- private static final boolean[] FFFF = {false, false, false, false};
+ private static final boolean[] TTTT = { true, true, true, true };
+ private static final boolean[] FTTT = { false, true, true, true };
+ private static final boolean[] TFTT = { true, false, true, true };
+ private static final boolean[] FFTT = { false, false, true, true };
+ private static final boolean[] TTFT = { true, true, false, true };
+ private static final boolean[] FTFT = { false, true, false, true };
+ private static final boolean[] TFFT = { true, false, false, true };
+ private static final boolean[] FFFT = { false, false, false, true };
+ private static final boolean[] TTTF = { true, true, true, false };
+ private static final boolean[] FTTF = { false, true, true, false };
+ private static final boolean[] TFTF = { true, false, true, false };
+ private static final boolean[] FFTF = { false, false, true, false };
+ private static final boolean[] TTFF = { true, true, false, false };
+ private static final boolean[] FTFF = { false, true, false, false };
+ private static final boolean[] TFFF = { true, false, false, false };
+ private static final boolean[] FFFF = { false, false, false, false };
/**
- *
- * Converts a hexadecimal digit into an int using the default (Lsb0) bit ordering.
- *
- *
- * '1' is converted to 1
- *
+ * Converts the first 4 bits of a binary (represented as boolean array) in big-endian MSB0 bit ordering to a hexadecimal digit.
*
- * @param hexDigit the hexadecimal digit to convert
- * @return an int equals to {@code hexDigit}
- * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit
- */
- public static int hexDigitToInt(final char hexDigit) {
- final int digit = Character.digit(hexDigit, 16);
- if (digit < 0) {
- throw new IllegalArgumentException("Cannot interpret '" + hexDigit + "' as a hexadecimal digit");
- }
- return digit;
- }
-
- /**
- *
- * Converts a hexadecimal digit into an int using the Msb0 bit ordering.
- *
*
- * '1' is converted to 8
+ * (1, 0, 0, 0) is converted as follow: '8' (1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0) is converted to '4'.
*
*
- * @param hexDigit the hexadecimal digit to convert
- * @return an int equals to {@code hexDigit}
- * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit
+ * @param src The binary to convert.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty.
+ * @throws NullPointerException if {@code src} is {@code null}.
*/
- public static int hexDigitMsb0ToInt(final char hexDigit) {
- switch (hexDigit) {
- case '0':
- return 0x0;
- case '1':
- return 0x8;
- case '2':
- return 0x4;
- case '3':
- return 0xC;
- case '4':
- return 0x2;
- case '5':
- return 0xA;
- case '6':
- return 0x6;
- case '7':
- return 0xE;
- case '8':
- return 0x1;
- case '9':
- return 0x9;
- case 'a':// fall through
- case 'A':
- return 0x5;
- case 'b':// fall through
- case 'B':
- return 0xD;
- case 'c':// fall through
- case 'C':
- return 0x3;
- case 'd':// fall through
- case 'D':
- return 0xB;
- case 'e':// fall through
- case 'E':
- return 0x7;
- case 'f':// fall through
- case 'F':
- return 0xF;
- default:
- throw new IllegalArgumentException("Cannot interpret '" + hexDigit + "' as a hexadecimal digit");
- }
+ public static char binaryBeMsb0ToHexDigit(final boolean[] src) {
+ return binaryBeMsb0ToHexDigit(src, 0);
}
/**
+ * Converts a binary (represented as boolean array) in big-endian MSB0 bit ordering to a hexadecimal digit.
+ *
*
- * Converts a hexadecimal digit into binary (represented as boolean array) using the default
- * (Lsb0) bit ordering.
- *
- *
- * '1' is converted as follow: (1, 0, 0, 0)
+ * (1, 0, 0, 0) with srcPos = 0 is converted as follow: '8' (1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0) with srcPos = 2 is converted to '5'.
*
*
- * @param hexDigit the hexadecimal digit to convert
- * @return a boolean array with the binary representation of {@code hexDigit}
- * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit
+ * @param src The binary to convert.
+ * @param srcPos The position of the LSB to start the conversion.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IndexOutOfBoundsException if {@code srcPos} is outside the array.
*/
- public static boolean[] hexDigitToBinary(final char hexDigit) {
- switch (hexDigit) {
- case '0':
- return FFFF.clone();
- case '1':
- return TFFF.clone();
- case '2':
- return FTFF.clone();
- case '3':
- return TTFF.clone();
- case '4':
- return FFTF.clone();
- case '5':
- return TFTF.clone();
- case '6':
- return FTTF.clone();
- case '7':
- return TTTF.clone();
- case '8':
- return FFFT.clone();
- case '9':
- return TFFT.clone();
- case 'a':// fall through
- case 'A':
- return FTFT.clone();
- case 'b':// fall through
- case 'B':
- return TTFT.clone();
- case 'c':// fall through
- case 'C':
- return FFTT.clone();
- case 'd':// fall through
- case 'D':
- return TFTT.clone();
- case 'e':// fall through
- case 'E':
- return FTTT.clone();
- case 'f':// fall through
- case 'F':
- return TTTT.clone();
- default:
- throw new IllegalArgumentException("Cannot interpret '" + hexDigit + "' as a hexadecimal digit");
+ public static char binaryBeMsb0ToHexDigit(final boolean[] src, final int srcPos) {
+ // JDK 9: Objects.checkIndex(int index, int length)
+ if (Integer.compareUnsigned(srcPos, src.length) >= 0) {
+ // Throw the correct exception
+ if (src.length == 0) {
+ throw new IllegalArgumentException("Cannot convert an empty array.");
+ }
+ throw new IndexOutOfBoundsException(srcPos + " is not within array length " + src.length);
+ }
+ // Little-endian bit 0 position
+ final int pos = src.length - 1 - srcPos;
+ if (3 <= pos && src[pos - 3]) {
+ if (src[pos - 2]) {
+ if (src[pos - 1]) {
+ return src[pos] ? 'f' : 'e';
+ }
+ return src[pos] ? 'd' : 'c';
+ }
+ if (src[pos - 1]) {
+ return src[pos] ? 'b' : 'a';
+ }
+ return src[pos] ? '9' : '8';
+ }
+ if (2 <= pos && src[pos - 2]) {
+ if (src[pos - 1]) {
+ return src[pos] ? '7' : '6';
+ }
+ return src[pos] ? '5' : '4';
+ }
+ if (1 <= pos && src[pos - 1]) {
+ return src[pos] ? '3' : '2';
}
+ return src[pos] ? '1' : '0';
}
/**
- *
- * Converts a hexadecimal digit into binary (represented as boolean array) using the Msb0
- * bit ordering.
- *
- *
- * '1' is converted as follow: (0, 0, 0, 1)
- *
+ * Converts binary (represented as boolean array) into a byte using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param hexDigit the hexadecimal digit to convert
- * @return a boolean array with the binary representation of {@code hexDigit}
- * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit
+ * @param src The binary to convert.
+ * @param srcPos The position in {@code src}, in boolean unit, from where to start the conversion.
+ * @param dstInit initial value of the destination byte.
+ * @param dstPos The position of the LSB, in bits, in the result byte.
+ * @param nBools The number of booleans to convert.
+ * @return A byte containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + dstPos >= 8}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}.
*/
- public static boolean[] hexDigitMsb0ToBinary(final char hexDigit) {
- switch (hexDigit) {
- case '0':
- return FFFF.clone();
- case '1':
- return FFFT.clone();
- case '2':
- return FFTF.clone();
- case '3':
- return FFTT.clone();
- case '4':
- return FTFF.clone();
- case '5':
- return FTFT.clone();
- case '6':
- return FTTF.clone();
- case '7':
- return FTTT.clone();
- case '8':
- return TFFF.clone();
- case '9':
- return TFFT.clone();
- case 'a':// fall through
- case 'A':
- return TFTF.clone();
- case 'b':// fall through
- case 'B':
- return TFTT.clone();
- case 'c':// fall through
- case 'C':
- return TTFF.clone();
- case 'd':// fall through
- case 'D':
- return TTFT.clone();
- case 'e':// fall through
- case 'E':
- return TTTF.clone();
- case 'f':// fall through
- case 'F':
- return TTTT.clone();
- default:
- throw new IllegalArgumentException("Cannot interpret '" + hexDigit + "' as a hexadecimal digit");
+ public static byte binaryToByte(final boolean[] src, final int srcPos, final byte dstInit, final int dstPos, final int nBools) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ return dstInit;
+ }
+ if ((long) nBools - 1 + dstPos >= Byte.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + dstPos >= 8");
+ }
+ byte out = dstInit;
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + dstPos;
+ final int bits = (src[i + srcPos] ? 1 : 0) << shift;
+ final int mask = 0x1 << shift;
+ out = (byte) (out & ~mask | bits);
}
+ return out;
}
/**
+ * Converts binary (represented as boolean array) to a hexadecimal digit using the default (LSB0) bit ordering.
+ *
*
- * Converts binary (represented as boolean array) to a hexadecimal digit using the default
- * (Lsb0) bit ordering.
- *
- *
- * (1, 0, 0, 0) is converted as follow: '1'
+ * (1, 0, 0, 0) is converted as follow: '1'.
*
*
- * @param src the binary to convert
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty.
+ * @throws NullPointerException if {@code src} is {@code null}.
*/
public static char binaryToHexDigit(final boolean[] src) {
return binaryToHexDigit(src, 0);
}
/**
+ * Converts binary (represented as boolean array) to a hexadecimal digit using the default (LSB0) bit ordering.
+ *
*
- * Converts binary (represented as boolean array) to a hexadecimal digit using the default
- * (Lsb0) bit ordering.
- *
- *
- * (1, 0, 0, 0) is converted as follow: '1'
+ * (1, 0, 0, 0) is converted as follow: '1'.
*
*
- * @param src the binary to convert
- * @param srcPos the position of the lsb to start the conversion
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @param srcPos The position of the LSB to start the conversion.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty.
+ * @throws NullPointerException if {@code src} is {@code null}.
*/
public static char binaryToHexDigit(final boolean[] src, final int srcPos) {
if (src.length == 0) {
@@ -335,47 +231,40 @@ public static char binaryToHexDigit(final boolean[] src, final int srcPos) {
}
/**
+ * Converts binary (represented as boolean array) to a hexadecimal digit using the MSB0 bit ordering.
+ *
*
- * Converts binary (represented as boolean array) to a hexadecimal digit using the Msb0 bit
- * ordering.
- *
- *
- * (1, 0, 0, 0) is converted as follow: '8'
+ * (1, 0, 0, 0) is converted as follow: '8'.
*
*
- * @param src the binary to convert
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty, {@code src.length < 4} or
- * {@code src.length > 8}
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty, {@code src.length < 4} or {@code src.length > 8}.
+ * @throws NullPointerException if {@code src} is {@code null}.
*/
public static char binaryToHexDigitMsb0_4bits(final boolean[] src) {
return binaryToHexDigitMsb0_4bits(src, 0);
}
/**
+ * Converts binary (represented as boolean array) to a hexadecimal digit using the MSB0 bit ordering.
+ *
*
- * Converts binary (represented as boolean array) to a hexadecimal digit using the Msb0 bit
- * ordering.
- *
- *
- * (1, 0, 0, 0) is converted as follow: '8' (1, 0, 0, 1, 1, 0, 1, 0) with srcPos = 3 is converted
- * to 'D'
+ * (1, 0, 0, 0) is converted as follow: '8' (1, 0, 0, 1, 1, 0, 1, 0) with srcPos = 3 is converted to 'D'
*
*
- * @param src the binary to convert
- * @param srcPos the position of the lsb to start the conversion
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty, {@code src.length > 8} or
- * {@code src.length - srcPos < 4}
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @param srcPos The position of the LSB to start the conversion.
+ * @return A hexadecimal digit representing the selected bits.
+ * @throws IllegalArgumentException if {@code src} is empty, {@code src.length > 8} or {@code src.length - srcPos < 4}.
+ * @throws NullPointerException if {@code src} is {@code null}.
*/
public static char binaryToHexDigitMsb0_4bits(final boolean[] src, final int srcPos) {
- if (src.length > 8) {
- throw new IllegalArgumentException("src.length>8: src.length=" + src.length);
+ if (src.length > Byte.SIZE) {
+ throw new IllegalArgumentException("src.length > 8: src.length=" + src.length);
}
if (src.length - srcPos < 4) {
- throw new IllegalArgumentException("src.length-srcPos<4: src.length=" + src.length + ", srcPos=" + srcPos);
+ throw new IllegalArgumentException("src.length - srcPos < 4: src.length=" + src.length + ", srcPos=" + srcPos);
}
if (src[srcPos + 3]) {
if (src[srcPos + 2]) {
@@ -402,859 +291,864 @@ public static char binaryToHexDigitMsb0_4bits(final boolean[] src, final int src
}
/**
- *
- * Converts the first 4 bits of a binary (represented as boolean array) in big endian Msb0
- * bit ordering to a hexadecimal digit.
- *
- *
- * (1, 0, 0, 0) is converted as follow: '8' (1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0) is converted
- * to '4'
- *
+ * Converts binary (represented as boolean array) into an int using the default (little endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @param srcPos The position in {@code src}, in boolean unit, from where to start the conversion.
+ * @param dstInit initial value of the destination int.
+ * @param dstPos The position of the LSB, in bits, in the result int.
+ * @param nBools The number of booleans to convert.
+ * @return An int containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + dstPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}.
*/
- public static char binaryBeMsb0ToHexDigit(final boolean[] src) {
- return binaryBeMsb0ToHexDigit(src, 0);
+ public static int binaryToInt(final boolean[] src, final int srcPos, final int dstInit, final int dstPos, final int nBools) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ return dstInit;
+ }
+ if ((long) nBools - 1 + dstPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + dstPos >= 32");
+ }
+ int out = dstInit;
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + dstPos;
+ final int bits = (src[i + srcPos] ? 1 : 0) << shift;
+ final int mask = 0x1 << shift;
+ out = out & ~mask | bits;
+ }
+ return out;
}
/**
- *
- * Converts a binary (represented as boolean array) in big endian Msb0 bit ordering to a
- * hexadecimal digit.
- *
- *
- * (1, 0, 0, 0) with srcPos = 0 is converted as follow: '8' (1, 0, 0, 0, 0, 0, 0, 0,
- * 0, 0, 0, 1, 0, 1, 0, 0) with srcPos = 2 is converted to '5'
- *
+ * Converts binary (represented as boolean array) into a long using the default (little endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @param srcPos the position of the lsb to start the conversion
- * @return a hexadecimal digit representing the selected bits
- * @throws IllegalArgumentException if {@code src} is empty
- * @throws NullPointerException if {@code src} is {@code null}
+ * @param src The binary to convert.
+ * @param srcPos The position in {@code src}, in boolean unit, from where to start the conversion.
+ * @param dstInit initial value of the destination long.
+ * @param dstPos The position of the LSB, in bits, in the result long.
+ * @param nBools The number of booleans to convert.
+ * @return A long containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + dstPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}.
*/
- public static char binaryBeMsb0ToHexDigit(boolean[] src, int srcPos) {
- if (src.length == 0) {
- throw new IllegalArgumentException("Cannot convert an empty array.");
- }
- final int beSrcPos = src.length - 1 - srcPos;
- final int srcLen = Math.min(4, beSrcPos + 1);
- final boolean[] paddedSrc = new boolean[4];
- System.arraycopy(src, beSrcPos + 1 - srcLen, paddedSrc, 4 - srcLen, srcLen);
- src = paddedSrc;
- srcPos = 0;
- if (src[srcPos]) {
- if (src.length > srcPos + 1 && src[srcPos + 1]) {
- if (src.length > srcPos + 2 && src[srcPos + 2]) {
- return src.length > srcPos + 3 && src[srcPos + 3] ? 'f' : 'e';
- }
- return src.length > srcPos + 3 && src[srcPos + 3] ? 'd' : 'c';
- }
- if (src.length > srcPos + 2 && src[srcPos + 2]) {
- return src.length > srcPos + 3 && src[srcPos + 3] ? 'b' : 'a';
- }
- return src.length > srcPos + 3 && src[srcPos + 3] ? '9' : '8';
+ public static long binaryToLong(final boolean[] src, final int srcPos, final long dstInit, final int dstPos, final int nBools) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ return dstInit;
}
- if (src.length > srcPos + 1 && src[srcPos + 1]) {
- if (src.length > srcPos + 2 && src[srcPos + 2]) {
- return src.length > srcPos + 3 && src[srcPos + 3] ? '7' : '6';
- }
- return src.length > srcPos + 3 && src[srcPos + 3] ? '5' : '4';
+ if ((long) nBools - 1 + dstPos >= Long.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + dstPos >= 64");
}
- if (src.length > srcPos + 2 && src[srcPos + 2]) {
- return src.length > srcPos + 3 && src[srcPos + 3] ? '3' : '2';
+ long out = dstInit;
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + dstPos;
+ final long bits = (src[i + srcPos] ? 1L : 0) << shift;
+ final long mask = 0x1L << shift;
+ out = out & ~mask | bits;
}
- return src.length > srcPos + 3 && src[srcPos + 3] ? '1' : '0';
+ return out;
}
/**
- *
- * Converts the 4 lsb of an int to a hexadecimal digit.
- *
- *
- * 0 returns '0'
- *
- *
- * 1 returns '1'
- *
- *
- * 10 returns 'A' and so on...
- *
+ * Converts binary (represented as boolean array) into a short using the default (little endian, LSB0) byte and bit ordering.
*
- * @param nibble the 4 bits to convert
- * @return a hexadecimal digit representing the 4 lsb of {@code nibble}
- * @throws IllegalArgumentException if {@code nibble < 0} or {@code nibble > 15}
+ * @param src The binary to convert.
+ * @param srcPos The position in {@code src}, in boolean unit, from where to start the conversion.
+ * @param dstInit initial value of the destination short.
+ * @param dstPos The position of the LSB, in bits, in the result short.
+ * @param nBools The number of booleans to convert.
+ * @return A short containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + dstPos >= 16}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}.
*/
- public static char intToHexDigit(final int nibble) {
- final char c = Character.forDigit(nibble, 16);
- if (c == Character.MIN_VALUE) {
- throw new IllegalArgumentException("nibble value not between 0 and 15: " + nibble);
+ public static short binaryToShort(final boolean[] src, final int srcPos, final short dstInit, final int dstPos, final int nBools) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ return dstInit;
}
- return c;
+ if ((long) nBools - 1 + dstPos >= Short.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + dstPos >= 16");
+ }
+ short out = dstInit;
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + dstPos;
+ final int bits = (src[i + srcPos] ? 1 : 0) << shift;
+ final int mask = 0x1 << shift;
+ out = (short) (out & ~mask | bits);
+ }
+ return out;
}
/**
- *
- * Converts the 4 lsb of an int to a hexadecimal digit encoded using the Msb0 bit ordering.
- *
- *
- * 0 returns '0'
- *
- *
- * 1 returns '8'
- *
- *
- * 10 returns '5' and so on...
- *
+ * Converts an array of byte into an int using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param nibble the 4 bits to convert
- * @return a hexadecimal digit representing the 4 lsb of {@code nibble}
- * @throws IllegalArgumentException if {@code nibble < 0} or {@code nibble > 15}
+ * @param src The byte array to convert.
+ * @param srcPos The position in {@code src}, in byte unit, from where to start the conversion.
+ * @param dstInit initial value of the destination int.
+ * @param dstPos The position of the LSB, in bits, in the result int.
+ * @param nBytes The number of bytes to convert.
+ * @return An int containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + dstPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}.
*/
- public static char intToHexDigitMsb0(final int nibble) {
- switch (nibble) {
- case 0x0:
- return '0';
- case 0x1:
- return '8';
- case 0x2:
- return '4';
- case 0x3:
- return 'c';
- case 0x4:
- return '2';
- case 0x5:
- return 'a';
- case 0x6:
- return '6';
- case 0x7:
- return 'e';
- case 0x8:
- return '1';
- case 0x9:
- return '9';
- case 0xA:
- return '5';
- case 0xB:
- return 'd';
- case 0xC:
- return '3';
- case 0xD:
- return 'b';
- case 0xE:
- return '7';
- case 0xF:
- return 'f';
- default:
- throw new IllegalArgumentException("nibble value not between 0 and 15: " + nibble);
+ public static int byteArrayToInt(final byte[] src, final int srcPos, final int dstInit, final int dstPos, final int nBytes) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
+ return dstInit;
+ }
+ if (((long) nBytes - 1) * Byte.SIZE + dstPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + dstPos >= 32");
+ }
+ int out = dstInit;
+ for (int i = 0; i < nBytes; i++) {
+ final int shift = i * Byte.SIZE + dstPos;
+ final int bits = (0xff & src[i + srcPos]) << shift;
+ final int mask = 0xff << shift;
+ out = out & ~mask | bits;
}
+ return out;
}
/**
- *
- * Converts an array of int into a long using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts an array of byte into a long using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the int array to convert
- * @param srcPos the position in {@code src}, in int unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination long
- * @param dstPos the position of the lsb, in bits, in the result long
- * @param nInts the number of ints to convert
- * @return a long containing the selected bits
- * @throws IllegalArgumentException if {@code (nInts-1)*32+dstPos >= 64}
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nInts > src.length}
+ * @param src The byte array to convert.
+ * @param srcPos The position in {@code src}, in byte unit, from where to start the conversion.
+ * @param dstInit initial value of the destination long.
+ * @param dstPos The position of the LSB, in bits, in the result long.
+ * @param nBytes The number of bytes to convert.
+ * @return A long containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + dstPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}.
*/
- public static long intArrayToLong(final int[] src, final int srcPos, final long dstInit, final int dstPos,
- final int nInts) {
- if (src.length == 0 && srcPos == 0 || 0 == nInts) {
+ public static long byteArrayToLong(final byte[] src, final int srcPos, final long dstInit, final int dstPos, final int nBytes) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
return dstInit;
}
- if ((nInts - 1) * 32 + dstPos >= 64) {
- throw new IllegalArgumentException("(nInts-1)*32+dstPos is greater or equal to than 64");
+ if (((long) nBytes - 1) * Byte.SIZE + dstPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + dstPos >= 64");
}
long out = dstInit;
- for (int i = 0; i < nInts; i++) {
- final int shift = i * 32 + dstPos;
- final long bits = (0xffffffffL & src[i + srcPos]) << shift;
- final long mask = 0xffffffffL << shift;
- out = (out & ~mask) | bits;
+ for (int i = 0; i < nBytes; i++) {
+ final int shift = i * Byte.SIZE + dstPos;
+ final long bits = (0xffL & src[i + srcPos]) << shift;
+ final long mask = 0xffL << shift;
+ out = out & ~mask | bits;
}
return out;
}
/**
- *
- * Converts an array of short into a long using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts an array of byte into a short using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the short array to convert
- * @param srcPos the position in {@code src}, in short unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination long
- * @param dstPos the position of the lsb, in bits, in the result long
- * @param nShorts the number of shorts to convert
- * @return a long containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code (nShorts-1)*16+dstPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nShorts > src.length}
+ * @param src The byte array to convert.
+ * @param srcPos The position in {@code src}, in byte unit, from where to start the conversion.
+ * @param dstInit initial value of the destination short.
+ * @param dstPos The position of the LSB, in bits, in the result short.
+ * @param nBytes The number of bytes to convert.
+ * @return A short containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + dstPos >= 16}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}.
*/
- public static long shortArrayToLong(final short[] src, final int srcPos, final long dstInit, final int dstPos,
- final int nShorts) {
- if (src.length == 0 && srcPos == 0 || 0 == nShorts) {
+ public static short byteArrayToShort(final byte[] src, final int srcPos, final short dstInit, final int dstPos, final int nBytes) {
+ if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
return dstInit;
}
- if ((nShorts - 1) * 16 + dstPos >= 64) {
- throw new IllegalArgumentException("(nShorts-1)*16+dstPos is greater or equal to than 64");
+ if (((long) nBytes - 1) * Byte.SIZE + dstPos >= Short.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + dstPos >= 16");
}
- long out = dstInit;
- for (int i = 0; i < nShorts; i++) {
- final int shift = i * 16 + dstPos;
- final long bits = (0xffffL & src[i + srcPos]) << shift;
- final long mask = 0xffffL << shift;
- out = (out & ~mask) | bits;
+ short out = dstInit;
+ for (int i = 0; i < nBytes; i++) {
+ final int shift = i * Byte.SIZE + dstPos;
+ final int bits = (0xff & src[i + srcPos]) << shift;
+ final int mask = 0xff << shift;
+ out = (short) (out & ~mask | bits);
}
return out;
}
/**
- *
- * Converts an array of short into an int using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts bytes from an array into a UUID using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the short array to convert
- * @param srcPos the position in {@code src}, in short unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination int
- * @param dstPos the position of the lsb, in bits, in the result int
- * @param nShorts the number of shorts to convert
- * @return an int containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code (nShorts-1)*16+dstPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nShorts > src.length}
+ * @param src The byte array to convert.
+ * @param srcPos The position in {@code src} where to copy the result from.
+ * @return A UUID.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if array does not contain at least 16 bytes beginning with {@code srcPos}.
*/
- public static int shortArrayToInt(final short[] src, final int srcPos, final int dstInit, final int dstPos,
- final int nShorts) {
- if (src.length == 0 && srcPos == 0 || 0 == nShorts) {
- return dstInit;
- }
- if ((nShorts - 1) * 16 + dstPos >= 32) {
- throw new IllegalArgumentException("(nShorts-1)*16+dstPos is greater or equal to than 32");
- }
- int out = dstInit;
- for (int i = 0; i < nShorts; i++) {
- final int shift = i * 16 + dstPos;
- final int bits = (0xffff & src[i + srcPos]) << shift;
- final int mask = 0xffff << shift;
- out = (out & ~mask) | bits;
+ public static UUID byteArrayToUuid(final byte[] src, final int srcPos) {
+ if (src.length - srcPos < 16) {
+ throw new IllegalArgumentException("Need at least 16 bytes for UUID");
}
- return out;
+ return new UUID(byteArrayToLong(src, srcPos, 0, 0, Byte.SIZE), byteArrayToLong(src, srcPos + 8, 0, 0, Byte.SIZE));
}
/**
- *
- * Converts an array of byte into a long using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a byte into an array of boolean using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the byte array to convert
- * @param srcPos the position in {@code src}, in byte unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination long
- * @param dstPos the position of the lsb, in bits, in the result long
- * @param nBytes the number of bytes to convert
- * @return a long containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+dstPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}
+ * @param src The byte to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBools The number of booleans to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + srcPos >= 8}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}.
*/
- public static long byteArrayToLong(final byte[] src, final int srcPos, final long dstInit, final int dstPos,
- final int nBytes) {
- if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
- return dstInit;
+ public static boolean[] byteToBinary(final byte src, final int srcPos, final boolean[] dst, final int dstPos, final int nBools) {
+ if (0 == nBools) {
+ return dst;
}
- if ((nBytes - 1) * 8 + dstPos >= 64) {
- throw new IllegalArgumentException("(nBytes-1)*8+dstPos is greater or equal to than 64");
+ if ((long) nBools - 1 + srcPos >= Byte.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + srcPos >= 8");
}
- long out = dstInit;
- for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + dstPos;
- final long bits = (0xffL & src[i + srcPos]) << shift;
- final long mask = 0xffL << shift;
- out = (out & ~mask) | bits;
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + srcPos;
+ dst[dstPos + i] = (0x1 & src >> shift) != 0;
}
- return out;
+ return dst;
}
/**
- *
- * Converts an array of byte into an int using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts a byte into an array of char using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the byte array to convert
- * @param srcPos the position in {@code src}, in byte unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination int
- * @param dstPos the position of the lsb, in bits, in the result int
- * @param nBytes the number of bytes to convert
- * @return an int containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+dstPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}
+ * @param src The byte to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dstInit The initial value for the result String.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nHexs The number of chars to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + srcPos >= 8}.
+ * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}.
*/
- public static int byteArrayToInt(final byte[] src, final int srcPos, final int dstInit, final int dstPos,
- final int nBytes) {
- if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
+ public static String byteToHex(final byte src, final int srcPos, final String dstInit, final int dstPos, final int nHexs) {
+ if (0 == nHexs) {
return dstInit;
}
- if ((nBytes - 1) * 8 + dstPos >= 32) {
- throw new IllegalArgumentException("(nBytes-1)*8+dstPos is greater or equal to than 32");
+ if (((long) nHexs - 1) * 4 + srcPos >= Byte.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + srcPos >= 8");
}
- int out = dstInit;
- for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + dstPos;
- final int bits = (0xff & src[i + srcPos]) << shift;
- final int mask = 0xff << shift;
- out = (out & ~mask) | bits;
+ final StringBuilder sb = new StringBuilder(dstInit);
+ int append = sb.length();
+ for (int i = 0; i < nHexs; i++) {
+ final int shift = i * 4 + srcPos;
+ final int bits = 0xF & src >> shift;
+ if (dstPos + i == append) {
+ ++append;
+ sb.append(intToHexDigit(bits));
+ } else {
+ sb.setCharAt(dstPos + i, intToHexDigit(bits));
+ }
}
- return out;
+ return sb.toString();
}
/**
+ * Converts a hexadecimal digit into binary (represented as boolean array) using the MSB0 bit ordering.
+ *
*
- * Converts an array of byte into a short using the default (little endian, Lsb0) byte and
- * bit ordering.
+ * '1' is converted as follow: (0, 0, 0, 1).
*
*
- * @param src the byte array to convert
- * @param srcPos the position in {@code src}, in byte unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination short
- * @param dstPos the position of the lsb, in bits, in the result short
- * @param nBytes the number of bytes to convert
- * @return a short containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+dstPos >= 16}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBytes > src.length}
+ * @param hexChar The hexadecimal digit to convert.
+ * @return A boolean array with the binary representation of {@code hexDigit}.
+ * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit.
*/
- public static short byteArrayToShort(final byte[] src, final int srcPos, final short dstInit, final int dstPos,
- final int nBytes) {
- if (src.length == 0 && srcPos == 0 || 0 == nBytes) {
- return dstInit;
- }
- if ((nBytes - 1) * 8 + dstPos >= 16) {
- throw new IllegalArgumentException("(nBytes-1)*8+dstPos is greater or equal to than 16");
- }
- short out = dstInit;
- for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + dstPos;
- final int bits = (0xff & src[i + srcPos]) << shift;
- final int mask = 0xff << shift;
- out = (short) ((out & ~mask) | bits);
+ public static boolean[] hexDigitMsb0ToBinary(final char hexChar) {
+ switch (hexChar) {
+ case '0':
+ return FFFF.clone();
+ case '1':
+ return FFFT.clone();
+ case '2':
+ return FFTF.clone();
+ case '3':
+ return FFTT.clone();
+ case '4':
+ return FTFF.clone();
+ case '5':
+ return FTFT.clone();
+ case '6':
+ return FTTF.clone();
+ case '7':
+ return FTTT.clone();
+ case '8':
+ return TFFF.clone();
+ case '9':
+ return TFFT.clone();
+ case 'a':// fall through
+ case 'A':
+ return TFTF.clone();
+ case 'b':// fall through
+ case 'B':
+ return TFTT.clone();
+ case 'c':// fall through
+ case 'C':
+ return TTFF.clone();
+ case 'd':// fall through
+ case 'D':
+ return TTFT.clone();
+ case 'e':// fall through
+ case 'E':
+ return TTTF.clone();
+ case 'f':// fall through
+ case 'F':
+ return TTTT.clone();
+ default:
+ throw new IllegalArgumentException("Cannot convert '" + hexChar + "' to a hexadecimal digit");
}
- return out;
}
/**
+ * Converts a hexadecimal digit into an int using the MSB0 bit ordering.
+ *
*
- * Converts an array of Char into a long using the default (little endian, Lsb0) byte and
- * bit ordering.
+ * '1' is converted to 8.
*
*
- * @param src the hex string to convert
- * @param srcPos the position in {@code src}, in Char unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination long
- * @param dstPos the position of the lsb, in bits, in the result long
- * @param nHex the number of Chars to convert
- * @return a long containing the selected bits
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+dstPos >= 64}
+ * @param hexChar The hexadecimal digit to convert.
+ * @return An int equals to {@code hexDigit}.
+ * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit.
*/
- public static long hexToLong(final String src, final int srcPos, final long dstInit, final int dstPos,
- final int nHex) {
- if (0 == nHex) {
- return dstInit;
- }
- if ((nHex - 1) * 4 + dstPos >= 64) {
- throw new IllegalArgumentException("(nHexs-1)*4+dstPos is greater or equal to than 64");
- }
- long out = dstInit;
- for (int i = 0; i < nHex; i++) {
- final int shift = i * 4 + dstPos;
- final long bits = (0xfL & hexDigitToInt(src.charAt(i + srcPos))) << shift;
- final long mask = 0xfL << shift;
- out = (out & ~mask) | bits;
+ public static int hexDigitMsb0ToInt(final char hexChar) {
+ switch (hexChar) {
+ case '0':
+ return 0x0;
+ case '1':
+ return 0x8;
+ case '2':
+ return 0x4;
+ case '3':
+ return 0xC;
+ case '4':
+ return 0x2;
+ case '5':
+ return 0xA;
+ case '6':
+ return 0x6;
+ case '7':
+ return 0xE;
+ case '8':
+ return 0x1;
+ case '9':
+ return 0x9;
+ case 'a':// fall through
+ case 'A':
+ return 0x5;
+ case 'b':// fall through
+ case 'B':
+ return 0xD;
+ case 'c':// fall through
+ case 'C':
+ return 0x3;
+ case 'd':// fall through
+ case 'D':
+ return 0xB;
+ case 'e':// fall through
+ case 'E':
+ return 0x7;
+ case 'f':// fall through
+ case 'F':
+ return 0xF;
+ default:
+ throw new IllegalArgumentException("Cannot convert '" + hexChar + "' to a hexadecimal digit");
}
- return out;
}
/**
+ * Converts a hexadecimal digit into binary (represented as boolean array) using the default (LSB0) bit ordering.
+ *
*
- * Converts an array of Char into an int using the default (little endian, Lsb0) byte and bit
- * ordering.
+ * '1' is converted as follow: (1, 0, 0, 0).
*
*
- * @param src the hex string to convert
- * @param srcPos the position in {@code src}, in Char unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination int
- * @param dstPos the position of the lsb, in bits, in the result int
- * @param nHex the number of Chars to convert
- * @return an int containing the selected bits
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+dstPos >= 32}
+ * @param hexChar The hexadecimal digit to convert.
+ * @return A boolean array with the binary representation of {@code hexDigit}.
+ * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit.
*/
- public static int hexToInt(final String src, final int srcPos, final int dstInit, final int dstPos, final int nHex) {
- if (0 == nHex) {
- return dstInit;
- }
- if ((nHex - 1) * 4 + dstPos >= 32) {
- throw new IllegalArgumentException("(nHexs-1)*4+dstPos is greater or equal to than 32");
- }
- int out = dstInit;
- for (int i = 0; i < nHex; i++) {
- final int shift = i * 4 + dstPos;
- final int bits = (0xf & hexDigitToInt(src.charAt(i + srcPos))) << shift;
- final int mask = 0xf << shift;
- out = (out & ~mask) | bits;
+ public static boolean[] hexDigitToBinary(final char hexChar) {
+ switch (hexChar) {
+ case '0':
+ return FFFF.clone();
+ case '1':
+ return TFFF.clone();
+ case '2':
+ return FTFF.clone();
+ case '3':
+ return TTFF.clone();
+ case '4':
+ return FFTF.clone();
+ case '5':
+ return TFTF.clone();
+ case '6':
+ return FTTF.clone();
+ case '7':
+ return TTTF.clone();
+ case '8':
+ return FFFT.clone();
+ case '9':
+ return TFFT.clone();
+ case 'a':// fall through
+ case 'A':
+ return FTFT.clone();
+ case 'b':// fall through
+ case 'B':
+ return TTFT.clone();
+ case 'c':// fall through
+ case 'C':
+ return FFTT.clone();
+ case 'd':// fall through
+ case 'D':
+ return TFTT.clone();
+ case 'e':// fall through
+ case 'E':
+ return FTTT.clone();
+ case 'f':// fall through
+ case 'F':
+ return TTTT.clone();
+ default:
+ throw new IllegalArgumentException("Cannot convert '" + hexChar + "' to a hexadecimal digit");
}
- return out;
}
/**
+ * Converts a hexadecimal digit into an int using the default (LSB0) bit ordering.
+ *
*
- * Converts an array of Char into a short using the default (little endian, Lsb0) byte and
- * bit ordering.
+ * '1' is converted to 1.
*
*
- * @param src the hex string to convert
- * @param srcPos the position in {@code src}, in Char unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination short
- * @param dstPos the position of the lsb, in bits, in the result short
- * @param nHex the number of Chars to convert
- * @return a short containing the selected bits
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+dstPos >= 16}
+ * @param hexChar The hexadecimal digit to convert.
+ * @return An int equals to {@code hexDigit}.
+ * @throws IllegalArgumentException if {@code hexDigit} is not a hexadecimal digit.
+ */
+ public static int hexDigitToInt(final char hexChar) {
+ if (!CharUtils.isHex(hexChar)) {
+ throw new IllegalArgumentException("Cannot convert '" + hexChar + "' to a hexadecimal digit");
+ }
+ return Character.digit(hexChar, 16);
+ }
+
+ /**
+ * Converts a hexadecimal string into a byte using the default (little-endian, LSB0) byte and bit ordering.
+ *
+ * @param src The hexadecimal string to convert.
+ * @param srcPos The position in {@code src}, in char unit, from where to start the conversion.
+ * @param dstInit initial value of the destination byte.
+ * @param dstPos The position of the LSB, in bits, in the result byte.
+ * @param nHex The number of Chars to convert.
+ * @return A byte containing the selected bits.
+ * @throws IllegalArgumentException if {@code (nHex-1)*4+dstPos >= 8}.
*/
- public static short hexToShort(final String src, final int srcPos, final short dstInit, final int dstPos,
- final int nHex) {
+ public static byte hexToByte(final String src, final int srcPos, final byte dstInit, final int dstPos, final int nHex) {
if (0 == nHex) {
return dstInit;
}
- if ((nHex - 1) * 4 + dstPos >= 16) {
- throw new IllegalArgumentException("(nHexs-1)*4+dstPos is greater or equal to than 16");
+ if (((long) nHex - 1) * 4 + dstPos >= Byte.SIZE) {
+ throw new IllegalArgumentException("(nHex - 1) * 4 + dstPos >= 8");
}
- short out = dstInit;
+ byte out = dstInit;
for (int i = 0; i < nHex; i++) {
final int shift = i * 4 + dstPos;
final int bits = (0xf & hexDigitToInt(src.charAt(i + srcPos))) << shift;
final int mask = 0xf << shift;
- out = (short) ((out & ~mask) | bits);
+ out = (byte) (out & ~mask | bits);
}
return out;
}
/**
- *
- * Converts an array of Char into a byte using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts an array of char into an int using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the hex string to convert
- * @param srcPos the position in {@code src}, in Char unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination byte
- * @param dstPos the position of the lsb, in bits, in the result byte
- * @param nHex the number of Chars to convert
- * @return a byte containing the selected bits
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+dstPos >= 8}
+ * @param src The hexadecimal string to convert.
+ * @param srcPos The position in {@code src}, in char unit, from where to start the conversion.
+ * @param dstInit initial value of the destination int.
+ * @param dstPos The position of the LSB, in bits, in the result int.
+ * @param nHex The number of chars to convert.
+ * @return An int containing the selected bits.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + dstPos >= 32}.
*/
- public static byte hexToByte(final String src, final int srcPos, final byte dstInit, final int dstPos,
- final int nHex) {
+ public static int hexToInt(final String src, final int srcPos, final int dstInit, final int dstPos, final int nHex) {
if (0 == nHex) {
return dstInit;
}
- if ((nHex - 1) * 4 + dstPos >= 8) {
- throw new IllegalArgumentException("(nHexs-1)*4+dstPos is greater or equal to than 8");
+ if (((long) nHex - 1) * 4 + dstPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + dstPos >= 32");
}
- byte out = dstInit;
+ int out = dstInit;
for (int i = 0; i < nHex; i++) {
final int shift = i * 4 + dstPos;
final int bits = (0xf & hexDigitToInt(src.charAt(i + srcPos))) << shift;
final int mask = 0xf << shift;
- out = (byte) ((out & ~mask) | bits);
+ out = out & ~mask | bits;
}
return out;
}
/**
- *
- * Converts binary (represented as boolean array) into a long using the default (little
- * endian, Lsb0) byte and bit ordering.
- *
+ * Converts an array of char into a long using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @param srcPos the position in {@code src}, in boolean unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination long
- * @param dstPos the position of the lsb, in bits, in the result long
- * @param nBools the number of booleans to convert
- * @return a long containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+dstPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}
+ * @param src The hexadecimal string to convert.
+ * @param srcPos The position in {@code src}, in char unit, from where to start the conversion.
+ * @param dstInit initial value of the destination long.
+ * @param dstPos The position of the LSB, in bits, in the result long.
+ * @param nHex The number of chars to convert.
+ * @return A long containing the selected bits.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + dstPos >= 64}.
*/
- public static long binaryToLong(final boolean[] src, final int srcPos, final long dstInit, final int dstPos,
- final int nBools) {
- if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ public static long hexToLong(final String src, final int srcPos, final long dstInit, final int dstPos, final int nHex) {
+ if (0 == nHex) {
return dstInit;
}
- if (nBools - 1 + dstPos >= 64) {
- throw new IllegalArgumentException("nBools-1+dstPos is greater or equal to than 64");
+ if (((long) nHex - 1) * 4 + dstPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + dstPos >= 64");
}
long out = dstInit;
- for (int i = 0; i < nBools; i++) {
- final int shift = i + dstPos;
- final long bits = (src[i + srcPos] ? 1L : 0) << shift;
- final long mask = 0x1L << shift;
- out = (out & ~mask) | bits;
+ for (int i = 0; i < nHex; i++) {
+ final int shift = i * 4 + dstPos;
+ final long bits = (0xfL & hexDigitToInt(src.charAt(i + srcPos))) << shift;
+ final long mask = 0xfL << shift;
+ out = out & ~mask | bits;
}
return out;
}
/**
- *
- * Converts binary (represented as boolean array) into an int using the default (little
- * endian, Lsb0) byte and bit ordering.
- *
+ * Converts an array of char into a short using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @param srcPos the position in {@code src}, in boolean unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination int
- * @param dstPos the position of the lsb, in bits, in the result int
- * @param nBools the number of booleans to convert
- * @return an int containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+dstPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}
+ * @param src The hexadecimal string to convert.
+ * @param srcPos The position in {@code src}, in char unit, from where to start the conversion.
+ * @param dstInit initial value of the destination short.
+ * @param dstPos The position of the LSB, in bits, in the result short.
+ * @param nHex The number of chars to convert.
+ * @return A short containing the selected bits.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + dstPos >= 16}.
*/
- public static int binaryToInt(final boolean[] src, final int srcPos, final int dstInit, final int dstPos,
- final int nBools) {
- if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ public static short hexToShort(final String src, final int srcPos, final short dstInit, final int dstPos, final int nHex) {
+ if (0 == nHex) {
return dstInit;
}
- if (nBools - 1 + dstPos >= 32) {
- throw new IllegalArgumentException("nBools-1+dstPos is greater or equal to than 32");
+ if (((long) nHex - 1) * 4 + dstPos >= Short.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + dstPos >= 16");
}
- int out = dstInit;
- for (int i = 0; i < nBools; i++) {
- final int shift = i + dstPos;
- final int bits = (src[i + srcPos] ? 1 : 0) << shift;
- final int mask = 0x1 << shift;
- out = (out & ~mask) | bits;
+ short out = dstInit;
+ for (int i = 0; i < nHex; i++) {
+ final int shift = i * 4 + dstPos;
+ final int bits = (0xf & hexDigitToInt(src.charAt(i + srcPos))) << shift;
+ final int mask = 0xf << shift;
+ out = (short) (out & ~mask | bits);
}
return out;
}
/**
- *
- * Converts binary (represented as boolean array) into a short using the default (little
- * endian, Lsb0) byte and bit ordering.
- *
+ * Converts an array of int into a long using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @param srcPos the position in {@code src}, in boolean unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination short
- * @param dstPos the position of the lsb, in bits, in the result short
- * @param nBools the number of booleans to convert
- * @return a short containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+dstPos >= 16}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}
+ * @param src The int array to convert.
+ * @param srcPos The position in {@code src}, in int unit, from where to start the conversion.
+ * @param dstInit initial value of the destination long.
+ * @param dstPos The position of the LSB, in bits, in the result long.
+ * @param nInts The number of ints to convert.
+ * @return A long containing the selected bits.
+ * @throws IllegalArgumentException if {@code (nInts - 1) * 32 + dstPos >= 64}.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nInts > src.length}.
*/
- public static short binaryToShort(final boolean[] src, final int srcPos, final short dstInit, final int dstPos,
- final int nBools) {
- if (src.length == 0 && srcPos == 0 || 0 == nBools) {
+ public static long intArrayToLong(final int[] src, final int srcPos, final long dstInit, final int dstPos, final int nInts) {
+ if (src.length == 0 && srcPos == 0 || 0 == nInts) {
return dstInit;
}
- if (nBools - 1 + dstPos >= 16) {
- throw new IllegalArgumentException("nBools-1+dstPos is greater or equal to than 16");
+ if (((long) nInts - 1) * Integer.SIZE + dstPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nInts - 1) * 32 + dstPos >= 64");
}
- short out = dstInit;
- for (int i = 0; i < nBools; i++) {
- final int shift = i + dstPos;
- final int bits = (src[i + srcPos] ? 1 : 0) << shift;
- final int mask = 0x1 << shift;
- out = (short) ((out & ~mask) | bits);
+ long out = dstInit;
+ for (int i = 0; i < nInts; i++) {
+ final int shift = i * Integer.SIZE + dstPos;
+ final long bits = (0xffffffffL & src[i + srcPos]) << shift;
+ final long mask = 0xffffffffL << shift;
+ out = out & ~mask | bits;
}
return out;
}
/**
- *
- * Converts binary (represented as boolean array) into a byte using the default (little
- * endian, Lsb0) byte and bit ordering.
- *
+ * Converts an int into an array of boolean using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the binary to convert
- * @param srcPos the position in {@code src}, in boolean unit, from where to start the
- * conversion
- * @param dstInit initial value of the destination byte
- * @param dstPos the position of the lsb, in bits, in the result byte
- * @param nBools the number of booleans to convert
- * @return a byte containing the selected bits
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+dstPos >= 8}
- * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nBools > src.length}
+ * @param src The int to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBools The number of booleans to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + srcPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}.
*/
- public static byte binaryToByte(final boolean[] src, final int srcPos, final byte dstInit, final int dstPos,
- final int nBools) {
- if (src.length == 0 && srcPos == 0 || 0 == nBools) {
- return dstInit;
+ public static boolean[] intToBinary(final int src, final int srcPos, final boolean[] dst, final int dstPos, final int nBools) {
+ if (0 == nBools) {
+ return dst;
}
- if (nBools - 1 + dstPos >= 8) {
- throw new IllegalArgumentException("nBools-1+dstPos is greater or equal to than 8");
+ if ((long) nBools - 1 + srcPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + srcPos >= 32");
}
- byte out = dstInit;
for (int i = 0; i < nBools; i++) {
- final int shift = i + dstPos;
- final int bits = (src[i + srcPos] ? 1 : 0) << shift;
- final int mask = 0x1 << shift;
- out = (byte) ((out & ~mask) | bits);
+ final int shift = i + srcPos;
+ dst[dstPos + i] = (0x1 & src >> shift) != 0;
}
- return out;
+ return dst;
}
/**
- *
- * Converts a long into an array of int using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts an int into an array of byte using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the long to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nInts the number of ints to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null} and {@code nInts > 0}
- * @throws IllegalArgumentException if {@code (nInts-1)*32+srcPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nInts > dst.length}
+ * @param src The int to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBytes The number of bytes to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + srcPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}.
*/
- public static int[] longToIntArray(final long src, final int srcPos, final int[] dst, final int dstPos,
- final int nInts) {
- if (0 == nInts) {
+ public static byte[] intToByteArray(final int src, final int srcPos, final byte[] dst, final int dstPos, final int nBytes) {
+ if (0 == nBytes) {
return dst;
}
- if ((nInts - 1) * 32 + srcPos >= 64) {
- throw new IllegalArgumentException("(nInts-1)*32+srcPos is greater or equal to than 64");
+ if (((long) nBytes - 1) * Byte.SIZE + srcPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + srcPos >= 32");
}
- for (int i = 0; i < nInts; i++) {
- final int shift = i * 32 + srcPos;
- dst[dstPos + i] = (int) (0xffffffff & (src >> shift));
+ for (int i = 0; i < nBytes; i++) {
+ final int shift = i * Byte.SIZE + srcPos;
+ dst[dstPos + i] = (byte) (0xff & src >> shift);
}
return dst;
}
/**
- *
- * Converts a long into an array of short using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts an int into an array of char using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the long to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nShorts the number of shorts to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code (nShorts-1)*16+srcPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nShorts > dst.length}
+ * @param src The int to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dstInit The initial value for the result String.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nHexs The number of chars to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + srcPos >= 32}.
+ * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}.
*/
- public static short[] longToShortArray(final long src, final int srcPos, final short[] dst, final int dstPos,
- final int nShorts) {
- if (0 == nShorts) {
- return dst;
+ public static String intToHex(final int src, final int srcPos, final String dstInit, final int dstPos, final int nHexs) {
+ if (0 == nHexs) {
+ return dstInit;
}
- if ((nShorts - 1) * 16 + srcPos >= 64) {
- throw new IllegalArgumentException("(nShorts-1)*16+srcPos is greater or equal to than 64");
+ if (((long) nHexs - 1) * 4 + srcPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + srcPos >= 32");
}
- for (int i = 0; i < nShorts; i++) {
- final int shift = i * 16 + srcPos;
- dst[dstPos + i] = (short) (0xffff & (src >> shift));
+ final StringBuilder sb = new StringBuilder(dstInit);
+ int append = sb.length();
+ for (int i = 0; i < nHexs; i++) {
+ final int shift = i * 4 + srcPos;
+ final int bits = 0xF & src >> shift;
+ if (dstPos + i == append) {
+ ++append;
+ sb.append(intToHexDigit(bits));
+ } else {
+ sb.setCharAt(dstPos + i, intToHexDigit(bits));
+ }
}
- return dst;
+ return sb.toString();
}
/**
+ * Converts the 4 LSB of an int to a hexadecimal digit.
+ *
*
- * Converts an int into an array of short using the default (little endian, Lsb0) byte and
- * bit ordering.
+ * 0 returns '0'
+ *
+ *
+ * 1 returns '1'
+ *
+ *
+ * 10 returns 'A' and so on...
*
*
- * @param src the int to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nShorts the number of shorts to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code (nShorts-1)*16+srcPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nShorts > dst.length}
+ * @param nibble The 4 bits to convert.
+ * @return A hexadecimal digit representing the 4 LSB of {@code nibble}.
+ * @throws IllegalArgumentException if {@code nibble < 0} or {@code nibble > 15}.
*/
- public static short[] intToShortArray(final int src, final int srcPos, final short[] dst, final int dstPos,
- final int nShorts) {
- if (0 == nShorts) {
- return dst;
- }
- if ((nShorts - 1) * 16 + srcPos >= 32) {
- throw new IllegalArgumentException("(nShorts-1)*16+srcPos is greater or equal to than 32");
- }
- for (int i = 0; i < nShorts; i++) {
- final int shift = i * 16 + srcPos;
- dst[dstPos + i] = (short) (0xffff & (src >> shift));
+ public static char intToHexDigit(final int nibble) {
+ final char c = Character.forDigit(nibble, 16);
+ if (c == Character.MIN_VALUE) {
+ throw new IllegalArgumentException("nibble value not between 0 and 15: " + nibble);
}
- return dst;
+ return c;
}
/**
+ * Converts the 4 LSB of an int to a hexadecimal digit encoded using the MSB0 bit ordering.
+ *
+ *
+ * 0 returns '0'
+ *
+ *
+ * 1 returns '8'
+ *
*
- * Converts a long into an array of byte using the default (little endian, Lsb0) byte and
- * bit ordering.
+ * 10 returns '5' and so on...
*
*
- * @param src the long to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBytes the number of bytes to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+srcPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}
+ * @param nibble The 4 bits to convert.
+ * @return A hexadecimal digit representing the 4 LSB of {@code nibble}.
+ * @throws IllegalArgumentException if {@code nibble < 0} or {@code nibble > 15}.
*/
- public static byte[] longToByteArray(final long src, final int srcPos, final byte[] dst, final int dstPos,
- final int nBytes) {
- if (0 == nBytes) {
+ public static char intToHexDigitMsb0(final int nibble) {
+ switch (nibble) {
+ case 0x0:
+ return '0';
+ case 0x1:
+ return '8';
+ case 0x2:
+ return '4';
+ case 0x3:
+ return 'c';
+ case 0x4:
+ return '2';
+ case 0x5:
+ return 'a';
+ case 0x6:
+ return '6';
+ case 0x7:
+ return 'e';
+ case 0x8:
+ return '1';
+ case 0x9:
+ return '9';
+ case 0xA:
+ return '5';
+ case 0xB:
+ return 'd';
+ case 0xC:
+ return '3';
+ case 0xD:
+ return 'b';
+ case 0xE:
+ return '7';
+ case 0xF:
+ return 'f';
+ default:
+ throw new IllegalArgumentException("nibble value not between 0 and 15: " + nibble);
+ }
+ }
+
+ /**
+ * Converts an int into an array of short using the default (little-endian, LSB0) byte and bit ordering.
+ *
+ * @param src The int to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nShorts The number of shorts to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nShorts - 1) * 16 + srcPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nShorts > dst.length}.
+ */
+ public static short[] intToShortArray(final int src, final int srcPos, final short[] dst, final int dstPos, final int nShorts) {
+ if (0 == nShorts) {
return dst;
}
- if ((nBytes - 1) * 8 + srcPos >= 64) {
- throw new IllegalArgumentException("(nBytes-1)*8+srcPos is greater or equal to than 64");
+ if (((long) nShorts - 1) * Short.SIZE + srcPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nShorts - 1) * 16 + srcPos >= 32");
}
- for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + srcPos;
- dst[dstPos + i] = (byte) (0xff & (src >> shift));
+ for (int i = 0; i < nShorts; i++) {
+ final int shift = i * Short.SIZE + srcPos;
+ dst[dstPos + i] = (short) (0xffff & src >> shift);
}
return dst;
}
/**
- *
- * Converts an int into an array of byte using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts a long into an array of boolean using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the int to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBytes the number of bytes to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+srcPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}
+ * @param src The long to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBools The number of booleans to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + srcPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}.
*/
- public static byte[] intToByteArray(final int src, final int srcPos, final byte[] dst, final int dstPos,
- final int nBytes) {
- if (0 == nBytes) {
+ public static boolean[] longToBinary(final long src, final int srcPos, final boolean[] dst, final int dstPos, final int nBools) {
+ if (0 == nBools) {
return dst;
}
- if ((nBytes - 1) * 8 + srcPos >= 32) {
- throw new IllegalArgumentException("(nBytes-1)*8+srcPos is greater or equal to than 32");
+ if ((long) nBools - 1 + srcPos >= Long.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + srcPos >= 64");
}
- for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + srcPos;
- dst[dstPos + i] = (byte) (0xff & (src >> shift));
+ for (int i = 0; i < nBools; i++) {
+ final int shift = i + srcPos;
+ dst[dstPos + i] = (0x1 & src >> shift) != 0;
}
return dst;
}
/**
- *
- * Converts a short into an array of byte using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a long into an array of byte using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the short to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBytes the number of bytes to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code (nBytes-1)*8+srcPos >= 16}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}
+ * @param src The long to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBytes The number of bytes to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + srcPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}.
*/
- public static byte[] shortToByteArray(final short src, final int srcPos, final byte[] dst, final int dstPos,
- final int nBytes) {
+ public static byte[] longToByteArray(final long src, final int srcPos, final byte[] dst, final int dstPos, final int nBytes) {
if (0 == nBytes) {
return dst;
}
- if ((nBytes - 1) * 8 + srcPos >= 16) {
- throw new IllegalArgumentException("(nBytes-1)*8+srcPos is greater or equal to than 16");
+ if (((long) nBytes - 1) * Byte.SIZE + srcPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + srcPos >= 64");
}
for (int i = 0; i < nBytes; i++) {
- final int shift = i * 8 + srcPos;
- dst[dstPos + i] = (byte) (0xff & (src >> shift));
+ final int shift = i * Byte.SIZE + srcPos;
+ dst[dstPos + i] = (byte) (0xff & src >> shift);
}
return dst;
}
/**
- *
- * Converts a long into an array of Char using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a long into an array of char using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the long to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dstInit the initial value for the result String
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nHexs the number of Chars to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+srcPos >= 64}
- * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}
+ * @param src The long to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dstInit The initial value for the result String.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nHexs The number of chars to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + srcPos >= 64}.
+ * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}.
*/
- public static String longToHex(final long src, final int srcPos, final String dstInit, final int dstPos,
- final int nHexs) {
+ public static String longToHex(final long src, final int srcPos, final String dstInit, final int dstPos, final int nHexs) {
if (0 == nHexs) {
return dstInit;
}
- if ((nHexs - 1) * 4 + srcPos >= 64) {
- throw new IllegalArgumentException("(nHexs-1)*4+srcPos is greater or equal to than 64");
+ if (((long) nHexs - 1) * 4 + srcPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + srcPos >= 64");
}
final StringBuilder sb = new StringBuilder(dstInit);
int append = sb.length();
for (int i = 0; i < nHexs; i++) {
final int shift = i * 4 + srcPos;
- final int bits = (int) (0xF & (src >> shift));
+ final int bits = (int) (0xF & src >> shift);
if (dstPos + i == append) {
++append;
sb.append(intToHexDigit(bits));
@@ -1266,275 +1160,228 @@ public static String longToHex(final long src, final int srcPos, final String ds
}
/**
- *
- * Converts an int into an array of Char using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts a long into an array of int using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the int to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dstInit the initial value for the result String
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nHexs the number of Chars to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+srcPos >= 32}
- * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}
+ * @param src The long to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nInts The number of ints to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null} and {@code nInts > 0}.
+ * @throws IllegalArgumentException if {@code (nInts - 1) * 32 + srcPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nInts > dst.length}.
*/
- public static String intToHex(final int src, final int srcPos, final String dstInit, final int dstPos,
- final int nHexs) {
- if (0 == nHexs) {
- return dstInit;
+ public static int[] longToIntArray(final long src, final int srcPos, final int[] dst, final int dstPos, final int nInts) {
+ if (0 == nInts) {
+ return dst;
}
- if ((nHexs - 1) * 4 + srcPos >= 32) {
- throw new IllegalArgumentException("(nHexs-1)*4+srcPos is greater or equal to than 32");
+ if (((long) nInts - 1) * Integer.SIZE + srcPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nInts - 1) * 32 + srcPos >= 64");
}
- final StringBuilder sb = new StringBuilder(dstInit);
- int append = sb.length();
- for (int i = 0; i < nHexs; i++) {
- final int shift = i * 4 + srcPos;
- final int bits = 0xF & (src >> shift);
- if (dstPos + i == append) {
- ++append;
- sb.append(intToHexDigit(bits));
- } else {
- sb.setCharAt(dstPos + i, intToHexDigit(bits));
- }
+ for (int i = 0; i < nInts; i++) {
+ final int shift = i * Integer.SIZE + srcPos;
+ dst[dstPos + i] = (int) (0xffffffff & src >> shift);
}
- return sb.toString();
+ return dst;
}
/**
- *
- * Converts a short into an array of Char using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a long into an array of short using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the short to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dstInit the initial value for the result String
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nHexs the number of Chars to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+srcPos >= 16}
- * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}
+ * @param src The long to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nShorts The number of shorts to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nShorts - 1) * 16 + srcPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nShorts > dst.length}.
*/
- public static String shortToHex(final short src, final int srcPos, final String dstInit, final int dstPos,
- final int nHexs) {
- if (0 == nHexs) {
- return dstInit;
+ public static short[] longToShortArray(final long src, final int srcPos, final short[] dst, final int dstPos, final int nShorts) {
+ if (0 == nShorts) {
+ return dst;
}
- if ((nHexs - 1) * 4 + srcPos >= 16) {
- throw new IllegalArgumentException("(nHexs-1)*4+srcPos is greater or equal to than 16");
+ if (((long) nShorts - 1) * Short.SIZE + srcPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nShorts - 1) * 16 + srcPos >= 64");
}
- final StringBuilder sb = new StringBuilder(dstInit);
- int append = sb.length();
- for (int i = 0; i < nHexs; i++) {
- final int shift = i * 4 + srcPos;
- final int bits = 0xF & (src >> shift);
- if (dstPos + i == append) {
- ++append;
- sb.append(intToHexDigit(bits));
- } else {
- sb.setCharAt(dstPos + i, intToHexDigit(bits));
- }
+ for (int i = 0; i < nShorts; i++) {
+ final int shift = i * Short.SIZE + srcPos;
+ dst[dstPos + i] = (short) (0xffff & src >> shift);
}
- return sb.toString();
+ return dst;
}
/**
- *
- * Converts a byte into an array of Char using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts an array of short into an int using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the byte to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dstInit the initial value for the result String
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nHexs the number of Chars to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws IllegalArgumentException if {@code (nHexs-1)*4+srcPos >= 8}
- * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}
+ * @param src The short array to convert.
+ * @param srcPos The position in {@code src}, in short unit, from where to start the conversion.
+ * @param dstInit initial value of the destination int.
+ * @param dstPos The position of the LSB, in bits, in the result int.
+ * @param nShorts The number of shorts to convert.
+ * @return An int containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nShorts - 1) * 16 + dstPos >= 32}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nShorts > src.length}.
*/
- public static String byteToHex(final byte src, final int srcPos, final String dstInit, final int dstPos,
- final int nHexs) {
- if (0 == nHexs) {
+ public static int shortArrayToInt(final short[] src, final int srcPos, final int dstInit, final int dstPos, final int nShorts) {
+ if (src.length == 0 && srcPos == 0 || 0 == nShorts) {
return dstInit;
}
- if ((nHexs - 1) * 4 + srcPos >= 8) {
- throw new IllegalArgumentException("(nHexs-1)*4+srcPos is greater or equal to than 8");
+ if (((long) nShorts - 1) * Short.SIZE + dstPos >= Integer.SIZE) {
+ throw new IllegalArgumentException("(nShorts - 1) * 16 + dstPos >= 32");
}
- final StringBuilder sb = new StringBuilder(dstInit);
- int append = sb.length();
- for (int i = 0; i < nHexs; i++) {
- final int shift = i * 4 + srcPos;
- final int bits = 0xF & (src >> shift);
- if (dstPos + i == append) {
- ++append;
- sb.append(intToHexDigit(bits));
- } else {
- sb.setCharAt(dstPos + i, intToHexDigit(bits));
- }
+ int out = dstInit;
+ for (int i = 0; i < nShorts; i++) {
+ final int shift = i * Short.SIZE + dstPos;
+ final int bits = (0xffff & src[i + srcPos]) << shift;
+ final int mask = 0xffff << shift;
+ out = out & ~mask | bits;
}
- return sb.toString();
+ return out;
}
/**
- *
- * Converts a long into an array of boolean using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts an array of short into a long using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the long to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBools the number of booleans to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+srcPos >= 64}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}
+ * @param src The short array to convert.
+ * @param srcPos The position in {@code src}, in short unit, from where to start the conversion.
+ * @param dstInit initial value of the destination long.
+ * @param dstPos The position of the LSB, in bits, in the result long.
+ * @param nShorts The number of shorts to convert.
+ * @return A long containing the selected bits.
+ * @throws NullPointerException if {@code src} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nShorts - 1) * 16 + dstPos >= 64}.
+ * @throws ArrayIndexOutOfBoundsException if {@code srcPos + nShorts > src.length}.
*/
- public static boolean[] longToBinary(final long src, final int srcPos, final boolean[] dst, final int dstPos,
- final int nBools) {
- if (0 == nBools) {
- return dst;
+ public static long shortArrayToLong(final short[] src, final int srcPos, final long dstInit, final int dstPos, final int nShorts) {
+ if (src.length == 0 && srcPos == 0 || 0 == nShorts) {
+ return dstInit;
}
- if (nBools - 1 + srcPos >= 64) {
- throw new IllegalArgumentException("nBools-1+srcPos is greater or equal to than 64");
+ if (((long) nShorts - 1) * Short.SIZE + dstPos >= Long.SIZE) {
+ throw new IllegalArgumentException("(nShorts - 1) * 16 + dstPos >= 64");
}
- for (int i = 0; i < nBools; i++) {
- final int shift = i + srcPos;
- dst[dstPos + i] = (0x1 & (src >> shift)) != 0;
+ long out = dstInit;
+ for (int i = 0; i < nShorts; i++) {
+ final int shift = i * Short.SIZE + dstPos;
+ final long bits = (0xffffL & src[i + srcPos]) << shift;
+ final long mask = 0xffffL << shift;
+ out = out & ~mask | bits;
}
- return dst;
+ return out;
}
/**
- *
- * Converts an int into an array of boolean using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a short into an array of boolean using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the int to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBools the number of booleans to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+srcPos >= 32}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}
+ * @param src The short to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBools The number of booleans to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBools - 1 + srcPos >= 16}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}.
*/
- public static boolean[] intToBinary(final int src, final int srcPos, final boolean[] dst, final int dstPos,
- final int nBools) {
+ public static boolean[] shortToBinary(final short src, final int srcPos, final boolean[] dst, final int dstPos, final int nBools) {
if (0 == nBools) {
return dst;
}
- if (nBools - 1 + srcPos >= 32) {
- throw new IllegalArgumentException("nBools-1+srcPos is greater or equal to than 32");
+ if ((long) nBools - 1 + srcPos >= Short.SIZE) {
+ throw new IllegalArgumentException("nBools - 1 + srcPos >= 16");
}
+ assert nBools - 1 < Short.SIZE - srcPos;
for (int i = 0; i < nBools; i++) {
final int shift = i + srcPos;
- dst[dstPos + i] = (0x1 & (src >> shift)) != 0;
+ dst[dstPos + i] = (0x1 & src >> shift) != 0;
}
return dst;
}
/**
- *
- * Converts a short into an array of boolean using the default (little endian, Lsb0) byte
- * and bit ordering.
- *
+ * Converts a short into an array of byte using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the short to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBools the number of booleans to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+srcPos >= 16}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}
+ * @param src The short to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBytes The number of bytes to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code (nBytes - 1) * 8 + srcPos >= 16}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}.
*/
- public static boolean[] shortToBinary(final short src, final int srcPos, final boolean[] dst, final int dstPos,
- final int nBools) {
- if (0 == nBools) {
+ public static byte[] shortToByteArray(final short src, final int srcPos, final byte[] dst, final int dstPos, final int nBytes) {
+ if (0 == nBytes) {
return dst;
}
- if (nBools - 1 + srcPos >= 16) {
- throw new IllegalArgumentException("nBools-1+srcPos is greater or equal to than 16");
+ if (((long) nBytes - 1) * Byte.SIZE + srcPos >= Short.SIZE) {
+ throw new IllegalArgumentException("(nBytes - 1) * 8 + srcPos >= 16");
}
- assert (nBools - 1) < 16 - srcPos;
- for (int i = 0; i < nBools; i++) {
- final int shift = i + srcPos;
- dst[dstPos + i] = (0x1 & (src >> shift)) != 0;
+ for (int i = 0; i < nBytes; i++) {
+ final int shift = i * Byte.SIZE + srcPos;
+ dst[dstPos + i] = (byte) (0xff & src >> shift);
}
return dst;
}
/**
- *
- * Converts a byte into an array of boolean using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Converts a short into an array of char using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the byte to convert
- * @param srcPos the position in {@code src}, in bits, from where to start the conversion
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBools the number of booleans to copy to {@code dst}, must be smaller or equal to
- * the width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code nBools-1+srcPos >= 8}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBools > dst.length}
+ * @param src The short to convert.
+ * @param srcPos The position in {@code src}, in bits, from where to start the conversion.
+ * @param dstInit The initial value for the result String.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nHexs The number of chars to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws IllegalArgumentException if {@code (nHexs - 1) * 4 + srcPos >= 16}.
+ * @throws StringIndexOutOfBoundsException if {@code dst.init.length() < dstPos}.
*/
- public static boolean[] byteToBinary(final byte src, final int srcPos, final boolean[] dst, final int dstPos,
- final int nBools) {
- if (0 == nBools) {
- return dst;
+ public static String shortToHex(final short src, final int srcPos, final String dstInit, final int dstPos, final int nHexs) {
+ if (0 == nHexs) {
+ return dstInit;
}
- if (nBools - 1 + srcPos >= 8) {
- throw new IllegalArgumentException("nBools-1+srcPos is greater or equal to than 8");
+ if (((long) nHexs - 1) * 4 + srcPos >= Short.SIZE) {
+ throw new IllegalArgumentException("(nHexs - 1) * 4 + srcPos >= 16");
}
- for (int i = 0; i < nBools; i++) {
- final int shift = i + srcPos;
- dst[dstPos + i] = (0x1 & (src >> shift)) != 0;
+ final StringBuilder sb = new StringBuilder(dstInit);
+ int append = sb.length();
+ for (int i = 0; i < nHexs; i++) {
+ final int shift = i * 4 + srcPos;
+ final int bits = 0xF & src >> shift;
+ if (dstPos + i == append) {
+ ++append;
+ sb.append(intToHexDigit(bits));
+ } else {
+ sb.setCharAt(dstPos + i, intToHexDigit(bits));
+ }
}
- return dst;
+ return sb.toString();
}
/**
- *
- * Converts UUID into an array of byte using the default (little endian, Lsb0) byte and bit
- * ordering.
- *
+ * Converts UUID into an array of byte using the default (little-endian, LSB0) byte and bit ordering.
*
- * @param src the UUID to convert
- * @param dst the destination array
- * @param dstPos the position in {@code dst} where to copy the result
- * @param nBytes the number of bytes to copy to {@code dst}, must be smaller or equal to the
- * width of the input (from srcPos to msb)
- * @return {@code dst}
- * @throws NullPointerException if {@code dst} is {@code null}
- * @throws IllegalArgumentException if {@code nBytes > 16}
- * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}
+ * @param src The UUID to convert.
+ * @param dst The destination array.
+ * @param dstPos The position in {@code dst} where to copy the result.
+ * @param nBytes The number of bytes to copy to {@code dst}, must be smaller or equal to the width of the input (from srcPos to MSB).
+ * @return {@code dst}.
+ * @throws NullPointerException if {@code dst} is {@code null}.
+ * @throws IllegalArgumentException if {@code nBytes > 16}.
+ * @throws ArrayIndexOutOfBoundsException if {@code dstPos + nBytes > dst.length}.
*/
public static byte[] uuidToByteArray(final UUID src, final byte[] dst, final int dstPos, final int nBytes) {
if (0 == nBytes) {
return dst;
}
if (nBytes > 16) {
- throw new IllegalArgumentException("nBytes is greater than 16");
+ throw new IllegalArgumentException("nBytes > 16");
}
- longToByteArray(src.getMostSignificantBits(), 0, dst, dstPos, nBytes > 8 ? 8 : nBytes);
+ longToByteArray(src.getMostSignificantBits(), 0, dst, dstPos, Math.min(nBytes, 8));
if (nBytes >= 8) {
longToByteArray(src.getLeastSignificantBits(), 0, dst, dstPos + 8, nBytes - 8);
}
@@ -1542,22 +1389,12 @@ public static byte[] uuidToByteArray(final UUID src, final byte[] dst, final int
}
/**
- *
- * Converts bytes from an array into a UUID using the default (little endian, Lsb0) byte and
- * bit ordering.
- *
+ * Constructs a new instance.
*
- * @param src the byte array to convert
- * @param srcPos the position in {@code src} where to copy the result from
- * @return a UUID
- * @throws NullPointerException if {@code src} is {@code null}
- * @throws IllegalArgumentException if array does not contain at least 16 bytes beginning
- * with {@code srcPos}
+ * @deprecated Will be removed in 4.0.0.
*/
- public static UUID byteArrayToUuid(final byte[] src, final int srcPos) {
- if (src.length - srcPos < 16) {
- throw new IllegalArgumentException("Need at least 16 bytes for UUID");
- }
- return new UUID(byteArrayToLong(src, srcPos, 0, 0, 8), byteArrayToLong(src, srcPos + 8, 0, 0, 8));
+ @Deprecated
+ public Conversion() {
+ // empty
}
}
diff --git a/src/main/java/org/apache/commons/lang3/DoubleRange.java b/src/main/java/org/apache/commons/lang3/DoubleRange.java
new file mode 100644
index 00000000000..da1185835b3
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/DoubleRange.java
@@ -0,0 +1,112 @@
+/*
+ * 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;
+
+/**
+ * Specializes {@link NumberRange} for {@link Double}s.
+ *
+ *
+ * This class is not designed to interoperate with other NumberRanges
+ *
+ *
+ * @since 3.13.0
+ */
+public final class DoubleRange extends NumberRange {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Creates a range with the specified minimum and maximum values (both inclusive).
+ *
+ *
+ * The range uses the natural ordering of the elements to determine where values lie in the range.
+ *
+ *
+ *
+ * The arguments may be passed in the order (min, max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+ *
+ *
+ * @param fromInclusive The first value that defines the edge of the range, inclusive.
+ * @param toInclusive The second value that defines the edge of the range, inclusive.
+ * @return The range object, not null.
+ * @throws IllegalArgumentException if either value is NaN.
+ */
+ public static DoubleRange of(final double fromInclusive, final double toInclusive) {
+ return of(Double.valueOf(fromInclusive), Double.valueOf(toInclusive));
+ }
+
+ /**
+ * Creates a range with the specified minimum and maximum values (both inclusive).
+ *
+ *
+ * The range uses the natural ordering of the elements to determine where values lie in the range.
+ *
+ *
+ *
+ * The arguments may be passed in the order (min, max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+ *
+ *
+ * @param fromInclusive The first value that defines the edge of the range, inclusive.
+ * @param toInclusive The second value that defines the edge of the range, inclusive.
+ * @return The range object, not null.
+ * @throws NullPointerException if either element is null.
+ * @throws IllegalArgumentException if either element is NaN.
+ */
+ public static DoubleRange of(final Double fromInclusive, final Double toInclusive) {
+ return new DoubleRange(fromInclusive, toInclusive);
+ }
+
+ /**
+ * Creates an instance.
+ *
+ * @param number1 The first element, not null.
+ * @param number2 The second element, not null.
+ * @throws NullPointerException when element1 is null.
+ * @throws NullPointerException when element2 is null.
+ * @throws IllegalArgumentException when element1 or element2 is NaN.
+ */
+ private DoubleRange(final Double number1, final Double number2) {
+ super(number1, number2, null);
+ }
+
+ /**
+ * Fits the given value into this range by returning the given value or, if out of bounds, the range minimum if
+ * below, or the range maximum if above.
+ *
+ * {@code
+ * LongRange range = LongRange.of(16, 64);
+ * range.fit(-9) --> 16
+ * range.fit(0) --> 16
+ * range.fit(15) --> 16
+ * range.fit(16) --> 16
+ * range.fit(17) --> 17
+ * ...
+ * range.fit(63) --> 63
+ * range.fit(64) --> 64
+ * range.fit(99) --> 64
+ * }
+ *
+ * @param element The element to test.
+ * @return The minimum, the element, or the maximum depending on the element's location relative to the range.
+ * @since 3.19.0
+ */
+ public double fit(final double element) {
+ return super.fit(element).doubleValue();
+ }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/EnumUtils.java b/src/main/java/org/apache/commons/lang3/EnumUtils.java
index 75b052a9fcf..a0557f18ecc 100644
--- a/src/main/java/org/apache/commons/lang3/EnumUtils.java
+++ b/src/main/java/org/apache/commons/lang3/EnumUtils.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,
@@ -20,12 +20,18 @@
import java.util.Arrays;
import java.util.Collections;
import java.util.EnumSet;
-import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.function.ToIntFunction;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.apache.commons.lang3.stream.Streams;
/**
- * Utility library to provide helper methods for Java enums.
+ * Provides methods for Java enums.
*
* #ThreadSafe#
*
@@ -33,57 +39,58 @@
*/
public class EnumUtils {
- private static final String NULL_ELEMENTS_NOT_PERMITTED = "null elements not permitted";
private static final String CANNOT_STORE_S_S_VALUES_IN_S_BITS = "Cannot store %s %s values in %s bits";
- private static final String S_DOES_NOT_SEEM_TO_BE_AN_ENUM_TYPE = "%s does not seem to be an Enum type";
private static final String ENUM_CLASS_MUST_BE_DEFINED = "EnumClass must be defined.";
+ private static final String NULL_ELEMENTS_NOT_PERMITTED = "null elements not permitted";
+ private static final String S_DOES_NOT_SEEM_TO_BE_AN_ENUM_TYPE = "%s does not seem to be an Enum type";
/**
* Validate {@code enumClass}.
- * @param the type of the enumeration
- * @param enumClass to check
- * @return {@code enumClass}
- * @throws NullPointerException if {@code enumClass} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class
+ *
+ * @param The type of the enumeration.
+ * @param enumClass to check.
+ * @return {@code enumClass}.
+ * @throws NullPointerException if {@code enumClass} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class.
* @since 3.2
*/
private static > Class asEnum(final Class enumClass) {
- Validate.notNull(enumClass, ENUM_CLASS_MUST_BE_DEFINED);
+ Objects.requireNonNull(enumClass, ENUM_CLASS_MUST_BE_DEFINED);
Validate.isTrue(enumClass.isEnum(), S_DOES_NOT_SEEM_TO_BE_AN_ENUM_TYPE, enumClass);
return enumClass;
}
/**
* Validate that {@code enumClass} is compatible with representation in a {@code long}.
- * @param the type of the enumeration
- * @param enumClass to check
- * @return {@code enumClass}
- * @throws NullPointerException if {@code enumClass} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values
+ *
+ * @param The type of the enumeration.
+ * @param enumClass to check.
+ * @return {@code enumClass}.
+ * @throws NullPointerException if {@code enumClass} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values.
* @since 3.0.1
*/
private static > Class checkBitVectorable(final Class enumClass) {
final E[] constants = asEnum(enumClass).getEnumConstants();
- Validate.isTrue(constants.length <= Long.SIZE, CANNOT_STORE_S_S_VALUES_IN_S_BITS,
- Integer.valueOf(constants.length), enumClass.getSimpleName(), Integer.valueOf(Long.SIZE));
-
+ Validate.isTrue(constants.length <= Long.SIZE, CANNOT_STORE_S_S_VALUES_IN_S_BITS, Integer.valueOf(constants.length), enumClass.getSimpleName(),
+ Integer.valueOf(Long.SIZE));
return enumClass;
}
/**
- * Creates a long bit vector representation of the given array of Enum values.
+ * Creates a long bit vector representation of the given array of Enum values.
*
* This generates a value that is usable by {@link EnumUtils#processBitVector}.
*
* Do not use this method if you have more than 64 values in your Enum, as this
* would create a value greater than a long can hold.
*
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param values the values we want to convert, not {@code null}
- * @param the type of the enumeration
- * @return a long whose value provides a binary representation of the given set of enum values.
- * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param values The values we want to convert, not {@code null}.
+ * @param the type of the enumeration.
+ * @return A long whose value provides a binary representation of the given set of enum values.
+ * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values.
* @since 3.0.1
* @see #generateBitVectors(Class, Iterable)
*/
@@ -94,48 +101,48 @@ public static > long generateBitVector(final Class enumClas
}
/**
- * Creates a long bit vector representation of the given subset of an Enum.
+ * Creates a long bit vector representation of the given subset of an Enum.
*
* This generates a value that is usable by {@link EnumUtils#processBitVector}.
*
* Do not use this method if you have more than 64 values in your Enum, as this
* would create a value greater than a long can hold.
*
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param values the values we want to convert, not {@code null}, neither containing {@code null}
- * @param the type of the enumeration
- * @return a long whose value provides a binary representation of the given set of enum values.
- * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param values The values we want to convert, not {@code null}, neither containing {@code null}.
+ * @param the type of the enumeration.
+ * @return A long whose value provides a binary representation of the given set of enum values.
+ * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}.
* @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values,
- * or if any {@code values} {@code null}
+ * or if any {@code values} {@code null}.
* @since 3.0.1
* @see #generateBitVectors(Class, Iterable)
*/
public static > long generateBitVector(final Class enumClass, final Iterable values) {
checkBitVectorable(enumClass);
- Validate.notNull(values);
+ Objects.requireNonNull(values, "values");
long total = 0;
for (final E constant : values) {
- Validate.isTrue(constant != null, NULL_ELEMENTS_NOT_PERMITTED);
+ Objects.requireNonNull(constant, NULL_ELEMENTS_NOT_PERMITTED);
total |= 1L << constant.ordinal();
}
return total;
}
/**
- * Creates a bit vector representation of the given subset of an Enum using as many {@code long}s as needed.
+ * Creates a bit vector representation of the given subset of an Enum using as many {@code long}s as needed.
*
* This generates a value that is usable by {@link EnumUtils#processBitVectors}.
*
* Use this method if you have more than 64 values in your Enum.
*
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param values the values we want to convert, not {@code null}, neither containing {@code null}
- * @param the type of the enumeration
- * @return a long[] whose values provide a binary representation of the given set of enum values
- * with least significant digits rightmost.
- * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class, or if any {@code values} {@code null}
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param values The values we want to convert, not {@code null}, neither containing {@code null}.
+ * @param the type of the enumeration.
+ * @return A long[] whose values provide a binary representation of the given set of enum values
+ * with the least significant digits rightmost.
+ * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class, or if any {@code values} {@code null}.
* @since 3.2
*/
@SafeVarargs
@@ -146,93 +153,90 @@ public static > long[] generateBitVectors(final Class enumC
Collections.addAll(condensed, values);
final long[] result = new long[(enumClass.getEnumConstants().length - 1) / Long.SIZE + 1];
for (final E value : condensed) {
- result[value.ordinal() / Long.SIZE] |= 1L << (value.ordinal() % Long.SIZE);
+ result[value.ordinal() / Long.SIZE] |= 1L << value.ordinal() % Long.SIZE;
}
ArrayUtils.reverse(result);
return result;
}
/**
- * Creates a bit vector representation of the given subset of an Enum using as many {@code long}s as needed.
+ * Creates a bit vector representation of the given subset of an Enum using as many {@code long}s as needed.
*
* This generates a value that is usable by {@link EnumUtils#processBitVectors}.
*
* Use this method if you have more than 64 values in your Enum.
*
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param values the values we want to convert, not {@code null}, neither containing {@code null}
- * @param the type of the enumeration
- * @return a long[] whose values provide a binary representation of the given set of enum values
- * with least significant digits rightmost.
- * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class, or if any {@code values} {@code null}
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param values The values we want to convert, not {@code null}, neither containing {@code null}.
+ * @param the type of the enumeration.
+ * @return A long[] whose values provide a binary representation of the given set of enum values
+ * with the least significant digits rightmost.
+ * @throws NullPointerException if {@code enumClass} or {@code values} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class, or if any {@code values} {@code null}.
* @since 3.2
*/
public static > long[] generateBitVectors(final Class enumClass, final Iterable values) {
asEnum(enumClass);
- Validate.notNull(values);
+ Objects.requireNonNull(values, "values");
final EnumSet condensed = EnumSet.noneOf(enumClass);
- for (final E constant : values) {
- Validate.isTrue(constant != null, NULL_ELEMENTS_NOT_PERMITTED);
- condensed.add(constant);
- }
+ values.forEach(constant -> condensed.add(Objects.requireNonNull(constant, NULL_ELEMENTS_NOT_PERMITTED)));
final long[] result = new long[(enumClass.getEnumConstants().length - 1) / Long.SIZE + 1];
for (final E value : condensed) {
- result[value.ordinal() / Long.SIZE] |= 1L << (value.ordinal() % Long.SIZE);
+ result[value.ordinal() / Long.SIZE] |= 1L << value.ordinal() % Long.SIZE;
}
ArrayUtils.reverse(result);
return result;
}
/**
- * Gets the enum for the class, returning {@code null} if not found.
+ * Gets the enum for the class, returning {@code null} if not found.
*
* This method differs from {@link Enum#valueOf} in that it does not throw an exception
* for an invalid enum name.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns null
- * @return the enum, null if not found
+ * @param The type of the enumeration.
+ * @param enumClass The class of the enum to query, not null.
+ * @param enumName The enum name, null returns null.
+ * @return The enum, null if not found.
*/
public static > E getEnum(final Class enumClass, final String enumName) {
return getEnum(enumClass, enumName, null);
}
/**
- * Gets the enum for the class, returning {@code defaultEnum} if not found.
+ * Gets the enum for the class, returning {@code defaultEnum} if not found.
*
* This method differs from {@link Enum#valueOf} in that it does not throw an exception
* for an invalid enum name.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns default enum
- * @param defaultEnum the default enum
- * @return the enum, default enum if not found
+ * @param The type of the enumeration.
+ * @param enumClass The class of the enum to query, null returns default enum.
+ * @param enumName The enum name, null returns default enum.
+ * @param defaultEnum The default enum.
+ * @return The enum, default enum if not found.
* @since 3.10
*/
public static > E getEnum(final Class enumClass, final String enumName, final E defaultEnum) {
- if (enumName == null) {
+ if (enumClass == null || enumName == null) {
return defaultEnum;
}
try {
return Enum.valueOf(enumClass, enumName);
- } catch (final IllegalArgumentException ex) {
+ } catch (final IllegalArgumentException e) {
return defaultEnum;
}
}
/**
- * Gets the enum for the class, returning {@code null} if not found.
+ * Gets the enum for the class, returning {@code null} if not found.
*
* This method differs from {@link Enum#valueOf} in that it does not throw an exception
* for an invalid enum name and performs case insensitive matching of the name.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns null
- * @return the enum, null if not found
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, may be null.
+ * @param enumName The enum name, null returns null.
+ * @return The enum, null if not found.
* @since 3.8
*/
public static > E getEnumIgnoreCase(final Class enumClass, final String enumName) {
@@ -240,86 +244,165 @@ public static > E getEnumIgnoreCase(final Class enumClass,
}
/**
- * Gets the enum for the class, returning {@code defaultEnum} if not found.
+ * Gets the enum for the class, returning {@code defaultEnum} if not found.
*
* This method differs from {@link Enum#valueOf} in that it does not throw an exception
* for an invalid enum name and performs case insensitive matching of the name.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns default enum
- * @param defaultEnum the default enum
- * @return the enum, default enum if not found
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, null returns default enum.
+ * @param enumName The enum name, null returns default enum.
+ * @param defaultEnum The default enum.
+ * @return The enum, default enum if not found.
* @since 3.10
*/
- public static > E getEnumIgnoreCase(final Class enumClass, final String enumName, final E defaultEnum) {
- if (enumName == null || !enumClass.isEnum()) {
- return defaultEnum;
- }
- for (final E each : enumClass.getEnumConstants()) {
- if (each.name().equalsIgnoreCase(enumName)) {
- return each;
- }
- }
- return defaultEnum;
+ public static > E getEnumIgnoreCase(final Class enumClass, final String enumName,
+ final E defaultEnum) {
+ return getFirstEnumIgnoreCase(enumClass, enumName, Enum::name, defaultEnum);
}
/**
- * Gets the {@code List} of enums.
+ * Gets the {@link List} of enums.
*
* This method is useful when you need a list of enums rather than an array.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @return the modifiable list of enums, never null
+ * @param The type of the enumeration.
+ * @param enumClass The class of the enum to query, not null.
+ * @return The modifiable list of enums, never null.
*/
public static > List getEnumList(final Class enumClass) {
return new ArrayList<>(Arrays.asList(enumClass.getEnumConstants()));
}
/**
- * Gets the {@code Map} of enums by name.
+ * Gets the {@link Map} of enums by name.
*
* This method is useful when you need a map of enums by name.
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @return the modifiable map of enum names to enums, never null
+ * @param The type of the enumeration.
+ * @param enumClass The class of the enum to query, not null.
+ * @return The modifiable map of enum names to enums, never null.
*/
public static > Map getEnumMap(final Class enumClass) {
- final Map map = new LinkedHashMap<>();
- for (final E e: enumClass.getEnumConstants()) {
- map.put(e.name(), e);
+ return getEnumMap(enumClass, E::name);
+ }
+
+ /**
+ * Gets the {@link Map} of enums by name.
+ *
+ *
+ * This method is useful when you need a map of enums by name.
+ *
+ *
+ * @param the type of enumeration.
+ * @param the type of the map key.
+ * @param enumClass The class of the enum to query, not null.
+ * @param keyFunction The function to query for the key, not null.
+ * @return The modifiable map of enums, never null.
+ * @since 3.13.0
+ */
+ public static , K> Map getEnumMap(final Class enumClass, final Function keyFunction) {
+ return stream(enumClass).collect(Collectors.toMap(keyFunction::apply, Function.identity()));
+ }
+
+ /**
+ * Gets the enum for the class in a system property, returning {@code defaultEnum} if not found.
+ *
+ *
+ * This method differs from {@link Enum#valueOf} in that it does not throw an exception for an invalid enum name.
+ *
+ *
+ * If a {@link SecurityException} is caught, the return value is {@code null}.
+ *
+ *
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, not null.
+ * @param propName The system property key for the enum name, null returns default enum.
+ * @param defaultEnum The default enum.
+ * @return The enum, default enum if not found.
+ * @since 3.13.0
+ */
+ public static > E getEnumSystemProperty(final Class enumClass, final String propName, final E defaultEnum) {
+ return getEnum(enumClass, SystemProperties.getProperty(propName), defaultEnum);
+ }
+
+ /**
+ * Gets the enum for the class and value, returning {@code defaultEnum} if not found.
+ *
+ *
+ * This method differs from {@link Enum#valueOf} in that it does not throw an exception for an invalid enum name and performs case insensitive matching of
+ * the name.
+ *
+ *
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, not null.
+ * @param value The enum name, null returns default enum.
+ * @param toIntFunction The function that gets an int for an enum for comparison to {@code value}.
+ * @param defaultEnum The default enum.
+ * @return An enum, default enum if not found.
+ * @since 3.18.0
+ */
+ public static > E getFirstEnum(final Class enumClass, final int value, final ToIntFunction toIntFunction, final E defaultEnum) {
+ if (!isEnum(enumClass)) {
+ return defaultEnum;
+ }
+ return stream(enumClass).filter(e -> value == toIntFunction.applyAsInt(e)).findFirst().orElse(defaultEnum);
+ }
+
+ /**
+ * Gets the enum for the class, returning {@code defaultEnum} if not found.
+ *
+ * This method differs from {@link Enum#valueOf} in that it does not throw an exception
+ * for an invalid enum name and performs case insensitive matching of the name.
+ *
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, null returns default enum.
+ * @param enumName The enum name, null returns default enum.
+ * @param stringFunction The function that gets the string for an enum for comparison to {@code enumName}.
+ * @param defaultEnum The default enum.
+ * @return An enum, default enum if not found.
+ * @since 3.13.0
+ */
+ public static > E getFirstEnumIgnoreCase(final Class enumClass, final String enumName, final Function stringFunction,
+ final E defaultEnum) {
+ if (enumName == null) {
+ return defaultEnum;
}
- return map;
+ return stream(enumClass).filter(e -> enumName.equalsIgnoreCase(stringFunction.apply(e))).findFirst().orElse(defaultEnum);
+ }
+
+ private static > boolean isEnum(final Class enumClass) {
+ return enumClass != null && enumClass.isEnum();
}
/**
- * Checks if the specified name is a valid enum for the class.
+ * Checks if the specified name is a valid enum for the class.
*
- * This method differs from {@link Enum#valueOf} in that checks if the name is
- * a valid enum without needing to catch the exception.
+ *
+ * This method differs from {@link Enum#valueOf} in that it checks if the name is a valid enum without needing to catch the exception.
+ *
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns false
- * @return true if the enum name is valid, otherwise false
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, null returns false.
+ * @param enumName The enum name, null returns false.
+ * @return true if the enum name is valid, otherwise false.
*/
public static > boolean isValidEnum(final Class enumClass, final String enumName) {
return getEnum(enumClass, enumName) != null;
}
/**
- * Checks if the specified name is a valid enum for the class.
+ * Checks if the specified name is a valid enum for the class.
*
- * This method differs from {@link Enum#valueOf} in that checks if the name is
- * a valid enum without needing to catch the exception
- * and performs case insensitive matching of the name.
+ *
+ * This method differs from {@link Enum#valueOf} in that it checks if the name is a valid enum without needing to catch the exception and performs case
+ * insensitive matching of the name.
+ *
*
- * @param the type of the enumeration
- * @param enumClass the class of the enum to query, not null
- * @param enumName the enum name, null returns false
- * @return true if the enum name is valid, otherwise false
+ * @param the type of the enumeration.
+ * @param enumClass The class of the enum to query, null returns false.
+ * @param enumName The enum name, null returns false.
+ * @return true if the enum name is valid, otherwise false.
* @since 3.8
*/
public static > boolean isValidEnumIgnoreCase(final Class enumClass, final String enumName) {
@@ -327,53 +410,71 @@ public static > boolean isValidEnumIgnoreCase(final Class e
}
/**
- * Convert a long value created by {@link EnumUtils#generateBitVector} into the set of
- * enum values that it represents.
+ * Convert a long value created by {@link EnumUtils#generateBitVector} into the set of
+ * enum values that it represents.
*
* If you store this value, beware any changes to the enum that would affect ordinal values.
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param value the long value representation of a set of enum values
- * @param the type of the enumeration
- * @return a set of enum values
- * @throws NullPointerException if {@code enumClass} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values
+ *
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param value The long value representation of a set of enum values.
+ * @param the type of the enumeration.
+ * @return A set of enum values.
+ * @throws NullPointerException if {@code enumClass} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class or has more than 64 values.
* @since 3.0.1
*/
public static > EnumSet processBitVector(final Class enumClass, final long value) {
- checkBitVectorable(enumClass).getEnumConstants();
- return processBitVectors(enumClass, value);
+ return processBitVectors(checkBitVectorable(enumClass), value);
}
/**
- * Convert a {@code long[]} created by {@link EnumUtils#generateBitVectors} into the set of
- * enum values that it represents.
+ * Convert a {@code long[]} created by {@link EnumUtils#generateBitVectors} into the set of
+ * enum values that it represents.
*
* If you store this value, beware any changes to the enum that would affect ordinal values.
- * @param enumClass the class of the enum we are working with, not {@code null}
- * @param values the long[] bearing the representation of a set of enum values, least significant digits rightmost, not {@code null}
- * @param the type of the enumeration
- * @return a set of enum values
- * @throws NullPointerException if {@code enumClass} is {@code null}
- * @throws IllegalArgumentException if {@code enumClass} is not an enum class
+ *
+ * @param enumClass The class of the enum we are working with, not {@code null}.
+ * @param values The long[] bearing the representation of a set of enum values, the least significant digits rightmost, not {@code null}.
+ * @param the type of the enumeration.
+ * @return A set of enum values.
+ * @throws NullPointerException if {@code enumClass} is {@code null}.
+ * @throws IllegalArgumentException if {@code enumClass} is not an enum class.
* @since 3.2
*/
public static