[COLLECTIONS-781] - INDEX_NOT_FOUND Constant (#210)

* COLLECTIONS-781 - INDEX_NOT_FOUND Constant

* Update CollectionUtils.java

Javadoc.

Co-authored-by: Gary Gregory <garydgregory@users.noreply.github.com>

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

@@ -43,14 +43,6 @@ class ArrayUtils {
      * Don't allow instances.
      */
     private ArrayUtils() {}
-
-    /**
-     * The index value when an element is not found in a list or array: {@code -1}. This value is returned by methods in
-     * this class and can also be used in comparisons with values returned by various method from
-     * {@link java.util.List}.
-     */
-    static final int INDEX_NOT_FOUND = -1;
-
     /**
      * <p>
      * Checks if the object is in the given array.
@@ -67,7 +59,7 @@ class ArrayUtils {
      * @return {@code true} if the array contains the object
      */
     static boolean contains(final Object[] array, final Object objectToFind) {
-        return indexOf(array, objectToFind) != INDEX_NOT_FOUND;
+        return indexOf(array, objectToFind) != CollectionUtils.INDEX_NOT_FOUND;
     }
 
     /**
@@ -76,14 +68,14 @@ class ArrayUtils {
      * </p>
      *
      * <p>
-     * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+     * This method returns {@link CollectionUtils#INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
      * </p>
      *
      * @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
+     * @return the index of the object within the array, {@link CollectionUtils#INDEX_NOT_FOUND} ({@code -1}) if not found or
      *         {@code null} array input
      */
     static <T> int indexOf(final T[] array, final Object objectToFind) {
@@ -96,12 +88,12 @@ class ArrayUtils {
      * </p>
      *
      * <p>
-     * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
+     * This method returns {@link CollectionUtils#INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
      * </p>
      *
      * <p>
      * A negative startIndex is treated as zero. A startIndex larger than the array length will return
-     * {@link #INDEX_NOT_FOUND} ({@code -1}).
+     * {@link CollectionUtils#INDEX_NOT_FOUND} ({@code -1}).
      * </p>
      *
      * @param array
@@ -110,12 +102,12 @@ class ArrayUtils {
      *            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
+     * @return the index of the object within the array starting at the index, {@link CollectionUtils#INDEX_NOT_FOUND} ({@code -1}) if
      *         not found or {@code null} array input
      */
     static int indexOf(final Object[] array, final Object objectToFind, int startIndex) {
         if (array == null) {
-            return INDEX_NOT_FOUND;
+            return CollectionUtils.INDEX_NOT_FOUND;
         }
         if (startIndex < 0) {
             startIndex = 0;
@@ -133,7 +125,7 @@ class ArrayUtils {
                 }
             }
         }
-        return INDEX_NOT_FOUND;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
 }

src/main/java/org/apache/commons/collections4/CollectionUtils.java

@@ -56,6 +56,13 @@ import org.apache.commons.collections4.iterators.PermutationIterator;
  */
 public class CollectionUtils {
 
+    /**
+     * The index value when an element is not found in a collection or array: {@code -1}.
+     *
+     * @since 4.5
+     */
+    public static final int INDEX_NOT_FOUND = -1;
+
     /**
      * Helper class to easily access cardinality properties of two collections.
      * @param <O>  the element type

src/main/java/org/apache/commons/collections4/IteratorUtils.java

@@ -1249,7 +1249,7 @@ public class IteratorUtils {
                 }
             }
         }
-        return -1;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
     /**

src/main/java/org/apache/commons/collections4/ListUtils.java

@@ -42,7 +42,6 @@ import org.apache.commons.collections4.sequence.SequencesComparator;
  * @since 1.0
  */
 public class ListUtils {
-
     /**
      * Don't allow instances.
      */
@@ -539,7 +538,7 @@ public class ListUtils {
                 }
             }
         }
-        return -1;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
     //-----------------------------------------------------------------------

src/main/java/org/apache/commons/collections4/list/AbstractLinkedList.java

@@ -29,6 +29,7 @@ import java.util.ListIterator;
 import java.util.NoSuchElementException;
 import java.util.Objects;
 
+import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.collections4.OrderedIterator;
 
 /**
@@ -143,7 +144,7 @@ public abstract class AbstractLinkedList<E> implements List<E> {
             }
             i++;
         }
-        return -1;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
     @Override
@@ -155,7 +156,7 @@ public abstract class AbstractLinkedList<E> implements List<E> {
             }
             i--;
         }
-        return -1;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
     @Override

src/main/java/org/apache/commons/collections4/map/LinkedMap.java

@@ -28,6 +28,7 @@ import java.util.ListIterator;
 import java.util.Map;
 import java.util.function.Predicate;
 
+import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.collections4.iterators.UnmodifiableIterator;
 import org.apache.commons.collections4.iterators.UnmodifiableListIterator;
 import org.apache.commons.collections4.list.UnmodifiableList;
@@ -183,7 +184,7 @@ public class LinkedMap<K, V> extends AbstractLinkedMap<K, V> implements Serializ
                 return i;
             }
         }
-        return -1;
+        return CollectionUtils.INDEX_NOT_FOUND;
     }
 
     /**