Package org.kiwiproject.collect

Class KiwiLists

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

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> void
    checkMinimumSize(List<T> items, int minSize)
    Checks that the given list is not null and has the given minimum size.
    static <T> void
    checkNonNullInputList(List<T> items)
    Checks that the given list is not null.
    static <T> List<T>
    distinct(Collection<T> collection)
    Returns a list of the collection elements with duplicates stripped out.
    static <T> List<T>
    distinctOrEmpty(Collection<T> collection)
    Returns a list of the collection elements with duplicates stripped out or an empty list if the input collection is null (or empty).
    static <T> List<T>
    distinctOrNull(Collection<T> collection)
    Returns a list of the collection elements with duplicates stripped out or `null` if a null value is passed in.
    static <T> T
    fifth(List<T> items)
    Return the fifth element in the specified list of items.
    static <T> T
    first(List<T> items)
    Return the first element in the specified list of items.
    static <T> Optional<T>
    firstIfPresent(List<T> items)
    Returns an Optional containing the first element in specified list of items, or an empty optional if the list is null or empty.
    static <T> List<T>
    firstN(List<T> items, int number)
    Returns a view of the "first N" elements of the input list.
    static <T> T
    fourth(List<T> items)
    Return the fourth element in the specified list of items.
    static <T> boolean
    hasOneElement(List<T> items)
    Checks whether the specified list is non-null and has only one item.
    static <T> boolean
    isNotNullOrEmpty(List<T> items)
    Checks whether the specified list is neither null nor empty.
    static <T> boolean
    isNullOrEmpty(List<T> items)
    Checks whether the specified list is null or empty.
    static <T> T
    last(List<T> items)
    Returns the last element in the specified list of items.
    static <T> Optional<T>
    lastIfPresent(List<T> items)
    Returns an Optional containing the last element in specified list of items, or an empty optional if the list is null or empty.
    static <T> List<T>
    lastN(List<T> items, int number)
    Returns a view of the "last N" elements of the input list.
    static <T> List<T>
    newListStartingAtCircularOffset(List<T> input, long startOffset)
    Returns a new list with the same elements and the same size as the original, however the initial position in the list is now the element specified by the "startOffset" and the list wraps around through the contents to end with "startOffset" - 1
    static <T> T
    nth(List<T> items, int number)
    Return the nth element in the specified list of items, starting at one for the first element, two for the second, etc.
    static <T> T
    penultimate(List<T> items)
    Returns the penultimate (second to last) element in the specified list.
    static <T> T
    second(List<T> items)
    Return the second element in the specified list of items.
    static <T> T
    secondToLast(List<T> items)
    Synonym for penultimate(List).
    static <T> List<T>
    shuffledArrayListOf(T... items)
    Create a new ArrayList with the given items shuffled using Collections.shuffle(List).
    static <T> List<T>
    shuffledListOf(T... items)
    Create a new unmodifiable List with the given items shuffled using Collections.shuffle(List).
    static <T> List<T>
    sorted(List<T> items)
    Given a list, sort it according to the natural order, returning a new list.
    static <T> List<T>
    sorted(List<T> items, Comparator<T> comparator)
    Given a list, sort it according to the provided Comparator returning a new list.
    static <T> List<T>
    subListExcludingFirst(List<T> items)
    Returns a view of the portion of the given list excluding the first element.
    static <T> List<T>
    subListExcludingLast(List<T> items)
    Returns a view of the portion of the given list excluding the last element.
    static <T> List<T>
    subListFrom(List<T> items, int number)
    Returns a view of the portion of the given list starting at the given logical element number, where the numbers start at one, until and including the last element in the list.
    static <T> List<T>
    subListFromIndex(List<T> items, int index)
    Returns a view of the portion of the given list starting at the given index, until and including the last element in the list.
    static <T> T
    third(List<T> items)
    Return the third element in the specified list 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(List<T> items)
      Checks whether the specified list is null or empty.
      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      Returns:
      true if list is null or empty; false otherwise

    • isNotNullOrEmpty

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

    • hasOneElement

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

    • sorted

      public static <T> List<T> sorted(List<T> items)
      Given a list, sort it according to the natural order, returning a new list.
      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      Returns:
      a new sorted list

    • sorted

      public static <T> List<T> sorted(List<T> items, Comparator<T> comparator)
      Given a list, sort it according to the provided Comparator returning a new list.
      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      comparator - a Comparator to be used to compare stream elements
      Returns:
      a new sorted list

    • first

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

    • firstIfPresent

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

    • second

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

    • third

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

    • fourth

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

    • fifth

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

    • penultimate

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

    • secondToLast

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

    • last

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

    • lastIfPresent

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

    • nth

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

    • distinct

      public static <T> List<T> distinct(Collection<T> collection)
      Returns a list of the collection elements with duplicates stripped out.
      Type Parameters:
      T - the type of items in the collection
      Parameters:
      collection - the collection of values
      Returns:
      a new list with only unique elements
      Throws:
      IllegalArgumentException - if the collection is null

    • distinctOrNull

      public static <T> List<T> distinctOrNull(Collection<T> collection)
      Returns a list 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
      Returns:
      a new list with only unique elements or null.

    • distinctOrEmpty

      public static <T> List<T> distinctOrEmpty(Collection<T> collection)
      Returns a list of the collection elements with duplicates stripped out or an empty list if the input collection is null (or empty).
      Type Parameters:
      T - the type of items in the collection
      Parameters:
      collection - the collection of values
      Returns:
      a new list with only unique elements or an empty list

    • newListStartingAtCircularOffset

      public static <T> List<T> newListStartingAtCircularOffset(List<T> input, long startOffset)
      Returns a new list with the same elements and the same size as the original, however the initial position in the list is now the element specified by the "startOffset" and the list wraps around through the contents to end with "startOffset" - 1
      Type Parameters:
      T - the type of the items in the list
      Parameters:
      input - the original list
      startOffset - the desired offset to start the new list
      Returns:
      a new list starting at the desired offset

    • subListExcludingFirst

      public static <T> List<T> subListExcludingFirst(List<T> items)
      Returns a view of the portion of the given list excluding the first element.

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of the items in the list
      Parameters:
      items - the list
      Returns:
      a view of the given list excluding the first item backed by the original list
      Throws:
      NullPointerException - if the list is null
      See Also:

    • subListExcludingLast

      public static <T> List<T> subListExcludingLast(List<T> items)
      Returns a view of the portion of the given list excluding the last element.

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of the items in the list
      Parameters:
      items - the list
      Returns:
      a view of the given list excluding the last item backed by the original list
      Throws:
      NullPointerException - if the list is null
      See Also:

    • subListFrom

      public static <T> List<T> subListFrom(List<T> items, int number)
      Returns a view of the portion of the given list starting at the given logical element number, where the numbers start at one, until and including the last element in the list. This is useful if something is using one-based element numbers for some reason. Use subListFromIndex(List, int) if you want to use zero-based list indices.

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      number - the number of the element to start the sublist, starting at one (not zero)
      Returns:
      a view of the given list backed by the original list, starting at the given one-based number
      Throws:
      NullPointerException - if the list is null
      IllegalArgumentException - if the given number is negative or is higher than the size of the list
      See Also:

    • subListFromIndex

      public static <T> List<T> subListFromIndex(List<T> items, int index)
      Returns a view of the portion of the given list starting at the given index, until and including the last element in the list.

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      index - the index in the list to start the sublist, zero-based like normal List methods
      Returns:
      a view of the given list backed by the original list, starting at the given zero-based index
      Throws:
      NullPointerException - if the list is null
      IllegalArgumentException - if the given index is negative or is higher than the last index in the list
      See Also:

    • firstN

      public static <T> List<T> firstN(List<T> items, int number)
      Returns a view of the "first N" elements of the input list.

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

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      number - the number of items wanted from the start of the list
      Returns:
      a view of the given list, backed by the original list, containing the last number elements
      See Also:

    • lastN

      public static <T> List<T> lastN(List<T> items, int number)
      Returns a view of the "last N" elements of the input list.

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

      This method has the same semantics as List.subList(int, int) since it calls that method.

      Type Parameters:
      T - the type of items in the list
      Parameters:
      items - the list
      number - the number of items wanted from the end of the list
      Returns:
      a view of the given list, backed by the original list, containing the first number elements
      See Also:

    • checkMinimumSize

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

    • checkNonNullInputList

      public static <T> void checkNonNullInputList(List<T> items)
      Checks that the given list is not null.
      Type Parameters:
      T - the type of the items in the list
      Parameters:
      items - the list
      Throws:
      NullPointerException - if the list is null

    • shuffledListOf

      @SafeVarargs public static <T> List<T> shuffledListOf(T... items)
      Create a new unmodifiable List with the given items shuffled using Collections.shuffle(List).
      Type Parameters:
      T - the type of the items in the list
      Parameters:
      items - the items to include in the new list
      Returns:
      an unmodifiable List with the given items in pseudorandom order

    • shuffledArrayListOf

      @SafeVarargs public static <T> List<T> shuffledArrayListOf(T... items)
      Create a new ArrayList with the given items shuffled using Collections.shuffle(List).
      Type Parameters:
      T - the type of the items in the list
      Parameters:
      items - the items to include in the new list
      Returns:
      an ArrayList with the given items in pseudorandom order