Package org.kiwiproject.collect

Class KiwiArrays

java.lang.Object
org.kiwiproject.collect.KiwiArrays
public final class KiwiArrays extends Object
Utility methods for working with Array instances.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> void
    checkMinimumSize(T[] items, int minSize)
    Checks that the given array is not null and has the given minimum size.
    static <T> void
    checkNonNullInputArray(T[] items)
    Checks that the given array is not null.
    static <T> T[]
    distinct(T[] collection, Class<T> arrayType)
    Returns an array of the collection elements with duplicates stripped out.
    static <T> T[]
    distinctOrNull(T[] collection, Class<T> arrayType)
    Returns an array of the collection elements with duplicates stripped out or `null` if a null value is passed in.
    static <T> T
    fifth(T[] items)
    Return the fifth element in the specified array of items.
    static <T> T
    first(T[] items)
    Return the first element in the specified array of items.
    static <T> Optional<T>
    firstIfPresent(T[] items)
    Returns an Optional containing the first element in specified array of items, or an empty optional if the array is null or empty.
    static <T> T[]
    firstN(T[] items, int number)
    Returns a new array containing the "first N" elements of the input array.
    static <T> T
    fourth(T[] items)
    Return the fourth element in the specified array of items.
    static <T> boolean
    hasOneElement(T[] items)
    Checks whether the specified array is non-null and has only one item.
    static <T> boolean
    isNotNullOrEmpty(T[] items)
    Checks whether the specified array is neither null nor empty.
    static <T> boolean
    isNullOrEmpty(T[] items)
    Checks whether the specified array is null or empty.
    static <T> T
    last(T[] items)
    Returns the last element in the specified array of items.
    static <T> Optional<T>
    lastIfPresent(T[] items)
    Returns an Optional containing the last element in specified array of items, or an empty optional if the array is null or empty.
    static <T> T[]
    lastN(T[] items, int number)
    Returns a new array containing the "last N" elements of the input array.
    static <T> T[]
    newArrayStartingAtCircularOffset(T[] input, long startOffset, Class<T> arrayType)
    Returns a new array with the same elements and the same size as the original, however the initial position in the array is now the element specified by the "startOffset" and the array wraps around through the contents to end with "startOffset" - 1
    static <T> T
    nth(T[] items, int number)
    Return the nth element in the specified array of items, starting at one for the first element, two for the second, etc.
    static <T> T
    penultimate(T[] items)
    Returns the penultimate (second to last) element in the specified array.
    static <T> T
    second(T[] items)
    Return the second element in the specified array of items.
    static <T> T
    secondToLast(T[] items)
    Synonym for penultimate(Object[]).
    static <T> T[]
    sorted(T[] items, Class<T> arrayType)
    Given an array, sort it according to the natural order, returning a new list.
    static <T> T[]
    sorted(T[] items, Comparator<T> comparator, Class<T> arrayType)
    Given an array, sort it according to the provided Comparator returning a new array.
    static <T> T[]
    subArrayExcludingFirst(T[] items)
    Returns a new array containing the portion of the given array excluding the first element.
    static <T> T[]
    subArrayExcludingLast(T[] items)
    Returns a new array containing the portion of the given array excluding the last element.
    static <T> T[]
    subArrayFrom(T[] items, int number)
    Returns a new array containing the portion of the given array starting at the given logical element number, where the numbers start at one, until and including the last element in the array.
    static <T> T[]
    subArrayFromIndex(T[] items, int index)
    Returns a new array containing the portion of the given array starting at the given index, until and including the last element in the array.
    static <T> T
    third(T[] items)
    Return the third element in the specified array of items.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isNullOrEmpty

      public static <T> boolean isNullOrEmpty(T[] items)
      Checks whether the specified array is null or empty.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      true if array is null or empty; false otherwise

    • isNotNullOrEmpty

      public static <T> boolean isNotNullOrEmpty(T[] items)
      Checks whether the specified array is neither null nor empty.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      true if array is NOT null or empty; false otherwise

    • hasOneElement

      public static <T> boolean hasOneElement(T[] items)
      Checks whether the specified array is non-null and has only one item.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      true if array is non-null and has exactly one item; false otherwise

    • sorted

      public static <T> T[] sorted(T[] items, Class<T> arrayType)
      Given an array, sort it according to the natural order, returning a new list.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      arrayType - the type of the items in the array. Needed to ensure the new array is not Object[]
      Returns:
      a new sorted array

    • sorted

      public static <T> T[] sorted(T[] items, Comparator<T> comparator, Class<T> arrayType)
      Given an array, sort it according to the provided Comparator returning a new array.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      comparator - a Comparator to be used to compare stream elements
      arrayType - the type of the items in the array. Needed to ensure the new array is not Object[]
      Returns:
      a new sorted array

    • first

      public static <T> T first(T[] items)
      Return the first element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the first item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least one item
      NullPointerException - if the array is null

    • firstIfPresent

      public static <T> Optional<T> firstIfPresent(T[] items)
      Returns an Optional containing the first element in specified array of items, or an empty optional if the array is null or empty.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      Optional containing first element if exists, otherwise Optional.empty()

    • second

      public static <T> T second(T[] items)
      Return the second element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the second item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least two items
      NullPointerException - if the array is null

    • third

      public static <T> T third(T[] items)
      Return the third element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the third item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least three items
      NullPointerException - if the array is null

    • fourth

      public static <T> T fourth(T[] items)
      Return the fourth element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the fourth item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least four items
      NullPointerException - if the array is null

    • fifth

      public static <T> T fifth(T[] items)
      Return the fifth element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the fifth item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least five items
      NullPointerException - if the array is null

    • penultimate

      public static <T> T penultimate(T[] items)
      Returns the penultimate (second to last) element in the specified array.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the penultimate item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least two items
      NullPointerException - if the array is null
      See Also:

    • secondToLast

      public static <T> T secondToLast(T[] items)
      Synonym for penultimate(Object[]).
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the penultimate item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least two items
      NullPointerException - if the array is null
      See Also:

    • last

      public static <T> T last(T[] items)
      Returns the last element in the specified array of items.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      the last item in the list
      Throws:
      IllegalArgumentException - if the array does not contain at least one item
      NullPointerException - if the array is null

    • lastIfPresent

      public static <T> Optional<T> lastIfPresent(T[] items)
      Returns an Optional containing the last element in specified array of items, or an empty optional if the array is null or empty.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Returns:
      Optional containing last element if exists, otherwise Optional.empty()

    • nth

      public static <T> T nth(T[] items, int number)
      Return the nth element in the specified array of items, starting at one for the first element, two for the second, etc.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      number - the number of the element to retrieve, starting at one (not zero)
      Returns:
      the nth item in items
      Throws:
      IllegalArgumentException - if the array does not contain at least number items
      NullPointerException - if the array is null

    • distinct

      public static <T> T[] distinct(T[] collection, Class<T> arrayType)
      Returns an array of the collection elements with duplicates stripped out.
      Type Parameters:
      T - the type of items in the collection
      Parameters:
      collection - the collection of values
      arrayType - the type of the items in the array. Needed to ensure the new array is not Object[]
      Returns:
      a new array with only unique elements
      Throws:
      IllegalArgumentException - if the collection is null

    • distinctOrNull

      public static <T> T[] distinctOrNull(T[] collection, Class<T> arrayType)
      Returns an array of the collection elements with duplicates stripped out or `null` if a null value is passed in.
      Type Parameters:
      T - the type of items in the collection
      Parameters:
      collection - the collection of values
      arrayType - the type of the items in the array. Needed to ensure the new array is not Object[]
      Returns:
      a new array with only unique elements or null.

    • newArrayStartingAtCircularOffset

      public static <T> T[] newArrayStartingAtCircularOffset(T[] input, long startOffset, Class<T> arrayType)
      Returns a new array with the same elements and the same size as the original, however the initial position in the array is now the element specified by the "startOffset" and the array wraps around through the contents to end with "startOffset" - 1
      Type Parameters:
      T - the type of the items in the array
      Parameters:
      input - the original array
      startOffset - the desired offset to start the new array
      arrayType - the type of the items in the array. Needed to ensure the new array is not Object[]
      Returns:
      a new array starting at the desired offset

    • subArrayExcludingFirst

      public static <T> T[] subArrayExcludingFirst(T[] items)
      Returns a new array containing the portion of the given array excluding the first element.
      Type Parameters:
      T - the type of the items in the array
      Parameters:
      items - the array
      Returns:
      a new array containing the given array excluding the first item
      Throws:
      NullPointerException - if the array is null

    • subArrayExcludingLast

      public static <T> T[] subArrayExcludingLast(T[] items)
      Returns a new array containing the portion of the given array excluding the last element.
      Type Parameters:
      T - the type of the items in the array
      Parameters:
      items - the array
      Returns:
      a new array containing the given array excluding the last item
      Throws:
      NullPointerException - if the array is null

    • subArrayFrom

      public static <T> T[] subArrayFrom(T[] items, int number)
      Returns a new array containing the portion of the given array starting at the given logical element number, where the numbers start at one, until and including the last element in the array. This is useful if something is using one-based element numbers for some reason. Use subArrayFromIndex(Object[], int) if you want to use zero-based list indices.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      number - the number of the element to start the subarray, starting at one (not zero)
      Returns:
      a new array containing the given array, starting at the given one-based number
      Throws:
      NullPointerException - if the array is null
      IllegalArgumentException - if the given number is negative or is higher than the size of the array

    • subArrayFromIndex

      public static <T> T[] subArrayFromIndex(T[] items, int index)
      Returns a new array containing the portion of the given array starting at the given index, until and including the last element in the array.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      index - the index in the array to start the subarray, zero-based like normal Array accessors
      Returns:
      a new array containing the given array, starting at the given zero-based index
      Throws:
      NullPointerException - if the array is null
      IllegalArgumentException - if the given index is negative or is higher than the last index in the array

    • firstN

      public static <T> T[] firstN(T[] items, int number)
      Returns a new array containing the "first N" elements of the input array.

      If the given number is larger than the size of the array, the entire array is returned, rather than throw an exception. In this case, the input array is returned directly, i.e. return items.

      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      number - the number of items wanted from the start of the array
      Returns:
      a new array containing the given array containing the last number elements

    • lastN

      public static <T> T[] lastN(T[] items, int number)
      Returns a new array containing the "last N" elements of the input array.

      If the given number is larger than the size of the array, the entire array is returned, rather than throw an exception. In this case, the input array is returned directly, i.e. return items.

      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      number - the number of items wanted from the end of the array
      Returns:
      a new array containing the given array containing the first number elements

    • checkMinimumSize

      public static <T> void checkMinimumSize(T[] items, int minSize)
      Checks that the given array is not null and has the given minimum size.
      Type Parameters:
      T - the type of the items in the array
      Parameters:
      items - the array
      minSize - the minimum required size
      Throws:
      NullPointerException - if the array is null
      IllegalArgumentException - if minSize is not positive or the array does not contain minSize elements

    • checkNonNullInputArray

      public static <T> void checkNonNullInputArray(T[] items)
      Checks that the given array is not null.
      Type Parameters:
      T - the type of items in the array
      Parameters:
      items - the array
      Throws:
      NullPointerException - if the array is null