-
Method Summary
Modifier and TypeMethodDescriptionstatic int
clamp
(int value, org.klojang.check.relation.IntRelation relation, int replacement) Retains a value if it has a certain relation to another value, else replaces it with that value.static <T> T
clamp
(T value, org.klojang.check.relation.Relation<T, T> relation, T replacement) Replaces a value with another value if it has a certain relation to that value.static <T> T
e2n
(T arg) Empty-to-null: returnsnull
if the argument is empty (as perisEmpty(Object)
), else the argument itself.static boolean
e2nDeepEquals
(Object arg0, Object arg1) Recursively tests the arguments for equality using empty-equals-null semantics.static boolean
Tests the provided arguments for equality using empty-equals-null semantics.static int
Generates a hash code for the provided arguments using empty-equals-null semantics.static int
e2nHashCode
(Object obj) Generates a hash code for the provided object using empty-equals-null semantics.static int
e2nTypedHashCode
(Object obj) Generates a hash code for the provided object using empty-equals-null semantics.static <T,
R> R hardCast
(T input) Does a brute-force cast of one type to another.static <T,
E extends Exception>
TifEmpty
(T value, org.klojang.check.fallible.FallibleSupplier<? extends T, E> supplier) Returns the first argument if it is not empty (as perisEmpty(Object)
), else the value produced by the specifiedSupplier
(which may be empty as well).static <T> T
ifEmpty
(T value, T defVal) Returns the first argument if it is not empty (as perisEmpty(Object)
), else the second argument.static <T,
U> U ifNotEmpty
(T arg, Function<T, U> then) Returns the result of passing the specified argument to the specifiedFunction
if the argument is notempty
, else returns null.static <T,
U> U ifNotEmpty
(T arg, Function<T, U> then, U dfault) Returns the result of passing the specified argument to the specifiedFunction
if the argument is notempty
, else a default value.static <T,
U> U Returns the result of passing the specified argument to the specifiedFunction
if the argument is notnull
, else returnsnull
.static <T,
U> U Returns the result of passing the specified argument to the specifiedFunction
if the argument is not null, else a default value.static <T,
E extends Exception>
TifNull
(T value, org.klojang.check.fallible.FallibleSupplier<? extends T, E> supplier) Returns the first argument if it is notnull
, else the value produced by the specifiedSupplier
.static <T> T
ifNull
(T value, T defVal) Returns the first argument if it is not null, else the second argument.static boolean
isDeepNotEmpty
(Object arg) Verifies that the argument is recursively non-empty.static boolean
isDeepNotEmpty
(Object[] arr) Verifies that the specified array is non-null, non-empty, and contains only deep-not-empty keys and values.static boolean
isDeepNotEmpty
(Collection<?> coll) Verifies that the specified collection is non-null, non-empty, and contains only deep-not-empty elements.static boolean
isDeepNotEmpty
(Map<?, ?> map) Verifies that the specified map is non-null, non-empty, and contains only deep-not-empty keys and values.static boolean
isDeepNotNull
(Object arg) Verifies that the argument is not null and, if it is array,Collection
orMap
, does not contain any null values.static boolean
isEmpty
(CharSequence arg) Returnstrue
if the specifiedCharSequence
is null or empty.static boolean
Returnstrue
if the specified argument is null or empty.static boolean
Returnstrue
if the specified array is null or empty.static boolean
isEmpty
(Collection<?> arg) Returnstrue
if the specifiedCollection
is null or empty.static boolean
Returns whether the specifiedMap
is null or empty.static boolean
Returnstrue
if the specifiedOptional
is empty or contains an empty object.static boolean
isEmpty
(org.klojang.check.aux.Emptyable arg) Returnstrue
if the specified array is null or empty.static Boolean
ReturnsBoolean.FALSE
if the argument is null, else the argument itself.static Byte
Returns zero if the argument is null, else the argument itself.static Character
Returns zero if the argument is null, else the argument itself.static Double
Returns zero if the argument is null, else the argument itself.static Float
Returns zero if the argument is null, else the argument itself.static Integer
Returns zero if the argument is null, else the argument itself.static Long
Returns zero if the argument is null, else the argument itself.static Short
Returns zero if the argument is null, else the argument itself.static String
Null-to-empty: returns an emptyString
if the argument is null, else the argument itself.static <T> List
<T> Null-to-empty: returnsCollections.emptyList()
if the argument is null, else the argument itself.static <K,
V> Map <K, V> Null-to-empty: returnsCollections.emptyMap()
if the argument is null, else the argument itself.static <T> Set
<T> Null-to-empty: returnsCollections.emptySet()
if the argument is null, else the argument itself.static <T> T
nullIf
(T value, T... forbiddenValues) Returnsnull
if the first argument is among the forbidden values, else the first argument itself.static <T> T
nullUnless
(T value, T... allowedValues) Returns this first argument if it is among the allowed values, elsenull
.static int
replaceIf
(int value, IntPredicate criterion, int replacement) Replaces a value with another value if it satisfies a certain criterion.static int
replaceIf
(int value, org.klojang.check.relation.IntRelation relation, int compareTo, int replacement) Replaces a value with another value if it has a certain relation to yet another value.static <T> T
Replaces a value with another value if it satisfies a certain criterion.static <T> T
replaceIf
(T value, org.klojang.check.relation.Relation<T, T> relation, T compareTo, T replacement) Replaces a value with another value if it has a certain relation to yet another value.static String
Returns an empty string if the argument isnull
, else the result of callingtoString()
on the argument.
-
Method Details
-
hardCast
public static <T,R> R hardCast(T input) Does a brute-force cast of one type to another. This method may come in handy, especially in the form of a method reference, when bumping up against the limits of Java's implementation of generics:List<CharSequence> list1 = List.of("Hello", "world"); // WON'T COMPILE: List<String> list2 = list1; List<String> list2 = bruteCast(list1);
Handle with care, though, as it will just as easily brute-force its way to a
ClassCastException
at runtime:String s = bruteCast(new File("/tmp/foo.txt")); // compiles
- Type Parameters:
T
- the input typeR
- The output type- Parameters:
input
- The value to be cast- Returns:
- the cast value
-
stringify
Returns an empty string if the argument isnull
, else the result of callingtoString()
on the argument. Equivalent toObjects.toString(obj, "")
, but more usable as method reference.- Parameters:
obj
- the object to stringify- Returns:
- an empty string if the argument is
null
, else the result of callingtoString()
on the argument
-
isEmpty
Returnstrue
if the specifiedCharSequence
is null or empty.- Parameters:
arg
- theCharSequence
to check- Returns:
- whether it is null or empty
-
isEmpty
Returnstrue
if the specified array is null or empty.- Parameters:
arg
- the array to check- Returns:
- whether it is null or empty
-
isEmpty
Returnstrue
if the specifiedCollection
is null or empty.- Parameters:
arg
- theCollection
to check- Returns:
- whether it is null or empty
-
isEmpty
Returns whether the specifiedMap
is null or empty.- Parameters:
arg
- theMap
to check- Returns:
- whether it is null or empty
-
isEmpty
Returnstrue
if the specifiedOptional
is empty or contains an empty object. This is the onlyisEmpty
method that will throw anIllegalArgumentException
if the argument is null asOptional
objects should never be null.- Parameters:
arg
- theOptional
to check- Returns:
- whether it is empty or contains an empty object
-
isEmpty
public static boolean isEmpty(org.klojang.check.aux.Emptyable arg) Returnstrue
if the specified array is null or empty.- Parameters:
arg
- the array to check- Returns:
- whether it is null or empty
-
isEmpty
Returnstrue
if the specified argument is null or empty. More precisely, this method returnstrue
if any of the following applies:arg
isnull
arg
is an emptyCharSequence
arg
is an emptyCollection
arg
is an emptyMap
arg
is an emptyEmptyable
arg
is a zero-length arrayarg
is an emptyOptional
or anOptional
containing an empty value
In any other case this method returns
false
.- Parameters:
arg
- the argument to check- Returns:
- whether it is null or empty
-
isDeepNotEmpty
Verifies that the argument is recursively non-empty. More precisely, this method returnstrue
if the argument is any of the following:- a non-empty
CharSequence
- a non-empty
Collection
containing only deep-not-empty elements - a non-empty
Map
containing only deep-not-empty keys and values - a deep-not-empty
Emptyable
- a non-zero-length
Object[]
containing only deep-not-empty elements - a non-zero-length array of primitives
- a non-empty
Optional
containing a deep-not-empty value - a non-null object of any other type
- Parameters:
arg
- The object to be tested- Returns:
- whether it is recursively non-empty
- See Also:
- a non-empty
-
isDeepNotEmpty
Verifies that the specified collection is non-null, non-empty, and contains only deep-not-empty elements.- Parameters:
coll
- the collection to test- Returns:
- whether it is recursively non-empty
-
isDeepNotEmpty
Verifies that the specified map is non-null, non-empty, and contains only deep-not-empty keys and values.- Parameters:
map
- the map to test- Returns:
- whether it is recursively non-empty
-
isDeepNotEmpty
Verifies that the specified array is non-null, non-empty, and contains only deep-not-empty keys and values.- Parameters:
arr
- the array to test- Returns:
- whether it is recursively non-empty
-
isDeepNotNull
Verifies that the argument is not null and, if it is array,Collection
orMap
, does not contain any null values. It may still be an empty array,Collection
orMap
, however. For maps, both keys and values are tested fornull
.- Parameters:
arg
- the object to be tested- Returns:
- whether it is not null and does not contain any null values
-
e2nEquals
Tests the provided arguments for equality using empty-equals-null semantics. This is roughly equivalent toObjects.equals(e2n(arg0), e2n(arg1))
, except thate2nEquals
does take the types of the two arguments into account. So an emptyString
is not equal to an emptyArrayList
and an emptyArrayList
is not equal to an emptyHashSet
. (An emptyHashSet
is equal to an emptyTreeSet
, but that is just behaviour specified by the Collections Framework.)null
equals an emptyCharSequence
null
equals an emptyCollection
null
equals an emptyMap
null
equals an empty arraynull
equals an emptyOptional
or anOptional
containing an empty object- A empty instance of one type is not equal to a empty instance of another non-comparable type
- Parameters:
arg0
- The 1st of the pair of objects to comparearg1
- The 2nd of the pair of objects to compare- Returns:
- whether the provided arguments are equal using empty-equals-null semantics
-
e2nDeepEquals
Recursively tests the arguments for equality using empty-equals-null semantics.- Parameters:
arg0
- The 1st of the pair of objects to comparearg1
- The 2nd of the pair of objects to compare- Returns:
- whether the provided arguments are deeply equal using empty-equals-null semantics
-
e2nHashCode
Generates a hash code for the provided object using empty-equals-null semantics. Empty objects (whatever their type and includingnull
) all have the same hash code: 0 (zero)! If the argument is any array, this method is recursively applied to the array's elements. Thereforee2nHashCode
in effect generates a "deep" hash code.- Parameters:
obj
- The object to generate a hash code for- Returns:
- the hash code
-
e2nTypedHashCode
Generates a hash code for the provided object using empty-equals-null semantics. This variant of
hashCode()
includes the type of the argument in the computation of the hash code. As withe2nEquals(Object, Object)
, this ensures that an emptyString
will not have the same hash code as an emptyArrayList
, and an emptyArrayList
will not have the same hash code as an emptyHashSet
. An emptyHashSet
will have the same hash code as an emptyTreeSet
, because for Collection Framework classes it is hash code of the base type that is included in the computation of the hash code (i.e.List.class
,Set.class
andMap.class
).Thus, using
e2nTypedHashCode
will lead to fewer hash collisions thane2nHashcode
. However, it may, in some circumstances break the contract forObject.hashCode()
. A class could define anequals
method that allows instances of it to be equal to instances of its superclass. However,e2nTypedHashCode
precludes this as the hash code for the class and the superclass will be different.Also note that this anyhow only becomes relevant if the collection of objects you work with is remarkably heterogeneous: strings, empty strings, sets, empty sets, empty lists, empty arrays, etc.
- Parameters:
obj
- The object to generate a hash code for- Returns:
- the hash code
-
e2nHash
Generates a hash code for the provided arguments using empty-equals-null semantics. SeeObject.hashCode()
.- Parameters:
objs
- The objects to generate a hash code for- Returns:
- the hash code
-
ifNull
public static <T> T ifNull(T value, T defVal) Returns the first argument if it is not null, else the second argument.- Parameters:
value
- The value to return if not nulldefVal
- The value to return if the first argument isnull
- Returns:
- A non-null value
-
ifNull
public static <T,E extends Exception> T ifNull(T value, org.klojang.check.fallible.FallibleSupplier<? extends T, E> supplier) throws EReturns the first argument if it is notnull
, else the value produced by the specifiedSupplier
.- Type Parameters:
T
- the type of the arguments and the return valueE
- The type of the exception that can potentially be thrown by theSupplier
- Parameters:
value
- The value to return if it is notnull
supplier
- The supplier of a default value- Returns:
- a non-null value
- Throws:
E
-
ifEmpty
public static <T> T ifEmpty(T value, T defVal) Returns the first argument if it is not empty (as perisEmpty(Object)
), else the second argument.- Type Parameters:
T
- the type of the arguments and the return value- Parameters:
value
- The value to return if it is not emptydefVal
- The value to return if the first argument is empty- Returns:
- a non-empty value
-
ifEmpty
public static <T,E extends Exception> T ifEmpty(T value, org.klojang.check.fallible.FallibleSupplier<? extends T, E> supplier) throws EReturns the first argument if it is not empty (as perisEmpty(Object)
), else the value produced by the specifiedSupplier
(which may be empty as well).- Type Parameters:
T
- the input and return typeE
- The exception potentially being thrown by the supplier as it- Parameters:
value
- The value to return if not emptysupplier
- The supplier of a default value ifvalue
is null- Returns:
- a non-empty value
- Throws:
E
-
nullUnless
public static <T> T nullUnless(T value, T... allowedValues) Returns this first argument if it is among the allowed values, elsenull
.- Type Parameters:
T
- the type of the involved values- Parameters:
value
- The value to testallowedValues
- The values it is allowed to have- Returns:
- the first argument or
null
-
nullIf
public static <T> T nullIf(T value, T... forbiddenValues) Returnsnull
if the first argument is among the forbidden values, else the first argument itself.- Type Parameters:
T
- the type of the involved values- Parameters:
value
- The value to testforbiddenValues
- The values it must not have- Returns:
- the first argument or
null
-
ifNotNull
Returns the result of passing the specified argument to the specifiedFunction
if the argument is notnull
, else returnsnull
. For example:String[] strs = ifNotNull("Hello World", s -> s.split(" "));
- Type Parameters:
T
- the type of the first argumentU
- The return type- Parameters:
arg
- the value to testthen
- The transformation to apply to the value if it is not null- Returns:
value
or null
-
ifNotNull
Returns the result of passing the specified argument to the specifiedFunction
if the argument is not null, else a default value. For example:String[] strs = ifNotNull("Hello World", s -> s.split(" "), new String[0]);
- Type Parameters:
T
- the type of the first value to transformU
- The return type- Parameters:
arg
- the value to transformthen
- The transformation to apply to the value if it is not nulldfault
- A default value to return if the argument is null- Returns:
- the result produced by the
Function
or by theSupplier
-
ifNotEmpty
Returns the result of passing the specified argument to the specifiedFunction
if the argument is notempty
, else returns null.- Type Parameters:
T
- the type of the value to transformU
- The return type- Parameters:
arg
- the value to transformthen
- The function to apply to the value if it is not null- Returns:
- the result produced by the
Function
or a default value
-
ifNotEmpty
Returns the result of passing the specified argument to the specifiedFunction
if the argument is notempty
, else a default value.- Type Parameters:
T
- the type of the value to transformU
- The return type- Parameters:
arg
- the value to transformthen
- The function to apply to the value if it is not nulldfault
- A default value to return if the argument is empty- Returns:
- the result produced by the
Function
or a default value
-
replaceIf
Replaces a value with another value if it satisfies a certain criterion. Note that theCommonChecks
class defines various predicates that might be of use.- Type Parameters:
T
- the type of the values- Parameters:
value
- the value to test and possibly returncriterion
- the criterion determining which value to returnreplacement
- the replacement value- Returns:
- the value determined by the criterion
-
clamp
public static <T> T clamp(T value, org.klojang.check.relation.Relation<T, T> relation, T replacement) Replaces a value with another value if it has a certain relation to that value. Note that theCommonChecks
class defines various relations that might be of use. This method can be used to apply some sort of clamping. For example:// import static nl.naturalis.check.CommonChecks.GT; // Prevent dates from lying in the future: LocalDate myLocalDate = replaceIf(someLocalDate, GT(), LocalDate.now());
- Type Parameters:
T
- the type of the values- Parameters:
value
- the value to test and possibly returnrelation
- the relation that needs to exist between the value and the replacement value in order for the replacement value to be returnedreplacement
- the replacement value- Returns:
- the value determined by the relation by the two values
-
replaceIf
public static <T> T replaceIf(T value, org.klojang.check.relation.Relation<T, T> relation, T compareTo, T replacement) Replaces a value with another value if it has a certain relation to yet another value. Note that theCommonChecks
class defines various relations that might be of use. For example:// import static nl.naturalis.check.CommonChecks.EQ; // Replace green with blue: Color color = replaceIf(someColor, EQ(), Color.GREEN, Color.BLUE);
- Type Parameters:
T
- the type of the values- Parameters:
value
- the value to test and possibly returnrelation
- the relation that needs to exist between the value and the compare-to value in order for the replacement value to be returnedcompareTo
- the compare-to valuereplacement
- the value returned if the specified relation is found to exist between the value and the compare-to value- Returns:
- the value determined by the relation by the two values
-
replaceIf
Replaces a value with another value if it satisfies a certain criterion. Note that theCommonChecks
class defines various predicates that might be of use.- Parameters:
value
- the value to test and possibly returncriterion
- the criterion determining which value to returnreplacement
- the replacement value- Returns:
- the value determined by the criterion
-
clamp
public static int clamp(int value, org.klojang.check.relation.IntRelation relation, int replacement) Retains a value if it has a certain relation to another value, else replaces it with that value. Note that theCommonChecks
class defines various relations that might be of use. This method can be used to apply some sort of clamping. For example:// import static nl.naturalis.check.CommonChecks.gt; // Prevent dates from lying in the future: int speed = replaceIf(someSpeed, gt(), 65);
- Parameters:
value
- the value to test and possibly returnrelation
- the relation that needs to exist between the value and the replacement value in order for the replacement value to be returnedreplacement
- the replacement value- Returns:
- the value determined by the relation by the two values
-
replaceIf
public static int replaceIf(int value, org.klojang.check.relation.IntRelation relation, int compareTo, int replacement) Replaces a value with another value if it has a certain relation to yet another value. Note that theCommonChecks
class defines various relations that might be of use.- Parameters:
value
- the value to test and possibly returnrelation
- the relation that needs to exist between the value and the compare-to value in order for the replacement value to be returnedcompareTo
- the compare-to valuereplacement
- the value returned if the specified relation is found to exist between the value and the compare-to value- Returns:
- the value determined by the relation by the two values
-
e2n
public static <T> T e2n(T arg) Empty-to-null: returnsnull
if the argument is empty (as perisEmpty(Object)
), else the argument itself.- Type Parameters:
T
- the type of the argument- Parameters:
arg
- the argument- Returns:
- the argument itself if not empty, else
null
-
n2e
Null-to-empty: returns an emptyString
if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeString
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Null-to-empty: returnsCollections.emptyList()
if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeList
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Null-to-empty: returnsCollections.emptySet()
if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeList
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Null-to-empty: returnsCollections.emptyMap()
if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeList
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeInteger
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeDouble
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeLong
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeFloat
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeShort
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeByte
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
Returns zero if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeByte
- Returns:
- the argument or the default value of the corresponding primitive type
-
n2e
ReturnsBoolean.FALSE
if the argument is null, else the argument itself.- Parameters:
arg
- an argument of typeByte
- Returns:
- the argument or the default value of the corresponding primitive type
-