Class ObjectMethods

java.lang.Object
org.klojang.util.ObjectMethods

public class ObjectMethods extends Object
General methods applicable to objects of any type.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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: returns null if the argument is empty (as per isEmpty(Object)), else the argument itself.
    static boolean
    Recursively tests the arguments for equality using empty-equals-null semantics.
    static boolean
    e2nEquals(Object arg0, Object arg1)
    Tests the provided arguments for equality using empty-equals-null semantics.
    static int
    e2nHash(Object... objs)
    Generates a hash code for the provided arguments using empty-equals-null semantics.
    static int
    Generates a hash code for the provided object using empty-equals-null semantics.
    static int
    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>
    T
    ifEmpty(T value, org.klojang.check.fallible.FallibleSupplier<? extends T,E> supplier)
    Returns the first argument if it is not empty (as per isEmpty(Object)), else the value produced by the specified Supplier (which may be empty as well).
    static <T> T
    ifEmpty(T value, T defVal)
    Returns the first argument if it is not empty (as per isEmpty(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 specified Function if the argument is not empty, 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 specified Function if the argument is not empty, else a default value.
    static <T, U> U
    ifNotNull(T arg, Function<T,U> then)
    Returns the result of passing the specified argument to the specified Function if the argument is not null, else returns null.
    static <T, U> U
    ifNotNull(T arg, Function<T,U> then, U dfault)
    Returns the result of passing the specified argument to the specified Function if the argument is not null, else a default value.
    static <T, E extends Exception>
    T
    ifNull(T value, org.klojang.check.fallible.FallibleSupplier<? extends T,E> supplier)
    Returns the first argument if it is not null, else the value produced by the specified Supplier.
    static <T> T
    ifNull(T value, T defVal)
    Returns the first argument if it is not null, else the second argument.
    static boolean
    Verifies that the argument is recursively non-empty.
    static boolean
    Verifies that the specified array is non-null, non-empty, and contains only deep-not-empty keys and values.
    static boolean
    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
    Verifies that the argument is not null and, if it is array, Collection or Map, does not contain any null values.
    static boolean
    Returns true if the specified CharSequence is null or empty.
    static boolean
    Returns true if the specified argument is null or empty.
    static boolean
    isEmpty(Object[] arg)
    Returns true if the specified array is null or empty.
    static boolean
    Returns true if the specified Collection is null or empty.
    static boolean
    isEmpty(Map<?,?> arg)
    Returns whether the specified Map is null or empty.
    static boolean
    isEmpty(Optional<?> arg)
    Returns true if the specified Optional is empty or contains an empty object.
    static boolean
    isEmpty(org.klojang.check.aux.Emptyable arg)
    Returns true if the specified array is null or empty.
    static Boolean
    n2e(Boolean arg)
    Returns Boolean.FALSE if the argument is null, else the argument itself.
    static Byte
    n2e(Byte arg)
    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
    n2e(Double arg)
    Returns zero if the argument is null, else the argument itself.
    static Float
    n2e(Float arg)
    Returns zero if the argument is null, else the argument itself.
    static Integer
    n2e(Integer arg)
    Returns zero if the argument is null, else the argument itself.
    static Long
    n2e(Long arg)
    Returns zero if the argument is null, else the argument itself.
    static Short
    n2e(Short arg)
    Returns zero if the argument is null, else the argument itself.
    static String
    n2e(String arg)
    Null-to-empty: returns an empty String if the argument is null, else the argument itself.
    static <T> List<T>
    n2e(List<T> arg)
    Null-to-empty: returns Collections.emptyList() if the argument is null, else the argument itself.
    static <K, V> Map<K,V>
    n2e(Map<K,V> arg)
    Null-to-empty: returns Collections.emptyMap() if the argument is null, else the argument itself.
    static <T> Set<T>
    n2e(Set<T> arg)
    Null-to-empty: returns Collections.emptySet() if the argument is null, else the argument itself.
    static <T> T
    nullIf(T value, T... forbiddenValues)
    Returns null 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, else null.
    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
    replaceIf(T value, Predicate<? super T> criterion, T replacement)
    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 is null, else the result of calling toString() on the argument.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • 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 type
      R - The output type
      Parameters:
      input - The value to be cast
      Returns:
      the cast value
    • stringify

      public static String stringify(Object obj)
      Returns an empty string if the argument is null, else the result of calling toString() on the argument. Equivalent to Objects.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 calling toString() on the argument
    • isEmpty

      public static boolean isEmpty(CharSequence arg)
      Returns true if the specified CharSequence is null or empty.
      Parameters:
      arg - the CharSequence to check
      Returns:
      whether it is null or empty
    • isEmpty

      public static boolean isEmpty(Object[] arg)
      Returns true if the specified array is null or empty.
      Parameters:
      arg - the array to check
      Returns:
      whether it is null or empty
    • isEmpty

      public static boolean isEmpty(Collection<?> arg)
      Returns true if the specified Collection is null or empty.
      Parameters:
      arg - the Collection to check
      Returns:
      whether it is null or empty
    • isEmpty

      public static boolean isEmpty(Map<?,?> arg)
      Returns whether the specified Map is null or empty.
      Parameters:
      arg - the Map to check
      Returns:
      whether it is null or empty
    • isEmpty

      public static boolean isEmpty(Optional<?> arg)
      Returns true if the specified Optional is empty or contains an empty object. This is the only isEmpty method that will throw an IllegalArgumentException if the argument is null as Optional objects should never be null.
      Parameters:
      arg - the Optional to check
      Returns:
      whether it is empty or contains an empty object
    • isEmpty

      public static boolean isEmpty(org.klojang.check.aux.Emptyable arg)
      Returns true if the specified array is null or empty.
      Parameters:
      arg - the array to check
      Returns:
      whether it is null or empty
    • isEmpty

      public static boolean isEmpty(Object arg)
      Returns true if the specified argument is null or empty. More precisely, this method returns true if any of the following applies:
      • arg is null
      • arg is an empty CharSequence
      • arg is an empty Collection
      • arg is an empty Map
      • arg is an empty Emptyable
      • arg is a zero-length array
      • arg is an empty Optional or an Optional 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

      public static boolean isDeepNotEmpty(Object arg)
      Verifies that the argument is recursively non-empty. More precisely, this method returns true 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:
      • CommonChecks.deepNotEmpty()
    • isDeepNotEmpty

      public static boolean isDeepNotEmpty(Collection<?> coll)
      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

      public static boolean isDeepNotEmpty(Map<?,?> map)
      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

      public static boolean isDeepNotEmpty(Object[] arr)
      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

      public static boolean isDeepNotNull(Object arg)
      Verifies that the argument is not null and, if it is array, Collection or Map, does not contain any null values. It may still be an empty array, Collection or Map, however. For maps, both keys and values are tested for null.
      Parameters:
      arg - the object to be tested
      Returns:
      whether it is not null and does not contain any null values
    • e2nEquals

      public static boolean e2nEquals(Object arg0, Object arg1)
      Tests the provided arguments for equality using empty-equals-null semantics. This is roughly equivalent to Objects.equals(e2n(arg0), e2n(arg1)), except that e2nEquals does take the types of the two arguments into account. So an empty String is not equal to an empty ArrayList and an empty ArrayList is not equal to an empty HashSet. (An empty HashSet is equal to an empty TreeSet, but that is just behaviour specified by the Collections Framework.)

      1. null equals an empty CharSequence
      2. null equals an empty Collection
      3. null equals an empty Map
      4. null equals an empty array
      5. null equals an empty Optional or an Optional containing an empty object
      6. 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 compare
      arg1 - The 2nd of the pair of objects to compare
      Returns:
      whether the provided arguments are equal using empty-equals-null semantics
    • e2nDeepEquals

      public static boolean e2nDeepEquals(Object arg0, Object arg1)
      Recursively tests the arguments for equality using empty-equals-null semantics.
      Parameters:
      arg0 - The 1st of the pair of objects to compare
      arg1 - The 2nd of the pair of objects to compare
      Returns:
      whether the provided arguments are deeply equal using empty-equals-null semantics
    • e2nHashCode

      public static int e2nHashCode(Object obj)
      Generates a hash code for the provided object using empty-equals-null semantics. Empty objects (whatever their type and including null) all have the same hash code: 0 (zero)! If the argument is any array, this method is recursively applied to the array's elements. Therefore e2nHashCode in effect generates a "deep" hash code.
      Parameters:
      obj - The object to generate a hash code for
      Returns:
      the hash code
    • e2nTypedHashCode

      public static int e2nTypedHashCode(Object obj)

      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 with e2nEquals(Object, Object), this ensures that an empty String will not have the same hash code as an empty ArrayList, and an empty ArrayList will not have the same hash code as an empty HashSet. An empty HashSet will have the same hash code as an empty TreeSet, 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 and Map.class).

      Thus, using e2nTypedHashCode will lead to fewer hash collisions than e2nHashcode. However, it may, in some circumstances break the contract for Object.hashCode(). A class could define an equals 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

      public static int e2nHash(Object... objs)
      Generates a hash code for the provided arguments using empty-equals-null semantics. See Object.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 null
      defVal - The value to return if the first argument is null
      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 E
      Returns the first argument if it is not null, else the value produced by the specified Supplier.
      Type Parameters:
      T - the type of the arguments and the return value
      E - The type of the exception that can potentially be thrown by the Supplier
      Parameters:
      value - The value to return if it is not null
      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 per isEmpty(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 empty
      defVal - 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 E
      Returns the first argument if it is not empty (as per isEmpty(Object)), else the value produced by the specified Supplier (which may be empty as well).
      Type Parameters:
      T - the input and return type
      E - The exception potentially being thrown by the supplier as it
      Parameters:
      value - The value to return if not empty
      supplier - The supplier of a default value if value 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, else null.
      Type Parameters:
      T - the type of the involved values
      Parameters:
      value - The value to test
      allowedValues - The values it is allowed to have
      Returns:
      the first argument or null
    • nullIf

      public static <T> T nullIf(T value, T... forbiddenValues)
      Returns null 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 test
      forbiddenValues - The values it must not have
      Returns:
      the first argument or null
    • ifNotNull

      public static <T, U> U ifNotNull(T arg, Function<T,U> then)
      Returns the result of passing the specified argument to the specified Function if the argument is not null, else returns null. For example:
       String[] strs = ifNotNull("Hello World", s -> s.split(" "));
       
      Type Parameters:
      T - the type of the first argument
      U - The return type
      Parameters:
      arg - the value to test
      then - The transformation to apply to the value if it is not null
      Returns:
      value or null
    • ifNotNull

      public static <T, U> U ifNotNull(T arg, Function<T,U> then, U dfault)
      Returns the result of passing the specified argument to the specified Function 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 transform
      U - The return type
      Parameters:
      arg - the value to transform
      then - The transformation to apply to the value if it is not null
      dfault - A default value to return if the argument is null
      Returns:
      the result produced by the Function or by the Supplier
    • ifNotEmpty

      public static <T, U> U ifNotEmpty(T arg, Function<T,U> then)
      Returns the result of passing the specified argument to the specified Function if the argument is not empty, else returns null.
      Type Parameters:
      T - the type of the value to transform
      U - The return type
      Parameters:
      arg - the value to transform
      then - The function to apply to the value if it is not null
      Returns:
      the result produced by the Function or a default value
    • ifNotEmpty

      public static <T, U> U ifNotEmpty(T arg, Function<T,U> then, U dfault)
      Returns the result of passing the specified argument to the specified Function if the argument is not empty, else a default value.
      Type Parameters:
      T - the type of the value to transform
      U - The return type
      Parameters:
      arg - the value to transform
      then - The function to apply to the value if it is not null
      dfault - A default value to return if the argument is empty
      Returns:
      the result produced by the Function or a default value
    • replaceIf

      public static <T> T replaceIf(T value, Predicate<? super T> criterion, T replacement)
      Replaces a value with another value if it satisfies a certain criterion. Note that the CommonChecks 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 return
      criterion - the criterion determining which value to return
      replacement - 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 the CommonChecks 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 return
      relation - the relation that needs to exist between the value and the replacement value in order for the replacement value to be returned
      replacement - 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 the CommonChecks 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 return
      relation - the relation that needs to exist between the value and the compare-to value in order for the replacement value to be returned
      compareTo - the compare-to value
      replacement - 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

      public static int replaceIf(int value, IntPredicate criterion, int replacement)
      Replaces a value with another value if it satisfies a certain criterion. Note that the CommonChecks class defines various predicates that might be of use.
      Parameters:
      value - the value to test and possibly return
      criterion - the criterion determining which value to return
      replacement - 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 the CommonChecks 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 return
      relation - the relation that needs to exist between the value and the replacement value in order for the replacement value to be returned
      replacement - 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 the CommonChecks class defines various relations that might be of use.
      Parameters:
      value - the value to test and possibly return
      relation - the relation that needs to exist between the value and the compare-to value in order for the replacement value to be returned
      compareTo - the compare-to value
      replacement - 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: returns null if the argument is empty (as per isEmpty(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

      public static String n2e(String arg)
      Null-to-empty: returns an empty String if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type String
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static <T> List<T> n2e(List<T> arg)
      Null-to-empty: returns Collections.emptyList() if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type List
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static <T> Set<T> n2e(Set<T> arg)
      Null-to-empty: returns Collections.emptySet() if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type List
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static <K, V> Map<K,V> n2e(Map<K,V> arg)
      Null-to-empty: returns Collections.emptyMap() if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type List
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Integer n2e(Integer arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Integer
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Double n2e(Double arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Double
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Long n2e(Long arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Long
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Float n2e(Float arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Float
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Short n2e(Short arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Short
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Byte n2e(Byte arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Byte
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Character n2e(Character arg)
      Returns zero if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Byte
      Returns:
      the argument or the default value of the corresponding primitive type
    • n2e

      public static Boolean n2e(Boolean arg)
      Returns Boolean.FALSE if the argument is null, else the argument itself.
      Parameters:
      arg - an argument of type Byte
      Returns:
      the argument or the default value of the corresponding primitive type