Package org.kiwiproject.collect
Class KiwiArrays
- java.lang.Object
-
- org.kiwiproject.collect.KiwiArrays
-
public class KiwiArrays extends Object
Utility methods for working with Array instances.
-
-
Constructor Summary
Constructors Constructor Description KiwiArrays()
-
Method Summary
All Methods Static Methods Concrete Methods 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 a array of the collection elements with duplicates stripped out.static <T> T[]
distinctOrNull(T[] collection, Class<T> arrayType)
Returns a 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 anOptional
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 anOptional
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" - 1static <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 forpenultimate(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 providedComparator
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.
-
-
-
Method Detail
-
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 arrayarrayType
- the type of the items in the array. Needed to ensure the new array is notObject[]
- 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 providedComparator
returning a new array.- Type Parameters:
T
- the type of items in the array- Parameters:
items
- the arraycomparator
- a Comparator to be used to compare stream elementsarrayType
- the type of the items in the array. Needed to ensure the new array is notObject[]
- 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 itemNullPointerException
- if the array is null
-
firstIfPresent
public static <T> Optional<T> firstIfPresent(T[] items)
Returns anOptional
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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- 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 itemsNullPointerException
- if the array is null- See Also:
secondToLast(Object[])
-
secondToLast
public static <T> T secondToLast(T[] items)
Synonym forpenultimate(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 itemsNullPointerException
- if the array is null- See Also:
penultimate(Object[])
-
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 itemNullPointerException
- if the array is null
-
lastIfPresent
public static <T> Optional<T> lastIfPresent(T[] items)
Returns anOptional
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 arraynumber
- 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 itemsNullPointerException
- if the array is null
-
distinct
public static <T> T[] distinct(T[] collection, Class<T> arrayType)
Returns a array of the collection elements with duplicates stripped out.- Type Parameters:
T
- the type of items in the collection- Parameters:
collection
- the collection of valuesarrayType
- the type of the items in the array. Needed to ensure the new array is notObject[]
- 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 a 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 valuesarrayType
- the type of the items in the array. Needed to ensure the new array is notObject[]
- 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 arraystartOffset
- the desired offset to start the new arrayarrayType
- the type of the items in the array. Needed to ensure the new array is notObject[]
- 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. UsesubArrayFromIndex(Object[], int)
if you want to use zero-based list indices.- Type Parameters:
T
- the type of items in the array- Parameters:
items
- the arraynumber
- 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 nullIllegalArgumentException
- 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 arrayindex
- 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 nullIllegalArgumentException
- 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 arraynumber
- 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 arraynumber
- 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 arrayminSize
- the minimum required size- Throws:
NullPointerException
- if the array is nullIllegalArgumentException
- 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
-
-