Class KiwiLists
- java.lang.Object
-
- org.kiwiproject.collect.KiwiLists
-
-
Constructor Summary
Constructors Constructor Description KiwiLists()
-
Method Summary
All Methods Static Methods Concrete Methods 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>
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 anOptional
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 anOptional
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" - 1static <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 forpenultimate(List)
.static <T> List<T>
shuffledArrayListOf(T... items)
Create a newArrayList
with the given items shuffled usingCollections.shuffle(List)
.static <T> List<T>
shuffledListOf(T... items)
Create a new unmodifiableList
with the given items shuffled usingCollections.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 providedComparator
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.
-
-
-
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 providedComparator
returning a new list.- Type Parameters:
T
- the type of items in the list- Parameters:
items
- the listcomparator
- 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 itemNullPointerException
- if the list is null
-
firstIfPresent
public static <T> Optional<T> firstIfPresent(List<T> items)
Returns anOptional
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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- if the list is null- See Also:
secondToLast(List)
-
secondToLast
public static <T> T secondToLast(List<T> items)
Synonym forpenultimate(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 itemsNullPointerException
- if the list is null- See Also:
penultimate(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 itemNullPointerException
- if the list is null
-
lastIfPresent
public static <T> Optional<T> lastIfPresent(List<T> items)
Returns anOptional
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 listnumber
- 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 itemsNullPointerException
- 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.
-
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 liststartOffset
- 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:
List.subList(int, int)
-
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:
List.subList(int, int)
-
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. UsesubListFromIndex(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 listnumber
- 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 nullIllegalArgumentException
- if the given number is negative or is higher than the size of the list- See Also:
List.subList(int, int)
-
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 listindex
- 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 nullIllegalArgumentException
- if the given index is negative or is higher than the last index in the list- See Also:
List.subList(int, int)
-
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 listnumber
- 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:
List.subList(int, int)
-
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 listnumber
- 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:
List.subList(int, int)
-
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 listminSize
- the minimum required size- Throws:
NullPointerException
- if the list is nullIllegalArgumentException
- 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 unmodifiableList
with the given items shuffled usingCollections.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 newArrayList
with the given items shuffled usingCollections.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
-
-