Module org.tquadrat.foundation.base
Package org.tquadrat.foundation.lang

Class Objects

java.lang.Object
org.tquadrat.foundation.lang.Objects
@UtilityClass @ClassVersion(sourceVersion="$Id: Objects.java 1137 2024-05-31 00:14:04Z tquadrat $") @API(status=STABLE, since="0.0.1") public final class Objects extends Object

This class consists of several utility methods working on Object instances, similar to those on Arrays or Collections.

The class was originally inspired by the class of the same name that was finally introduced with the Java 7 release; some of its methods will delegate to java.util.Objects, others will extend the functionality of the methods with the same name from java.util.Objects.

If a method from java.util.Objects would throw a NullPointerException, the method with the same name from this class would throw a ValidationException instead.

Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: Objects.java 1137 2024-05-31 00:14:04Z tquadrat $
Since:
0.0.1
UML Diagram
UML Diagram for "org.tquadrat.foundation.lang.Objects"⁠

UML Diagram for "org.tquadrat.foundation.lang.Objects"

UML Diagram for "org.tquadrat.foundation.lang.Objects"⁠

  • Constructor Details

    • Objects

      private Objects()
      No instance allowed for this class.

  • Method Details

    • checkFromIndexSize

      @API(status=STABLE, since="0.0.5") public static final int checkFromIndexSize(int fromIndex, int size, int length)

      Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

      The sub-range is defined to be out-of-bounds if any of the following inequalities is true:

      • fromIndex < 0
      • size < 0
      • fromIndex + size > length, taking into account integer overflow
      • length < 0, which is implied from the former inequalities

      Calls java.util.Objects.checkFromIndexSize(int,int,int) internally.

      Parameters:
      fromIndex - The lower-bound (inclusive) of the sub-interval.
      size - The size of the sub-range.
      length - The upper-bound (exclusive) of the range.
      Returns:
      The fromIndex if the sub-range is within bounds of the range.
      Throws:
      IndexOutOfBoundsException - The sub-range is out-of-bounds.
      Since:
      0.0.5

    • checkFromToIndex

      @API(status=STABLE, since="0.0.5") public static final int checkFromToIndex(int fromIndex, int toIndex, int length)

      Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

      The sub-range is defined to be out-of-bounds if any of the following inequalities is true:

      • fromIndex < 0
      • fromIndex > toIndex
      • toIndex > length
      • length < 0, which is implied from the former inequalities

      Calls java.util.Objects.checkFromToIndex(int,int,int) internally.

      Parameters:
      fromIndex - The lower-bound (inclusive) of the sub-range.
      toIndex - The upper-bound (exclusive) of the sub-range.
      length - The upper-bound (exclusive) the range.
      Returns:
      The fromIndex if the sub-range is within bounds of the range.
      Throws:
      IndexOutOfBoundsException - The sub-range is out-of-bounds.
      Since:
      0.0.5

    • checkIndex

      @API(status=STABLE, since="0.0.5") public static final int checkIndex(int index, int length)

      Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

      The index is defined to be out-of-bounds if any of the following inequalities is true:

      • index < 0
      • index >= length
      • length < 0, which is implied from the former inequalities

      Calls java.util.Objects.checkIndex(int,int) internally.

      Parameters:
      index - The index.
      length - The upper-bound (exclusive) of the range.
      Returns:
      The index if it is within bounds of the range.
      Throws:
      IndexOutOfBoundsException - The index is out-of-bounds.
      Since:
      0.0.5

    • checkState

      public static final <E extends Exception> void checkState(boolean condition, Supplier<E> exception) throws E

      Throws the exception provided by the given supplier if the condition resolves to false.

      Basically, this method is a replacement for the code sequence below:

        …
  if( !<condition> )
  {
      throw new <WhatEver>Exception( <WhatEverMessage> );
  }
  …

      Code using this method may be easier to read than the if statement above:

        …
  checkState( <condition>, () -> new <WhatEver>Exception( <WhatEverMessage> ) );
  …
      Type Parameters:
      E - The type of the exception that is thrown in case the condition is not met.
      Parameters:
      condition - The condition to check.
      exception - The exception to throw.
      Throws:
      E - The condition was not met.

    • compare

      @API(status=STABLE, since="0.0.5") public static final <T> int compare(T object, T other, Comparator<? super T> comparator) throws NullArgumentException

      Returns 0 if the arguments are identical and comparator.compare(a, b) otherwise.

      Consequently, if both arguments are null, 0 is returned.

      Calls java.util.Objects#compare() internally, but different from that method, this implementation will throw a NullArgumentException in case the comparator is null.

      Type Parameters:
      T - The type of the objects being compared.
      Parameters:
      object - An object.
      other - Another object to be compared with the first object.
      comparator - The Comparator to compare the first two arguments.
      Returns:
      0 if the arguments are identical and +1, 0, or -1, based on the return value of c.compare(a, b) otherwise.
      Throws:
      NullArgumentException - The comparator is null.
      Since:
      0.0.5
      See Also:

    • deepEquals

      @API(status=STABLE, since="0.0.5") public static final boolean deepEquals(Object object, Object other)

      Returns true if the arguments are deeply equal to each other and false otherwise.

      Two null values are deeply equal. If both arguments are arrays, the algorithm in Arrays.deepEquals() is used to determine equality. Otherwise, equality is determined by using the equals() method of the first argument.

      Calls java.util.Objects#deepEquals() internally.

      Parameters:
      object - An object.
      other - Another object to be compared with the first object for deep equality.
      Returns:
      true if the arguments are deeply equal to each other and false otherwise.
      Since:
      0.0.5
      See Also:

    • equals

      @API(status=STABLE, since="0.0.5") public static final boolean equals(Object object, Object other)

      Returns true if the arguments are equal to each other and false otherwise.

      Consequently, if both arguments are null, true is returned and if exactly one argument is null, false is returned. Otherwise, equality is determined by using the equals() method of the first argument.

      Calls Objects.equals(Object, Object) internally.

      Parameters:
      object - An object.
      other - Another object to be compared with the first one for equality.
      Returns:
      true if the arguments are equal to each other and false otherwise.
      Since:
      0.0.5
      See Also:

    • hash

      @API(status=STABLE, since="0.0.5") public static final int hash(Object... values)

      Generates a hash code for a sequence of input values. The hash code is generated as if all the input values were placed into an array, and that array is hashed by calling Arrays.hashCode(Object[]).

      Calls java.util.Arrays.hashCode() internally.

      Parameters:
      values - The values to be hashed.
      Returns:
      A hash value of the sequence of input values.
      Since:
      0.0.5
      See Also:

    • hashCode

      @API(status=STABLE, since="0.0.5") public static final int hashCode(Object o)

      Returns the hash code of a non-null argument and 0 for a null argument.

      Calls java.util.Objects.hashCode(Object) internally.

      Parameters:
      o - An object.
      Returns:
      The hash code of an argument that is not null, and 0 for a null argument,
      Since:
      0.0.5
      See Also:

    • isNull

      @API(status=STABLE, since="0.0.5") public static final boolean isNull(Object obj)

      Returns true if the provided reference is null, otherwise returns false.

      This method can be used as a Predicate, filter(Objects::isNull).

      Calls java.util.Objects.isNull() internally.

      Parameters:
      obj - A reference to be checked against null.
      Returns:
      true if the provided reference is null, otherwise false
      Since:
      0.0.5
      See Also:

    • mapFromNull

      @API(status=STABLE, since="0.2.2") public static final <T> T mapFromNull(T value, Supplier<? extends T> supplier)

      Provides a replacement value if the given value is null.

      This is basically a shortcut to

      Optional.ofNullable( value ).orElseGet( supplier )
      Type Parameters:
      T - The type of the object to map.
      Parameters:
      value - The object to map; can be null (obviously).
      supplier - The supplier for the replacement function.
      Returns:
      The provided object if that is not null, or the result from the supplier method. Keep in mind that this result can be null!
      Since:
      0.2.2
      See Also:

    • mapFromNull

      @API(status=STABLE, since="0.4.2") public static final <T> T mapFromNull(T value, T replacement)

      Provides a replacement value if the given value is null.

      This is basically a shortcut to

      Optional.ofNullable( value ).orElse( replacement )
      Type Parameters:
      T - The type of the object to map.
      Parameters:
      value - The object to map; can be null.
      replacement - The replacement value; it may not be null.
      Returns:
      The provided object if that is not null, or the replacement value.
      Since:
      0.4.2
      See Also:

    • mapNonNull

      public static final <T, R> R mapNonNull(T o, Function<T,? extends R> mapper)

      Maps (converts) the given object instance by applying the provided mapper if the instance is not null.

      The mapper function will not be called at all if the given instance is null.

      Type Parameters:
      T - The type of the object to map.
      R - The type of the result.
      Parameters:
      o - The object to map; can be null.
      mapper - The mapping function.
      Returns:
      The result of the mapping, or null if the given object instance was already null. Keep in mind that the result of the mapping can be null!

    • mapNonNull

      public static final <T, R> R mapNonNull(T o, Function<T,? extends R> mapper, R defaultValue)

      Maps (converts) the given object instance by applying the provided mapper if the instance is not null or returns the given default value.

      The mapper function will not be called at all if the given instance is null.

      Type Parameters:
      T - The type of the object to map.
      R - The type of the result.
      Parameters:
      o - The object to map; can be null.
      mapper - The mapping function.
      defaultValue - The default value; can be null.
      Returns:
      The result of the mapping, or the default value if the given object instance is null. Keep in mind that the result of the mapping can be null!

    • nonNull

      @API(status=STABLE, since="0.0.5") public static final boolean nonNull(Object obj)

      Returns true if the provided reference is not null, otherwise returns false.

      This method exists to be used as a Predicate, filter(Objects::nonNull)

      Calls java.util.Objects.nonNull() internally.

      Parameters:
      obj - A reference to be checked against null
      Returns:
      false if the provided reference is null, otherwise true
      Since:
      0.0.5
      See Also:

    • require

      @API(status=STABLE, since="0.1.0") public static final <T> T require(T obj, Predicate<? super T> validation) throws ValidationException
      Applies the given validation on the given value, and if that fails, an ValidationException is thrown.
      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check; can be null.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - obj failed the validation.
      Since:
      0.1.0

    • require

      @API(status=STABLE, since="0.1.0") public static final <T> T require(T obj, String message, Predicate<? super T> validation) throws ValidationException, NullArgumentException, EmptyArgumentException
      Applies the given validation on the given value, and if that fails, an ValidationException with the specified message is thrown.
      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check; can be null.
      message - The message that is set to the thrown exception.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - obj failed the validation.
      NullArgumentException - message is null.
      EmptyArgumentException - message is the empty String.
      Since:
      0.1.0

    • require

      @API(status=STABLE, since="0.1.0") public static final <T> T require(T obj, Supplier<String> messageSupplier, Predicate<? super T> validation) throws ValidationException

      Applies the given validation on the given value, and if that fails, a customized ValidationException is thrown.

      Unlike the method require(Object,String,Predicate), this method allows to defer the creation of the message until after the validation was performed (and failed). While this may confer a performance advantage in the success case, some care should be taken that the costs for the creation of the message supplier are less than the cost of just creating the String message directly.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check; can be null.
      messageSupplier - The supplier of the detail message to be used in the event that ValidationException is thrown. If null or if it returns null, no detail message is provided to the exception.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      NullArgumentException - The validation is null.
      ValidationException - obk failed the validation.
      Since:
      0.1.0

    • require

      @API(status=STABLE, since="0.1.0") public static final <T> T require(T obj, Function<? super T,String> messageSupplier, Predicate<? super T> validation) throws ValidationException

      Applies the given validation on the given value, and if that fails, a customized ValidationException is thrown.

      Unlike the method require(Object,String,Predicate), this method allows to defer the creation of the message until after the validation was performed (and failed). While this may confer a performance advantage in the success case, some care should be taken that the costs the creation of the message supplier are less than the cost of just creating the String message directly.

      This implementation is different from requireNonNull(Object, Supplier) as it takes an instance of Function for the messageSupplier. That function is called with obj as the argument; this allows to add the invalid value to the exception detail message. The provided message supplier function must accept null as a valid argument.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check; can be null.
      messageSupplier - The supplier of the detail message to be used in the event that a ValidationException is thrown. If null or if it returns null, no detail message is provided.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      NullArgumentException - The validation is null.
      ValidationException - obj failed the validation.
      Since:
      0.1.0

    • requireNonNull

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNull(T obj) throws NullArgumentException

      Checks if the given value obj is null and throws a NullArgumentException if it is null.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check.
      Returns:
      The value if it is not null.
      Throws:
      NullArgumentException - obj is null.
      Since:
      0.0.5
      See Also:

    • requireNonNull

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNull(T obj, String message) throws ValidationException, NullArgumentException, EmptyArgumentException

      Checks if the given value obj is null and throws a ValidationException with the specified message if it is null.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check.
      message - The message that is set to the thrown exception.
      Returns:
      The value if it is not null.
      Throws:
      NullArgumentException - message or obj is null.
      EmptyArgumentException - message is the empty String.
      ValidationException
      Since:
      0.0.5
      See Also:

    • requireNonNull

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNull(T obj, Supplier<String> messageSupplier) throws ValidationException

      Checks that the specified object reference is not null and throws a customized ValidationException if it is.

      Unlike the method requireNonNull(Object,String), this method allows to defer the creation of the message until after the null check failed. While this may confer a performance advantage in the non-null case, when deciding to call this method care should be taken that the costs of creating the message supplier are less than the cost of just creating the String message directly.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      obj - The value to check.
      messageSupplier - The supplier of the detail message to be used in the event that a NullArgumentException is thrown. If null, no detail message is provided.
      Returns:
      The value if it is not null.
      Throws:
      ValidationException - obj is null
      Since:
      0.0.5

    • requireNonNullArgument

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNullArgument(T arg, String name)
      Checks if the given argument a is null and throws a NullArgumentException if it is null.
      Type Parameters:
      T - The type of the argument to check.
      Parameters:
      arg - The argument to check.
      name - The name of the argument; this is used for the error message.
      Returns:
      The argument if it is not null.
      Throws:
      NullArgumentException - arg is null.
      Since:
      0.0.5

    • requireNonNullArgument

      @API(status=STABLE, since="0.0.7") public static final <T> T requireNonNullArgument(T arg, Object otherArg, String name, String otherName)

      Checks if not both of the given arguments arg and otherArg are null and throws a NullArgumentException if both are null. Otherwise, it returns arg.

      Type Parameters:
      T - The type of the first argument to check.
      Parameters:
      arg - The first argument to check; it will be returned in case of success, even if null.
      otherArg - The other argument to check.
      name - The name of the first argument; this is used for the error message.
      otherName - The name of the other argument; this is used for the error message.
      Returns:
      The first argument, even that might be null.
      Throws:
      NullArgumentException - Both arguments are null.
      Since:
      0.0.7

    • requireNotBlankArgument

      @API(status=STABLE, since="0.1.0") public static final <T extends CharSequence> T requireNotBlankArgument(T arg, String name)

      Checks if the given String argument arg is null, empty or blank and throws a NullArgumentException if it is null, an EmptyArgumentException if it is empty, or a BlankArgumentException if it is blank.

      Type Parameters:
      T - The type of the argument to check.
      Parameters:
      arg - The argument to check; may be null.
      name - The name of the argument; this is used for the error message.
      Returns:
      The argument if it is not null, empty or blank.
      Throws:
      NullArgumentException - arg is null.
      EmptyArgumentException - arg is empty.
      BlankArgumentException - arg is blank.
      Since:
      0.1.0
      See Also:

    • requireNotEmptyArgument

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNotEmptyArgument(T arg, String name)

      Checks if the given argument arg is null or empty and throws a NullArgumentException if it is null, or an EmptyArgumentException if it is empty.

      Strings, arrays, instances of Collection and Map as well as instances of StringBuilder, StringBuffer, and CharSequence will be checked on being empty.

      For an instance of Optional, the presence of a value is checked in order to determine whether the Optional is empty or not.

      Because the interface Enumeration does not provide an API for the check on emptiness (hasMoreElements() will return false after all elements have been taken from the Enumeration instance), the result for arguments of this type has to be taken with caution.

      For instances of Stream, this method will only check for null (like requireNonNullArgument(Object,String). This is because any operation on the stream itself would render it unusable for later processing.

      In case the argument is of type Optional, this method behaves different from requireNotEmptyArgument(Optional,String); this one will return the Optional instance, while the other method will return the contents of the Optional.

      This method will not work properly for instances of StringJoiner, because its method length() will not return 0 when a prefix, suffix, or an "empty value" was provided.

      Type Parameters:
      T - The type of the argument to check.
      Parameters:
      arg - The argument to check; may be null.
      name - The name of the argument; this is used for the error message.
      Returns:
      The argument if it is not null or empty.
      Throws:
      NullArgumentException - arg is null.
      EmptyArgumentException - arg is empty.
      Since:
      0.0.5

    • requireNotEmptyArgument

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNotEmptyArgument(Optional<T> optional, String name)

      Checks if the given argument optional of type Optional is null or empty and throws a NullArgumentException if it is null, or a EmptyArgumentException if it is empty.

      Otherwise it returns the value of the Optional.

      This is different from the behaviour of requireNotEmptyArgument(Object,String) with an instance of Optional as the argument to test.

      Type Parameters:
      T - The type of the given Optional to check.
      Parameters:
      optional - The argument to check; can be null.
      name - The name of the argument; this is used for the error message.
      Returns:
      The value of the argument if optional is not null and not empty. This could be the empty string!
      Throws:
      NullArgumentException - optional is null.
      EmptyArgumentException - optional is empty.
      Since:
      0.0.5

    • requireNonNullElse

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNullElse(T obj, T defaultObj) throws NullArgumentException

      Returns the first argument if it is not null, otherwise it returns the non-null second argument.

      This implementation behaves different from that in java.util.Objects.requireNonNullElse(Object,Object) as it will always check that the default is not null.

      Type Parameters:
      T - The type of the references.
      Parameters:
      obj - An object reference.
      defaultObj - Another object reference to be returned if the first argument is null.
      Returns:
      The first argument if it is not null, otherwise the second argument if it is not null.
      Throws:
      NullArgumentException - The defaultObj is null.
      Since:
      0.0.5
      See Also:

    • requireNonNullElseGet

      @API(status=STABLE, since="0.0.5") public static final <T> T requireNonNullElseGet(T obj, Supplier<? extends T> supplier) throws NullArgumentException, NullPointerException

      Returns the first argument if it is not null, otherwise it returns the non-null value returned by supplier.get().

      This implementation behaves different from that in java.util.Objects.requireNonNullElseGet(Object,Supplier) as it will always check that the supplier is not null.

      Note:
      • Although the provided Supplier may not be null, it may return null.
      Type Parameters:
      T - The type of the reference.
      Parameters:
      obj - An object reference.
      supplier - The supplier of a non-null object of type {code T} to return if the first argument is null.
      Returns:
      The first argument if it is not null, otherwise the value returned by a call to supplier.get() if it is not null.
      Throws:
      NullArgumentException - The supplier is null.
      NullPointerException - obj is null and the return value of supplier.get() value is null, too.
      Since:
      0.0.5

    • requireValidArgument

      @API(status=STABLE, since="0.1.0") public static final <T> T requireValidArgument(T arg, String name, Predicate<? super T> validation)

      Applies the given validation on the given value, and if that fails, an ValidationException with a default message is thrown. The validation is also responsible for the null-check; that means, the method test() of the validation may be called with null as the argument.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      arg - The value to check; can be null.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name or validation is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.1.0

    • requireValidArgument

      @API(status=STABLE, since="0.1.0") public static final <T> T requireValidArgument(T arg, String name, Predicate<? super T> validation, UnaryOperator<String> messageSupplier)

      Applies the given validation on the given value, and if that fails, a ValidationException is thrown. The message for the exception will be provided by the given message supplier that takes the name of the argument as an argument.

      The validation is also responsible for the null-check; that means, the method test() of the validation may be called with null as the argument.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      arg - The value to check; can be null.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      messageSupplier - The function that generates the message for the exception.
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name, validation or messageProvider is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.1.0

    • requireValidDoubleArgument

      @API(status=STABLE, since="0.2.0") public static final double requireValidDoubleArgument(double arg, String name, DoublePredicate validation)
      Applies the given validation on the given value, and if that fails, an ValidationException with a default message is thrown.
      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name or validation is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidDoubleArgument

      @API(status=STABLE, since="0.2.0") public static final double requireValidDoubleArgument(double arg, String name, DoublePredicate validation, UnaryOperator<String> messageSupplier)

      Applies the given validation on the given value, and if that fails, a ValidationException is thrown. The message for the exception will be provided by the given message supplier that takes the name of the argument as an argument.

      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      messageSupplier - The function that generates the message for the exception.
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name, validation or messageProvider is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidIntegerArgument

      @API(status=STABLE, since="0.2.0") public static final int requireValidIntegerArgument(int arg, String name, IntPredicate validation)
      Applies the given validation on the given value, and if that fails, an ValidationException with a default message is thrown.
      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name or validation is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidIntegerArgument

      @API(status=STABLE, since="0.2.0") public static final int requireValidIntegerArgument(int arg, String name, IntPredicate validation, UnaryOperator<String> messageSupplier)

      Applies the given validation on the given value, and if that fails, a ValidationException is thrown. The message for the exception will be provided by the given message supplier that takes the name of the argument as an argument.

      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      messageSupplier - The function that generates the message for the exception.
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name, validation or messageProvider is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidLongArgument

      @API(status=STABLE, since="0.2.0") public static final long requireValidLongArgument(long arg, String name, LongPredicate validation)
      Applies the given validation on the given value, and if that fails, an ValidationException with a default message is thrown.
      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name or validation is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidLongArgument

      @API(status=STABLE, since="0.2.0") public static final long requireValidLongArgument(long arg, String name, LongPredicate validation, UnaryOperator<String> messageSupplier)

      Applies the given validation on the given value, and if that fails, a ValidationException is thrown. The message for the exception will be provided by the given message supplier that takes the name of the argument as an argument.

      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      messageSupplier - The function that generates the message for the exception.
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - name, validation or messageProvider is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.2.0

    • requireValidNonNullArgument

      @API(status=STABLE, since="0.1.0") public static final <T> T requireValidNonNullArgument(T arg, String name, Predicate<? super T> validation)

      Applies the given validation on the given value (that must not be null), and if that fails, an ValidationException with a default message is thrown.

      If the value is null, the validation is never triggered.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - a failed the validation.
      NullArgumentException - arg, name or validation is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.1.0

    • requireValidNonNullArgument

      @API(status=STABLE, since="0.1.0") public static final <T> T requireValidNonNullArgument(T arg, String name, Predicate<? super T> validation, UnaryOperator<String> messageSupplier)

      Applies the given validation on the given value (that must not be null), and if that fails, a ValidationException is thrown. The message for the exception will be provided by the given message supplier that takes the name of the argument as an argument.

      Type Parameters:
      T - The type of the value to check.
      Parameters:
      arg - The value to check.
      name - The name of the argument; this is used for the error message.
      validation - The validation
      messageSupplier - The function that generates the message for the exception.
      Returns:
      The value if the validation succeeds.
      Throws:
      ValidationException - arg failed the validation.
      NullArgumentException - arg, name, validation or messageProvider is null.
      EmptyArgumentException - name is the empty String.
      Since:
      0.1.0

    • toString

      @API(status=STABLE, since="0.0.5") public static final String toString(Object object)

      Converts the given argument object into a String, usually by calling its toString() method. If the value of the argument is null, the text "null" will be returned instead. Arrays will be converted to a String through calling the respective toString() method from Arrays (this distinguishes this implementation from {link java.util.Objects#toString(Object, String) java.util.Objects.toString()}). Values of type Date or Calendar will be translated based on the default locale - whatever that is.

      Parameters:
      object - The object; may be null.
      Returns:
      The object's string representation.
      Since:
      0.0.5
      See Also:

    • toString

      @API(status=STABLE, since="0.0.5") public static final String toString(Object object, String nullDefault)

      Converts the given argument object into a String, usually by calling its toString() method. If the value of the argument is null, the text provided as the nullDefault argument will be returned instead.

      Arrays will be converted to a string through calling the respective toString() method from Arrays (this distinguishes this implementation from {link java.util.Objects#toString(Object,String) java.util.Objects.toString(Object,String)}).

      Values of type Date or Calendar will be translated based on the default locale – whatever that is.

      Parameters:
      object - The object; may be null.
      nullDefault - The text that should be returned if object is null.
      Returns:
      The object's string representation.
      Since:
      0.0.5
      See Also:

    • toString

      @API(status=STABLE, since="0.0.5") public static final <T> String toString(T value, Stringer<? super T> stringer, String nullDefault)

      Converts the given argument into a String using the given instance of Stringer. If the value of the argument is null, the text provided as the nullDefault argument will be returned instead.

      Type Parameters:
      T - The type of the object.
      Parameters:
      value - The object; may be null.
      stringer - The method that is used to convert the given object to a String.
      nullDefault - The text that should be returned if object is null.
      Returns:
      The object's string representation.
      Since:
      0.0.5
      See Also: