Package org.kiwiproject.collect

Class KiwiLists

  • public class KiwiLists
extends Object
    Utility methods for working with List instances.

    • Constructor Summary

      Constructors 
      Constructor Description
      KiwiLists()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> void checkNonNullInputList​(List<T> items)  
      static <T> List<T> distinct​(Collection<T> collection)
      Returns a list of the collection elements with duplicates stripped out.
      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> 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> 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> 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> T third​(List<T> items)
      Return the third element in the specified list of items.

    • Constructor Detail

      • KiwiLists

        public KiwiLists()

    • Method Detail

      • 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(List)

      • 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.

      • checkNonNullInputList

        public static <T> void checkNonNullInputList​(List<T> items)

      • 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