Class ArgChecker


  • public final class ArgChecker
    extends Object
    Contains utility methods for checking inputs to methods.

    This utility is used throughout the system to validate inputs to methods. Most of the methods return their validated input, allowing patterns like this:

      // constructor
      public Person(String name, int age) {
        this.name = ArgChecker.notBlank(name, "name");
        this.age = ArgChecker.notNegative(age, "age");
      }
     
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> void inOrderNotEqual​(Comparable<? super T> obj1, T obj2, String name1, String name2)
      Checks that the two values are in order and not equal.
      static <T> void inOrderOrEqual​(Comparable<? super T> obj1, T obj2, String name1, String name2)
      Checks that the two values are in order or equal.
      static double inRange​(double argument, double lowInclusive, double highExclusive, String name)
      Checks that the argument is within the range defined by low <= x < high.
      static int inRange​(int argument, int lowInclusive, int highExclusive, String name)
      Checks that the argument is within the range defined by low <= x < high.
      static <T extends Comparable<T>>
      T
      inRangeComparable​(T argument, T lowInclusive, T highExclusive, String name)
      Checks that the argument is within the range defined by low <= x < high using the items' natural order.
      static <T extends Comparable<T>>
      T
      inRangeComparableExclusive​(T argument, T lowExclusive, T highExclusive, String name)
      Checks that the argument is within the range defined by low < x < high using the items' natural order.
      static <T extends Comparable<T>>
      T
      inRangeComparableInclusive​(T argument, T lowInclusive, T highInclusive, String name)
      Checks that the argument is within the range defined by low <= x <= high using the items' natural order.
      static double inRangeExclusive​(double argument, double lowExclusive, double highExclusive, String name)
      Checks that the argument is within the range defined by low < x < high.
      static int inRangeExclusive​(int argument, int lowExclusive, int highExclusive, String name)
      Checks that the argument is within the range defined by low < x < high.
      static double inRangeInclusive​(double argument, double lowInclusive, double highInclusive, String name)
      Checks that the argument is within the range defined by low <= x <= high.
      static int inRangeInclusive​(int argument, int lowInclusive, int highInclusive, String name)
      Checks that the argument is within the range defined by low <= x <= high.
      static void isFalse​(boolean validIfFalse, String message)
      Checks that the specified boolean is false.
      static void isFalse​(boolean validIfFalse, String message, Object... arg)
      Checks that the specified boolean is false.
      static void isTrue​(boolean validIfTrue)
      Checks that the specified boolean is true.
      static void isTrue​(boolean validIfTrue, String message)
      Checks that the specified boolean is true.
      static void isTrue​(boolean validIfTrue, String message, double arg)
      Checks that the specified boolean is true.
      static void isTrue​(boolean validIfTrue, String message, long arg)
      Checks that the specified boolean is true.
      static void isTrue​(boolean validIfTrue, String message, Object... arg)
      Checks that the specified boolean is true.
      static String matches​(CharMatcher matcher, int minLength, int maxLength, String argument, String name, String equivalentRegex)
      Checks that the specified argument is non-null and only contains the specified characters.
      static String matches​(Pattern pattern, String argument, String name)
      Checks that the specified argument is non-null and matches the specified pattern.
      static double[] noDuplicates​(double[] argument, String name)
      Checks that the specified argument array is non-null and does not contain any duplicate values.
      static double[] noDuplicatesSorted​(double[] argument, String name)
      Checks that the specified argument array is non-null, sorted, and does not contain any duplicate values.
      static <T,​I extends Iterable<T>>
      I
      noNulls​(I argument, String name)
      Checks that the specified argument collection is non-null and contains no nulls.
      static <K,​V,​M extends Map<K,​V>>
      M
      noNulls​(M argument, String name)
      Checks that the specified argument map is non-null and contains no nulls.
      static <T> T[] noNulls​(T[] argument, String name)
      Checks that the specified argument array is non-null and contains no nulls.
      static String notBlank​(String argument, String name)
      Checks that the specified argument is non-null and not blank.
      static double[] notEmpty​(double[] argument, String name)
      Checks that the specified argument array is non-null and not empty.
      static int[] notEmpty​(int[] argument, String name)
      Checks that the specified argument array is non-null and not empty.
      static long[] notEmpty​(long[] argument, String name)
      Checks that the specified argument array is non-null and not empty.
      static <T,​C extends Collection<T>>
      C
      notEmpty​(C argument, String name)
      Checks that the specified argument collection is non-null and not empty.
      static <T,​I extends Iterable<T>>
      I
      notEmpty​(I argument, String name)
      Checks that the specified argument iterable is non-null and not empty.
      static String notEmpty​(String argument, String name)
      Checks that the specified argument is non-null and not empty.
      static <K,​V,​M extends Map<K,​V>>
      M
      notEmpty​(M argument, String name)
      Checks that the specified argument map is non-null and not empty.
      static <T> T[] notEmpty​(T[] argument, String name)
      Checks that the specified argument array is non-null and not empty.
      static double notNaN​(double argument, String name)
      Checks that the argument is a number and not NaN.
      static double notNegative​(double argument, String name)
      Checks that the argument is not negative.
      static int notNegative​(int argument, String name)
      Checks that the argument is not negative.
      static long notNegative​(long argument, String name)
      Checks that the argument is not negative.
      static double notNegativeOrZero​(double argument, double tolerance, String name)
      Checks that the argument is greater than zero to within a given accuracy.
      static double notNegativeOrZero​(double argument, String name)
      Checks that the argument is not negative or zero.
      static int notNegativeOrZero​(int argument, String name)
      Checks that the argument is not negative or zero.
      static long notNegativeOrZero​(long argument, String name)
      Checks that the argument is not negative or zero.
      static <T> T notNull​(T argument, String name)
      Checks that the specified argument is non-null.
      static <T> T notNullItem​(T argument)
      Checks that the specified item is non-null.
      static double notZero​(double argument, double tolerance, String name)
      Checks that the argument is not equal to zero to within a given accuracy.
      static double notZero​(double argument, String name)
      Checks that the argument is not equal to zero.
    • Method Detail

      • isTrue

        public static void isTrue​(boolean validIfTrue)
        Checks that the specified boolean is true.

        Given the input argument, this returns normally only if it is true. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isTrue(collection.contains("value"));
         

        It is strongly recommended to pass an additional message argument using isTrue(boolean, String).

        Parameters:
        validIfTrue - a boolean resulting from testing an argument
        Throws:
        IllegalArgumentException - if the test value is false
      • isTrue

        public static void isTrue​(boolean validIfTrue,
                                  String message)
        Checks that the specified boolean is true.

        Given the input argument, this returns normally only if it is true. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isTrue(collection.contains("value"), "Collection must contain 'value'");
         
        Parameters:
        validIfTrue - a boolean resulting from testing an argument
        message - the error message, not null
        Throws:
        IllegalArgumentException - if the test value is false
      • isTrue

        public static void isTrue​(boolean validIfTrue,
                                  String message,
                                  Object... arg)
        Checks that the specified boolean is true.

        Given the input argument, this returns normally only if it is true. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isTrue(collection.contains("value"), "Collection must contain 'value': {}", collection);
         

        This returns void, and not the value being checked, as there is never a good reason to validate a boolean argument value.

        The message is produced using a template that contains zero to many "{}" placeholders. Each placeholder is replaced by the next available argument. If there are too few arguments, then the message will be left with placeholders. If there are too many arguments, then the excess arguments are appended to the end of the message. No attempt is made to format the arguments. See Messages.format(String, Object...) for more details.

        Parameters:
        validIfTrue - a boolean resulting from testing an argument
        message - the error message with {} placeholders, not null
        arg - the message arguments
        Throws:
        IllegalArgumentException - if the test value is false
      • isTrue

        public static void isTrue​(boolean validIfTrue,
                                  String message,
                                  long arg)
        Checks that the specified boolean is true.

        Given the input argument, this returns normally only if it is true. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isTrue(value > check, "Value must be greater than check: {}", value);
         

        This returns void, and not the value being checked, as there is never a good reason to validate a boolean argument value.

        The message is produced using a template that contains zero or one "{}" placeholders. The placeholder, if present, is replaced by the argument. If there is no placeholder, the argument is appended to the end of the message.

        Parameters:
        validIfTrue - a boolean resulting from testing an argument
        message - the error message with {} placeholders, not null
        arg - the message argument
        Throws:
        IllegalArgumentException - if the test value is false
      • isTrue

        public static void isTrue​(boolean validIfTrue,
                                  String message,
                                  double arg)
        Checks that the specified boolean is true.

        Given the input argument, this returns normally only if it is true. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isTrue(value > check, "Value must be greater than check: {}", value);
         

        This returns void, and not the value being checked, as there is never a good reason to validate a boolean argument value.

        The message is produced using a template that contains zero or one "{}" placeholders. The placeholder, if present, is replaced by the argument. If there is no placeholder, the argument is appended to the end of the message.

        Parameters:
        validIfTrue - a boolean resulting from testing an argument
        message - the error message with {} placeholders, not null
        arg - the message argument
        Throws:
        IllegalArgumentException - if the test value is false
      • isFalse

        public static void isFalse​(boolean validIfFalse,
                                   String message)
        Checks that the specified boolean is false.

        Given the input argument, this returns normally only if it is false. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isFalse(collection.contains("value"), "Collection must not contain 'value'");
         

        This returns void, and not the value being checked, as there is never a good reason to validate a boolean argument value.

        Parameters:
        validIfFalse - a boolean resulting from testing an argument
        message - the error message, not null
        Throws:
        IllegalArgumentException - if the test value is true
      • isFalse

        public static void isFalse​(boolean validIfFalse,
                                   String message,
                                   Object... arg)
        Checks that the specified boolean is false.

        Given the input argument, this returns normally only if it is false. This will typically be the result of a caller-specific check. For example:

          ArgChecker.isFalse(collection.contains("value"), "Collection must not contain 'value': {}", collection);
         

        This returns void, and not the value being checked, as there is never a good reason to validate a boolean argument value.

        The message is produced using a template that contains zero to many "{}" placeholders. Each placeholder is replaced by the next available argument. If there are too few arguments, then the message will be left with placeholders. If there are too many arguments, then the excess arguments are appended to the end of the message. No attempt is made to format the arguments. See Messages.format(String, Object...) for more details.

        Parameters:
        validIfFalse - a boolean resulting from testing an argument
        message - the error message with {} placeholders, not null
        arg - the message arguments, not null
        Throws:
        IllegalArgumentException - if the test value is true
      • notNull

        public static <T> T notNull​(T argument,
                                    String name)
        Checks that the specified argument is non-null.

        Given the input argument, this returns only if it is non-null. For example, in a constructor:

          this.name = ArgChecker.notNull(name, "name");
         
        Type Parameters:
        T - the type of the input argument reflected in the result
        Parameters:
        argument - the argument to check, null throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null
      • notNullItem

        public static <T> T notNullItem​(T argument)
        Checks that the specified item is non-null.

        Given the input argument, this returns only if it is non-null. One use for this method is in a stream:

          ArgChecker.notNull(coll, "coll")
          coll.stream()
            .map(ArgChecker::notNullItem)
            ...
         
        Type Parameters:
        T - the type of the input argument reflected in the result
        Parameters:
        argument - the argument to check, null throws an exception
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null
      • matches

        public static String matches​(Pattern pattern,
                                     String argument,
                                     String name)
        Checks that the specified argument is non-null and matches the specified pattern.

        Given the input argument, this returns only if it is non-null and matches the regular expression pattern specified. For example, in a constructor:

          this.name = ArgChecker.matches(REGEX_NAME, name, "name");
         
        Parameters:
        pattern - the pattern to check against, not null
        argument - the argument to check, null throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • matches

        public static String matches​(CharMatcher matcher,
                                     int minLength,
                                     int maxLength,
                                     String argument,
                                     String name,
                                     String equivalentRegex)
        Checks that the specified argument is non-null and only contains the specified characters.

        Given the input argument, this returns only if it is non-null and matches the CharMatcher specified. For example, in a constructor:

          this.name = ArgChecker.matches(REGEX_NAME, 1, Integer.MAX_VALUE, name, "name", "[A-Z]+");
         
        Parameters:
        matcher - the matcher to check against, not null
        minLength - the minimum length to allow
        maxLength - the minimum length to allow
        argument - the argument to check, null throws an exception
        name - the name of the argument to use in the error message, not null
        equivalentRegex - the equivalent regular expression pattern
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notBlank

        public static String notBlank​(String argument,
                                      String name)
        Checks that the specified argument is non-null and not blank.

        Given the input argument, this returns the input only if it is non-null and contains at least one non whitespace character. This is often linked with a call to trim(). For example, in a constructor:

          this.name = ArgChecker.notBlank(name, "name").trim();
         

        The argument is trimmed using String.trim() to determine if it is empty. The result is the original argument, not the trimmed one.

        Parameters:
        argument - the argument to check, null or blank throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or blank
      • notEmpty

        public static String notEmpty​(String argument,
                                      String name)
        Checks that the specified argument is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one character, which may be a whitespace character. See also notBlank(String, String). For example, in a constructor:

          this.name = ArgChecker.notEmpty(name, "name");
         
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static <T> T[] notEmpty​(T[] argument,
                                       String name)
        Checks that the specified argument array is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. The element is not validated and may be null. For example, in a constructor:

          this.names = ArgChecker.notEmpty(names, "names");
         
        Type Parameters:
        T - the type of the input array reflected in the result
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static int[] notEmpty​(int[] argument,
                                     String name)
        Checks that the specified argument array is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. For example, in a constructor:

          this.values = ArgChecker.notEmpty(values, "values");
         
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static long[] notEmpty​(long[] argument,
                                      String name)
        Checks that the specified argument array is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. For example, in a constructor:

          this.values = ArgChecker.notEmpty(values, "values");
         
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static double[] notEmpty​(double[] argument,
                                        String name)
        Checks that the specified argument array is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. For example, in a constructor:

          this.values = ArgChecker.notEmpty(values, "values");
         
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static <T,​I extends Iterable<T>> I notEmpty​(I argument,
                                                                 String name)
        Checks that the specified argument iterable is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. The element is not validated and may be null. For example, in a constructor:

          this.values = ArgChecker.notEmpty(values, "values");
         
        Type Parameters:
        T - the element type of the input iterable reflected in the result
        I - the type of the input iterable, reflected in the result
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static <T,​C extends Collection<T>> C notEmpty​(C argument,
                                                                   String name)
        Checks that the specified argument collection is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one element. The element is not validated and may contain nulls if the collection allows nulls. For example, in a constructor:

          this.values = ArgChecker.notEmpty(values, "values");
         
        Type Parameters:
        T - the element type of the input collection reflected in the result
        C - the type of the input collection, reflected in the result
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • notEmpty

        public static <K,​V,​M extends Map<K,​V>> M notEmpty​(M argument,
                                                                            String name)
        Checks that the specified argument map is non-null and not empty.

        Given the input argument, this returns only if it is non-null and contains at least one mapping. The element is not validated and may contain nulls if the collection allows nulls. For example, in a constructor:

          this.keyValues = ArgChecker.notEmpty(keyValues, "keyValues");
         
        Type Parameters:
        K - the key type of the input map key, reflected in the result
        V - the value type of the input map value, reflected in the result
        M - the type of the input map, reflected in the result
        Parameters:
        argument - the argument to check, null or empty throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or empty
      • noNulls

        public static <T> T[] noNulls​(T[] argument,
                                      String name)
        Checks that the specified argument array is non-null and contains no nulls.

        Given the input argument, this returns only if it is non-null and contains no nulls. For example, in a constructor:

          this.values = ArgChecker.noNulls(values, "values");
         
        Type Parameters:
        T - the type of the input array reflected in the result
        Parameters:
        argument - the argument to check, null or contains null throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or contains nulls
      • noNulls

        public static <T,​I extends Iterable<T>> I noNulls​(I argument,
                                                                String name)
        Checks that the specified argument collection is non-null and contains no nulls.

        Given the input argument, this returns only if it is non-null and contains no nulls. For example, in a constructor:

          this.values = ArgChecker.noNulls(values, "values");
         
        Type Parameters:
        T - the element type of the input iterable reflected in the result
        I - the type of the input iterable, reflected in the result
        Parameters:
        argument - the argument to check, null or contains null throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or contains nulls
      • noNulls

        public static <K,​V,​M extends Map<K,​V>> M noNulls​(M argument,
                                                                           String name)
        Checks that the specified argument map is non-null and contains no nulls.

        Given the input argument, this returns only if it is non-null and contains no nulls. For example, in a constructor:

          this.keyValues = ArgChecker.noNulls(keyValues, "keyValues");
         
        Type Parameters:
        K - the key type of the input map key, reflected in the result
        V - the value type of the input map value, reflected in the result
        M - the type of the input map, reflected in the result
        Parameters:
        argument - the argument to check, null or contains null throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or contains nulls
      • noDuplicates

        public static double[] noDuplicates​(double[] argument,
                                            String name)
        Checks that the specified argument array is non-null and does not contain any duplicate values.

        Given the input argument, this returns only if it is non-null and does not contain duplicate values. For example, in a constructor:

          this.values = ArgChecker.noDuplicates(values, "values");
         

        If you know the argument is sorted increasing then noDuplicatesSorted(double[], String) might be more performant.

        Parameters:
        argument - the argument to check, null or duplicate values throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null or contains duplicate values
      • noDuplicatesSorted

        public static double[] noDuplicatesSorted​(double[] argument,
                                                  String name)
        Checks that the specified argument array is non-null, sorted, and does not contain any duplicate values.

        Given the input argument, this returns only if it is non-null, sorted, and does not contain duplicate values. For example, in a constructor:

          this.values = ArgChecker.noDuplicatesSorted(values, "values");
         
        Parameters:
        argument - the argument to check, null, out of order or duplicate values throws an exception
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument, not null
        Throws:
        IllegalArgumentException - if the input is null, unsorted, or contains duplicate values
      • notNegative

        public static int notNegative​(int argument,
                                      String name)
        Checks that the argument is not negative.

        Given the input argument, this returns only if it is zero or greater. For example, in a constructor:

          this.amount = ArgChecker.notNegative(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative
      • notNegative

        public static long notNegative​(long argument,
                                       String name)
        Checks that the argument is not negative.

        Given the input argument, this returns only if it is zero or greater. For example, in a constructor:

          this.amount = ArgChecker.notNegative(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative
      • notNegative

        public static double notNegative​(double argument,
                                         String name)
        Checks that the argument is not negative.

        Given the input argument, this returns only if it is zero or greater. For example, in a constructor:

          this.amount = ArgChecker.notNegative(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative
      • notNaN

        public static double notNaN​(double argument,
                                    String name)
        Checks that the argument is a number and not NaN.

        Given the input argument, this returns only if it is an actual number. For example, in a constructor:

          this.amount = ArgChecker.notNaN(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is NaN
      • notNegativeOrZero

        public static int notNegativeOrZero​(int argument,
                                            String name)
        Checks that the argument is not negative or zero.

        Given the input argument, this returns only if it is greater than zero. For example, in a constructor:

          this.amount = ArgChecker.notNegativeOrZero(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative or zero
      • notNegativeOrZero

        public static long notNegativeOrZero​(long argument,
                                             String name)
        Checks that the argument is not negative or zero.

        Given the input argument, this returns only if it is greater than zero. For example, in a constructor:

          this.amount = ArgChecker.notNegativeOrZero(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative or zero
      • notNegativeOrZero

        public static double notNegativeOrZero​(double argument,
                                               String name)
        Checks that the argument is not negative or zero.

        Given the input argument, this returns only if it is greater than zero. For example, in a constructor:

          this.amount = ArgChecker.notNegativeOrZero(amount, "amount");
         
        Parameters:
        argument - the argument to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the input is negative or zero
      • notNegativeOrZero

        public static double notNegativeOrZero​(double argument,
                                               double tolerance,
                                               String name)
        Checks that the argument is greater than zero to within a given accuracy.

        Given the input argument, this returns only if it is greater than zero using the eps accuracy for zero. For example, in a constructor:

          this.amount = ArgChecker.notNegativeOrZero(amount, 0.0001d, "amount");
         
        Parameters:
        argument - the value to check
        tolerance - the tolerance to use for zero
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the absolute value of the argument is less than eps
      • notZero

        public static double notZero​(double argument,
                                     String name)
        Checks that the argument is not equal to zero.

        Given the input argument, this returns only if it is not zero. Both positive and negative zero are checked. For example, in a constructor:

          this.amount = ArgChecker.notZero(amount, "amount");
         
        Parameters:
        argument - the value to check
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is zero
      • notZero

        public static double notZero​(double argument,
                                     double tolerance,
                                     String name)
        Checks that the argument is not equal to zero to within a given accuracy.

        Given the input argument, this returns only if it is not zero comparing using the eps accuracy. For example, in a constructor:

          this.amount = ArgChecker.notZero(amount, 0.0001d, "amount");
         
        Parameters:
        argument - the value to check
        tolerance - the tolerance to use for zero
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the absolute value of the argument is less than the tolerance
      • inRange

        public static double inRange​(double argument,
                                     double lowInclusive,
                                     double highExclusive,
                                     String name)
        Checks that the argument is within the range defined by low <= x < high.

        Given a value, this returns true if it is within the specified range including the lower boundary but excluding the upper boundary. For example, in a constructor:

          this.amount = ArgChecker.inRange(amount, 0d, 1d, "amount");
         
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeInclusive

        public static double inRangeInclusive​(double argument,
                                              double lowInclusive,
                                              double highInclusive,
                                              String name)
        Checks that the argument is within the range defined by low <= x <= high.

        Given a value, this returns true if it is within the specified range including both boundaries. For example, in a constructor:

          this.amount = ArgChecker.inRangeInclusive(amount, 0d, 1d, "amount");
         
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highInclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeExclusive

        public static double inRangeExclusive​(double argument,
                                              double lowExclusive,
                                              double highExclusive,
                                              String name)
        Checks that the argument is within the range defined by low < x < high.

        Given a value, this returns true if it is within the specified range excluding both boundaries. For example, in a constructor:

          this.amount = ArgChecker.inRangeExclusive(amount, 0d, 1d, "amount");
         
        Parameters:
        argument - the value to check
        lowExclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRange

        public static int inRange​(int argument,
                                  int lowInclusive,
                                  int highExclusive,
                                  String name)
        Checks that the argument is within the range defined by low <= x < high.

        Given a value, this returns true if it is within the specified range including the lower boundary but excluding the upper boundary. For example, in a constructor:

          this.amount = ArgChecker.inRange(amount, 0, 1, "amount");
         
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeInclusive

        public static int inRangeInclusive​(int argument,
                                           int lowInclusive,
                                           int highInclusive,
                                           String name)
        Checks that the argument is within the range defined by low <= x <= high.

        Given a value, this returns true if it is within the specified range including both boundaries. For example, in a constructor:

          this.amount = ArgChecker.inRangeInclusive(amount, 0, 1, "amount");
         
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highInclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeExclusive

        public static int inRangeExclusive​(int argument,
                                           int lowExclusive,
                                           int highExclusive,
                                           String name)
        Checks that the argument is within the range defined by low < x < high.

        Given a value, this returns true if it is within the specified range excluding both boundaries. For example, in a constructor:

          this.amount = ArgChecker.inRangeExclusive(amount, 0, 1, "amount");
         
        Parameters:
        argument - the value to check
        lowExclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeComparable

        public static <T extends Comparable<T>> T inRangeComparable​(T argument,
                                                                    T lowInclusive,
                                                                    T highExclusive,
                                                                    String name)
        Checks that the argument is within the range defined by low <= x < high using the items' natural order.

        Given a value, this returns true if it is within the specified range including the lower boundary but excluding the upper boundary. For example, in a constructor:

          this.duration = ArgChecker.inRangeComparable(duration, Duration.ZERO, Duration.ofHours(1), "duration");
         
        Type Parameters:
        T - the type of the value
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeComparableInclusive

        public static <T extends Comparable<T>> T inRangeComparableInclusive​(T argument,
                                                                             T lowInclusive,
                                                                             T highInclusive,
                                                                             String name)
        Checks that the argument is within the range defined by low <= x <= high using the items' natural order.

        Given a value, this returns true if it is within the specified range including both boundaries. For example, in a constructor:

          this.duration = ArgChecker.inRangeComparableInclusive(duration, Duration.ZERO, Duration.ofHours(1), "duration");
         
        Type Parameters:
        T - the type of the value
        Parameters:
        argument - the value to check
        lowInclusive - the low value of the range
        highInclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inRangeComparableExclusive

        public static <T extends Comparable<T>> T inRangeComparableExclusive​(T argument,
                                                                             T lowExclusive,
                                                                             T highExclusive,
                                                                             String name)
        Checks that the argument is within the range defined by low < x < high using the items' natural order.

        Given a value, this returns true if it is within the specified range excluding both boundaries. For example, in a constructor:

          this.duration = ArgChecker.inRangeComparableExclusive(duration, Duration.ZERO, Duration.ofHours(1), "duration");
         
        Type Parameters:
        T - the type of the value
        Parameters:
        argument - the value to check
        lowExclusive - the low value of the range
        highExclusive - the high value of the range
        name - the name of the argument to use in the error message, not null
        Returns:
        the input argument
        Throws:
        IllegalArgumentException - if the argument is outside the valid range
      • inOrderNotEqual

        public static <T> void inOrderNotEqual​(Comparable<? super T> obj1,
                                               T obj2,
                                               String name1,
                                               String name2)
        Checks that the two values are in order and not equal.

        Given two comparable instances, this checks that the first is "less than" the second. Two equal values also throw the exception.

        Type Parameters:
        T - the type
        Parameters:
        obj1 - the first object, null throws an exception
        obj2 - the second object, null throws an exception
        name1 - the first argument name, not null
        name2 - the second argument name, not null
        Throws:
        IllegalArgumentException - if either input is null or they are not in order
      • inOrderOrEqual

        public static <T> void inOrderOrEqual​(Comparable<? super T> obj1,
                                              T obj2,
                                              String name1,
                                              String name2)
        Checks that the two values are in order or equal.

        Given two comparable instances, this checks that the first is "less than" or "equal to" the second.

        Type Parameters:
        T - the type
        Parameters:
        obj1 - the first object, null throws an exception
        obj2 - the second object, null throws an exception
        name1 - the first argument name, not null
        name2 - the second argument name, not null
        Throws:
        IllegalArgumentException - if either input is null or they are not in order