examples added in Javadoc

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

@@ -1855,6 +1855,15 @@ public static void reverse(final short[] array, final int startIndexInclusive, f
      * <p>There is no special handling for multi-dimensional arrays.</p>
      *
      * <p>This method does nothing for a {@code null} input array.</p>
+     * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap(["1", "2", "3"], 0, 2) -> ["3", "2", "1"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3"], 0, 0) -> ["1", "2", "3"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3"], 1, 0) -> ["2", "1", "3"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3"], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
      *
      * @param array the array to swap, may be {@code null}
      * @param offset1 the index of the first element to swap
@@ -1873,6 +1882,15 @@ public static void swap(final Object[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([true, false, true], 0, 2) -> [true, false, true]</li>
+     *         <li>ArrayUtils.swap([true, false, true], 0, 0) -> [true, false, true]</li>
+     *         <li>ArrayUtils.swap([true, false, true], 1, 0) -> [false, true, true]</li>
+     *         <li>ArrayUtils.swap([true, false, true], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -1890,6 +1908,15 @@ public static void swap(final long[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     *
      * @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
@@ -1907,6 +1934,15 @@ public static void swap(final int[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -1923,6 +1959,15 @@ public static void swap(final short[] array, int offset1, int offset2) {
      * <p>Swaps two elements in the given array.</p>
      *
      * <p>This method does nothing for a {@code null} input array.</p>
+     * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
      *
      * @param array  the array to swap, may be {@code null}
      * @param offset1 the index of the first element to swap
@@ -1941,6 +1986,15 @@ public static void swap(final char[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -1958,6 +2012,15 @@ public static void swap(final byte[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -1975,6 +2038,15 @@ public static void swap(final double[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -1992,6 +2064,15 @@ public static void swap(final float[] array, int offset1, int offset2) {
      *
      * <p>This method does nothing for a {@code null} input array.</p>
      *
+      * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 2) -> [3, 2, 1]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 0) -> [1, 2, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 1, 0) -> [2, 1, 3]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3], 0, 5) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2009,6 +2090,15 @@ public static void swap(final boolean[] array, int offset1, int offset2) {
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 2, 1) -> ["3", "2", "1", "4"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 0, 1) -> ["1", "2", "3", "4"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3", "4"], 2, 0, 2) -> ["3", "4", "1", "2"]</li>
+     *         <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2031,6 +2121,15 @@ public static void swap(final boolean[] array,  int offset1, int offset2, int le
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([true, false, true, false], 0, 2, 1) -> [true, false, true, false]</li>
+     *         <li>ArrayUtils.swap([true, false, true, false], 0, 0, 1) -> [true, false, true, false]</li>
+     *         <li>ArrayUtils.swap([true, false, true, false], 0, 2, 2) -> [true, false, true, false]</li>
+     *         <li>ArrayUtils.swap([true, false, true, false], 0, 5, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2054,6 +2153,15 @@ public static void swap(final byte[] array,  int offset1, int offset2, int len)
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2076,6 +2184,15 @@ public static void swap(final char[] array,  int offset1, int offset2, int len)
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2098,6 +2215,15 @@ public static void swap(final double[] array,  int offset1, int offset2, int len
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2120,6 +2246,15 @@ public static void swap(final float[] array,  int offset1, int offset2, int len)
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2142,6 +2277,15 @@ public static void swap(final int[] array,  int offset1, int offset2, int len) {
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2164,6 +2308,15 @@ public static void swap(final long[] array,  int offset1, int offset2, int len)
      * 
      * <p>This method does nothing for a {@code null} input array.</p>
      * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
+     * 
      * @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
@@ -2185,6 +2338,15 @@ public static void swap(final Object[] array,  int offset1, int offset2, int len
     * <p>Swaps a series of elements in the given array.</p>
     * 
     * <p>This method does nothing for a {@code null} input array.</p>
+     * 
+     * <p>Examples:
+     *     <ul>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -> [3, 2, 1, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -> [1, 2, 3, 4]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -> [3, 4, 1, 2]</li>
+     *         <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -> ArrayOutOfBoundsException</li>
+     *     </ul>
+     * </p>
     * 
     * @param array the array to swap, may be {@code null}
     * @param offset1 the index of the first element in the series to swap