/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      https://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.lang3;
  
  import java.util.Collection;
  import java.util.Map;
  import java.util.Objects;
  import java.util.concurrent.atomic.AtomicInteger;
  import java.util.function.Supplier;
  import java.util.regex.Pattern;
  
  /**
   * This class assists in validating arguments. The validation methods are
   * based along the following principles:
   * <ul>
   *   <li>An invalid {@code null} argument causes a {@link NullPointerException}.</li>
   *   <li>A non-{@code null} argument causes an {@link IllegalArgumentException}.</li>
   *   <li>An invalid index into an array/collection/map/string causes an {@link IndexOutOfBoundsException}.</li>
   * </ul>
   *
   * <p>All exceptions messages are
   * <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax">format strings</a>
   * as defined by the Java platform. For example:
   *
   * <pre>
   * Validate.isTrue(i &gt; 0, "The value must be greater than zero: %d", i);
   * Validate.notNull(surname, "The surname must not be %s", null);
   * </pre>
   *
   * <p>#ThreadSafe#</p>
   * @see String#format(String, Object...)
   * @since 2.0
   */
  public class Validate {
  
      private static final String DEFAULT_NOT_NAN_EX_MESSAGE =
          "The validated value is not a number";
      private static final String DEFAULT_FINITE_EX_MESSAGE =
          "The value is invalid: %f";
      private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
          "The value %s is not in the specified exclusive range of %s to %s";
      private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
          "The value %s is not in the specified inclusive range of %s to %s";
      private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
      private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
      private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
      private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
          "The validated array contains null element at index: %d";
      private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
          "The validated collection contains null element at index: %d";
      private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
      private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
      private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
          "The validated character sequence is empty";
      private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
      private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
      private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
      private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
          "The validated character sequence index is invalid: %d";
      private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
          "The validated collection index is invalid: %d";
      private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
      private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
      private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
  
      /**
       * Validate that the specified primitive value falls between the two
       * exclusive values specified; otherwise, throws an exception.
       *
       * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1);</pre>
       *
       * @param start the exclusive start value
       * @param end   the exclusive end value
       * @param value the value to validate
       * @throws IllegalArgumentException if the value falls out of the boundaries
       * @since 3.3
       */
      @SuppressWarnings("boxing")
      public static void exclusiveBetween(final double start, final double end, final double value) {
          // TODO when breaking BC, consider returning value
          if (value <= start || value >= end) {
              throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
          }
      }
  
     /**
      * Validate that the specified primitive value falls between the two
      * exclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
      *
      * @param start the exclusive start value
      * @param end   the exclusive end value
      * @param value the value to validate
      * @param message the exception message if invalid, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @since 3.3
      */
     public static void exclusiveBetween(final double start, final double end, final double value, final String message) {
         // TODO when breaking BC, consider returning value
         if (value <= start || value >= end) {
             throw new IllegalArgumentException(message);
         }
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * exclusive values specified; otherwise, throws an exception.
      *
      * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
      *
      * @param start the exclusive start value
      * @param end   the exclusive end value
      * @param value the value to validate
      * @throws IllegalArgumentException if the value falls out of the boundaries
      * @since 3.3
      */
     @SuppressWarnings("boxing")
     public static void exclusiveBetween(final long start, final long end, final long value) {
         // TODO when breaking BC, consider returning value
         if (value <= start || value >= end) {
             throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
         }
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * exclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in range");</pre>
      *
      * @param start the exclusive start value
      * @param end   the exclusive end value
      * @param value the value to validate
      * @param message the exception message if invalid, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @since 3.3
      */
     public static void exclusiveBetween(final long start, final long end, final long value, final String message) {
         // TODO when breaking BC, consider returning value
         if (value <= start || value >= end) {
             throw new IllegalArgumentException(message);
         }
     }
 
     /**
      * Validate that the specified argument object fall between the two
      * exclusive values specified; otherwise, throws an exception.
      *
      * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
      *
      * @param <T> the type of the argument object
      * @param start  the exclusive start value, not null
      * @param end  the exclusive end value, not null
      * @param value  the object to validate, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
      * @since 3.0
      */
     public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value) {
         // TODO when breaking BC, consider returning value
         if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
             throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
         }
     }
 
     /**
      * Validate that the specified argument object fall between the two
      * exclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
      *
      * @param <T> the type of the argument object
      * @param start  the exclusive start value, not null
      * @param end  the exclusive end value, not null
      * @param value  the object to validate, not null
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @see #exclusiveBetween(Object, Object, Comparable)
      * @since 3.0
      */
     public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
         // TODO when breaking BC, consider returning value
         if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validates that the specified argument is not infinite or Not-a-Number (NaN);
      * otherwise throwing an exception.
      *
      * <pre>Validate.finite(myDouble);</pre>
      *
      * <p>The message of the exception is &quot;The value is invalid: %f&quot;.</p>
      *
      * @param value  the value to validate
      * @throws IllegalArgumentException if the value is infinite or Not-a-Number (NaN)
      * @see #finite(double, String, Object...)
      * @since 3.5
      */
     public static void finite(final double value) {
         finite(value, DEFAULT_FINITE_EX_MESSAGE, value);
     }
 
     /**
      * Validates that the specified argument is not infinite or Not-a-Number (NaN);
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.finite(myDouble, "The argument must contain a numeric value");</pre>
      *
      * @param value the value to validate
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message
      * @throws IllegalArgumentException if the value is infinite or Not-a-Number (NaN)
      * @see #finite(double)
      * @since 3.5
      */
     public static void finite(final double value, final String message, final Object... values) {
         if (Double.isNaN(value) || Double.isInfinite(value)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Gets the message using {@link String#format(String, Object...) String.format(message, values)}
      * if the values are not empty, otherwise return the message unformatted.
      * This method exists to allow validation methods declaring a String message and varargs parameters
      * to be used without any message parameters when the message contains special characters,
      * e.g. {@code Validate.isTrue(false, "%Failed%")}.
      *
      * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values the optional values for the formatted message
      * @return formatted message using {@link String#format(String, Object...) String.format(message, values)}
      * if the values are not empty, otherwise return the unformatted message.
      */
     private static String getMessage(final String message, final Object... values) {
         return ArrayUtils.isEmpty(values) ? message : String.format(message, values);
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * inclusive values specified; otherwise, throws an exception.
      *
      * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1);</pre>
      *
      * @param start the inclusive start value
      * @param end   the inclusive end value
      * @param value the value to validate
      * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
      * @since 3.3
      */
     @SuppressWarnings("boxing")
     public static void inclusiveBetween(final double start, final double end, final double value) {
         // TODO when breaking BC, consider returning value
         if (value < start || value > end) {
             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
         }
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * inclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
      *
      * @param start the inclusive start value
      * @param end   the inclusive end value
      * @param value the value to validate
      * @param message the exception message if invalid, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @since 3.3
      */
     public static void inclusiveBetween(final double start, final double end, final double value, final String message) {
         // TODO when breaking BC, consider returning value
         if (value < start || value > end) {
             throw new IllegalArgumentException(message);
         }
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * inclusive values specified; otherwise, throws an exception.
      *
      * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
      *
      * @param start the inclusive start value
      * @param end   the inclusive end value
      * @param value the value to validate
      * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
      * @since 3.3
      */
     @SuppressWarnings("boxing")
     public static void inclusiveBetween(final long start, final long end, final long value) {
         // TODO when breaking BC, consider returning value
         if (value < start || value > end) {
             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
         }
     }
 
     /**
      * Validate that the specified primitive value falls between the two
      * inclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in range");</pre>
      *
      * @param start the inclusive start value
      * @param end   the inclusive end value
      * @param value the value to validate
      * @param message the exception message if invalid, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @since 3.3
      */
     public static void inclusiveBetween(final long start, final long end, final long value, final String message) {
         // TODO when breaking BC, consider returning value
         if (value < start || value > end) {
             throw new IllegalArgumentException(message);
         }
     }
 
     /**
      * Validate that the specified argument object fall between the two
      * inclusive values specified; otherwise, throws an exception.
      *
      * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
      *
      * @param <T> the type of the argument object
      * @param start  the inclusive start value, not null
      * @param end  the inclusive end value, not null
      * @param value  the object to validate, not null
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
      * @since 3.0
      */
     public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value) {
         // TODO when breaking BC, consider returning value
         if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
         }
     }
 
     /**
      * Validate that the specified argument object fall between the two
      * inclusive values specified; otherwise, throws an exception with the
      * specified message.
      *
      * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
      *
      * @param <T> the type of the argument object
      * @param start  the inclusive start value, not null
      * @param end  the inclusive end value, not null
      * @param value  the object to validate, not null
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if the value falls outside the boundaries
      * @see #inclusiveBetween(Object, Object, Comparable)
      * @since 3.0
      */
     public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
         // TODO when breaking BC, consider returning value
         if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validates that the argument can be converted to the specified class, if not, throws an exception.
      *
      * <p>This method is useful when validating that there will be no casting errors.</p>
      *
      * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
      *
      * <p>The message format of the exception is &quot;Cannot assign {type} to {superType}&quot;</p>
      *
      * @param superType  the class must be validated against, not null
      * @param type  the class to check, not null
      * @throws IllegalArgumentException if type argument is not assignable to the specified superType
      * @see #isAssignableFrom(Class, Class, String, Object...)
      * @since 3.0
      */
     public static void isAssignableFrom(final Class<?> superType, final Class<?> type) {
         // TODO when breaking BC, consider returning type
         if (type == null || superType == null || !superType.isAssignableFrom(type)) {
             throw new IllegalArgumentException(
                 String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE, ClassUtils.getName(type, "null type"), ClassUtils.getName(superType, "null type")));
         }
     }
 
     /**
      * Validates that the argument can be converted to the specified class, if not throws an exception.
      *
      * <p>This method is useful when validating if there will be no casting errors.</p>
      *
      * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
      *
      * <p>The message of the exception is &quot;The validated object cannot be converted to the&quot;
      * followed by the name of the class and &quot;class&quot;</p>
      *
      * @param superType  the class must be validated against, not null
      * @param type  the class to check, not null
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if argument cannot be converted to the specified class
      * @see #isAssignableFrom(Class, Class)
      */
     public static void isAssignableFrom(final Class<?> superType, final Class<?> type, final String message, final Object... values) {
         // TODO when breaking BC, consider returning type
         if (!superType.isAssignableFrom(type)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validates that the argument is an instance of the specified class, if not throws an exception.
      *
      * <p>This method is useful when validating according to an arbitrary class</p>
      *
      * <pre>Validate.isInstanceOf(OkClass.class, object);</pre>
      *
      * <p>The message of the exception is &quot;Expected type: {type}, actual: {obj_type}&quot;</p>
      *
      * @param type  the class the object must be validated against, not null
      * @param obj  the object to check, null throws an exception
      * @throws IllegalArgumentException if argument is not of specified class
      * @see #isInstanceOf(Class, Object, String, Object...)
      * @since 3.0
      */
     public static void isInstanceOf(final Class<?> type, final Object obj) {
         // TODO when breaking BC, consider returning obj
         if (!type.isInstance(obj)) {
             throw new IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE, type.getName(), ClassUtils.getName(obj, "null")));
         }
     }
 
     /**
      * Validate that the argument is an instance of the specified class; otherwise
      * throwing an exception with the specified message. This method is useful when
      * validating according to an arbitrary class
      *
      * <pre>Validate.isInstanceOf(OkClass.class, object, "Wrong class, object is of class %s",
      *   object.getClass().getName());</pre>
      *
      * @param type  the class the object must be validated against, not null
      * @param obj  the object to check, null throws an exception
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if argument is not of specified class
      * @see #isInstanceOf(Class, Object)
      * @since 3.0
      */
     public static void isInstanceOf(final Class<?> type, final Object obj, final String message, final Object... values) {
         // TODO when breaking BC, consider returning obj
         if (!type.isInstance(obj)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validate that the argument condition is {@code true}; otherwise
      * throwing an exception. This method is useful when validating according
      * to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>
      * Validate.isTrue(i &gt; 0);
      * Validate.isTrue(myObject.isOk());</pre>
      *
      * <p>The message of the exception is &quot;The validated expression is
      * false&quot;.</p>
      *
      * @param expression  the boolean expression to check
      * @throws IllegalArgumentException if expression is {@code false}
      * @see #isTrue(boolean, String, long)
      * @see #isTrue(boolean, String, double)
      * @see #isTrue(boolean, String, Object...)
      * @see #isTrue(boolean, Supplier)
      */
     public static void isTrue(final boolean expression) {
         if (!expression) {
             throw new IllegalArgumentException(DEFAULT_IS_TRUE_EX_MESSAGE);
         }
     }
 
     /**
      * Validate that the argument condition is {@code true}; otherwise
      * throwing an exception with the specified message. This method is useful when
      * validating according to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>Validate.isTrue(d &gt; 0.0, "The value must be greater than zero: &#37;s", d);</pre>
      *
      * <p>For performance reasons, the double value is passed as a separate parameter and
      * appended to the exception message only in the case of an error.</p>
      *
      * @param expression  the boolean expression to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param value  the value to append to the message when invalid
      * @throws IllegalArgumentException if expression is {@code false}
      * @see #isTrue(boolean)
      * @see #isTrue(boolean, String, long)
      * @see #isTrue(boolean, String, Object...)
      * @see #isTrue(boolean, Supplier)
      */
     public static void isTrue(final boolean expression, final String message, final double value) {
         if (!expression) {
             throw new IllegalArgumentException(String.format(message, Double.valueOf(value)));
         }
     }
 
     /**
      * Validate that the argument condition is {@code true}; otherwise
      * throwing an exception with the specified message. This method is useful when
      * validating according to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>Validate.isTrue(i &gt; 0.0, "The value must be greater than zero: &#37;d", i);</pre>
      *
      * <p>For performance reasons, the long value is passed as a separate parameter and
      * appended to the exception message only in the case of an error.</p>
      *
      * @param expression  the boolean expression to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param value  the value to append to the message when invalid
      * @throws IllegalArgumentException if expression is {@code false}
      * @see #isTrue(boolean)
      * @see #isTrue(boolean, String, double)
      * @see #isTrue(boolean, String, Object...)
      * @see #isTrue(boolean, Supplier)
      */
     public static void isTrue(final boolean expression, final String message, final long value) {
         if (!expression) {
             throw new IllegalArgumentException(String.format(message, Long.valueOf(value)));
         }
     }
 
     /**
      * Validate that the argument condition is {@code true}; otherwise
      * throwing an exception with the specified message. This method is useful when
      * validating according to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>{@code
      * Validate.isTrue(i >= min &amp;&amp; i <= max, "The value must be between %d and %d", min, max);}</pre>
      *
      * @param expression  the boolean expression to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if expression is {@code false}
      * @see #isTrue(boolean)
      * @see #isTrue(boolean, String, long)
      * @see #isTrue(boolean, String, double)
      * @see #isTrue(boolean, Supplier)
      */
     public static void isTrue(final boolean expression, final String message, final Object... values) {
         if (!expression) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validate that the argument condition is {@code true}; otherwise throwing an exception with the specified message. This method is useful when validating
      * according to an arbitrary boolean expression, such as validating a primitive number or using your own custom validation expression.
      *
      * <pre>{@code
      * Validate.isTrue(i >= min && i <= max, "The value must be between %d and %d", min, max);
      * }</pre>
      *
      * @param expression      the boolean expression to check
      * @param messageSupplier the exception message supplier
      * @throws IllegalArgumentException if expression is {@code false}
      * @see #isTrue(boolean)
      * @see #isTrue(boolean, String, long)
      * @see #isTrue(boolean, String, double)
      * @since 3.18.0
      */
     public static void isTrue(final boolean expression, final Supplier<String> messageSupplier) {
         if (!expression) {
             throw new IllegalArgumentException(messageSupplier.get());
         }
     }
 
     /**
      * Validate that the specified argument character sequence matches the specified regular
      * expression pattern; otherwise throwing an exception.
      *
      * <pre>Validate.matchesPattern("hi", "[a-z]*");</pre>
      *
      * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
      *
      * @param input  the character sequence to validate, not null
      * @param pattern  the regular expression pattern, not null
      * @throws IllegalArgumentException if the character sequence does not match the pattern
      * @see #matchesPattern(CharSequence, String, String, Object...)
      * @since 3.0
      */
     public static void matchesPattern(final CharSequence input, final String pattern) {
         // TODO when breaking BC, consider returning input
         if (!Pattern.matches(pattern, input)) {
             throw new IllegalArgumentException(String.format(DEFAULT_MATCHES_PATTERN_EX, input, pattern));
         }
     }
 
     /**
      * Validate that the specified argument character sequence matches the specified regular
      * expression pattern; otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.matchesPattern("hi", "[a-z]*", "%s does not match %s", "hi" "[a-z]*");</pre>
      *
      * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
      *
      * @param input  the character sequence to validate, not null
      * @param pattern  the regular expression pattern, not null
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalArgumentException if the character sequence does not match the pattern
      * @see #matchesPattern(CharSequence, String)
      * @since 3.0
      */
     public static void matchesPattern(final CharSequence input, final String pattern, final String message, final Object... values) {
         // TODO when breaking BC, consider returning input
         if (!Pattern.matches(pattern, input)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validate that the specified argument iterable is neither
      * {@code null} nor contains any elements that are {@code null};
      * otherwise throwing an exception.
      *
      * <pre>Validate.noNullElements(myCollection);</pre>
      *
      * <p>If the iterable is {@code null}, then the message in the exception
      * is &quot;The validated object is null&quot;.
      *
      * <p>If the array has a {@code null} element, then the message in the
      * exception is &quot;The validated iterable contains null element at index:
      * &quot; followed by the index.</p>
      *
      * @param <T> the iterable type
      * @param iterable  the iterable to check, validated not null by this method
      * @return the validated iterable (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if an element is {@code null}
      * @see #noNullElements(Iterable, String, Object...)
      */
     public static <T extends Iterable<?>> T noNullElements(final T iterable) {
         return noNullElements(iterable, DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE);
     }
 
     /**
      * Validate that the specified argument iterable is neither
      * {@code null} nor contains any elements that are {@code null};
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.noNullElements(myCollection, "The collection contains null at position %d");</pre>
      *
      * <p>If the iterable is {@code null}, then the message in the exception
      * is &quot;The validated object is null&quot;.
      *
      * <p>If the iterable has a {@code null} element, then the iteration
      * index of the invalid element is appended to the {@code values}
      * argument.</p>
      *
      * @param <T> the iterable type
      * @param iterable  the iterable to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated iterable (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if an element is {@code null}
      * @see #noNullElements(Iterable)
      */
     public static <T extends Iterable<?>> T noNullElements(final T iterable, final String message, final Object... values) {
         Objects.requireNonNull(iterable, "iterable");
         final AtomicInteger ai = new AtomicInteger();
         iterable.forEach(e -> {
             if (e == null) {
                 throw new IllegalArgumentException(getMessage(message, ArrayUtils.addAll(values, ai.getAndIncrement())));
             }
         });
         return iterable;
     }
 
     /**
      * Validate that the specified argument array is neither
      * {@code null} nor contains any elements that are {@code null};
      * otherwise throwing an exception.
      *
      * <pre>Validate.noNullElements(myArray);</pre>
      *
      * <p>If the array is {@code null}, then the message in the exception
      * is &quot;The validated object is null&quot;.</p>
      *
      * <p>If the array has a {@code null} element, then the message in the
      * exception is &quot;The validated array contains null element at index:
      * &quot; followed by the index.</p>
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @return the validated array (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if an element is {@code null}
      * @see #noNullElements(Object[], String, Object...)
      */
     public static <T> T[] noNullElements(final T[] array) {
         return noNullElements(array, DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE);
     }
 
     /**
      * Validate that the specified argument array is neither
      * {@code null} nor contains any elements that are {@code null};
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.noNullElements(myArray, "The array contain null at position %d");</pre>
      *
      * <p>If the array is {@code null}, then the message in the exception
      * is &quot;The validated object is null&quot;.
      *
      * <p>If the array has a {@code null} element, then the iteration
      * index of the invalid element is appended to the {@code values}
      * argument.</p>
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated array (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if an element is {@code null}
      * @see #noNullElements(Object[])
      */
     public static <T> T[] noNullElements(final T[] array, final String message, final Object... values) {
         Objects.requireNonNull(array, "array");
         for (int i = 0; i < array.length; i++) {
             if (array[i] == null) {
                 final Object[] values2 = ArrayUtils.add(values, Integer.valueOf(i));
                 throw new IllegalArgumentException(getMessage(message, values2));
             }
         }
         return array;
     }
 
     /**
      * <p>Validates that the specified argument character sequence is
      * neither {@code null}, a length of zero (no characters), empty
      * nor whitespace; otherwise throwing an exception.
      *
      * <pre>Validate.notBlank(myString);</pre>
      *
      * <p>The message in the exception is &quot;The validated character
      * sequence is blank&quot;.
      *
      * @param <T> the character sequence type
      * @param chars  the character sequence to check, validated not null by this method
      * @return the validated character sequence (never {@code null} method for chaining)
      * @throws NullPointerException if the character sequence is {@code null}
      * @throws IllegalArgumentException if the character sequence is blank
      * @see #notBlank(CharSequence, String, Object...)
      * @since 3.0
      */
     public static <T extends CharSequence> T notBlank(final T chars) {
         return notBlank(chars, DEFAULT_NOT_BLANK_EX_MESSAGE);
     }
 
     /**
      * Validates that the specified argument character sequence is not {@link StringUtils#isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}) or
      * {@code null}); otherwise throwing an exception with the specified message.
      *
      * <pre>
      * Validate.notBlank(myString, "The string must not be blank");
      * </pre>
      *
      * @param <T>     the character sequence type
      * @param chars   the character sequence to check, validated not null by this method
      * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated character sequence (never {@code null} method for chaining)
      * @throws NullPointerException     if the character sequence is {@code null}
      * @throws IllegalArgumentException if the character sequence is blank
      * @see #notBlank(CharSequence)
      * @see StringUtils#isBlank(CharSequence)
      * @since 3.0
      */
     public static <T extends CharSequence> T notBlank(final T chars, final String message, final Object... values) {
         Objects.requireNonNull(chars, toSupplier(message, values));
         if (StringUtils.isBlank(chars)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
         return chars;
     }
 
     /**
      * <p>Validates that the specified argument collection is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myCollection);</pre>
      *
      * <p>The message in the exception is &quot;The validated collection is
      * empty&quot;.
      *
      * @param <T> the collection type
      * @param collection  the collection to check, validated not null by this method
      * @return the validated collection (never {@code null} method for chaining)
      * @throws NullPointerException if the collection is {@code null}
      * @throws IllegalArgumentException if the collection is empty
      * @see #notEmpty(Collection, String, Object...)
      */
     public static <T extends Collection<?>> T notEmpty(final T collection) {
         return notEmpty(collection, DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE);
     }
 
     /**
      * <p>Validates that the specified argument map is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myMap);</pre>
      *
      * <p>The message in the exception is &quot;The validated map is
      * empty&quot;.
      *
      * @param <T> the map type
      * @param map  the map to check, validated not null by this method
      * @return the validated map (never {@code null} method for chaining)
      * @throws NullPointerException if the map is {@code null}
      * @throws IllegalArgumentException if the map is empty
      * @see #notEmpty(Map, String, Object...)
      */
     public static <T extends Map<?, ?>> T notEmpty(final T map) {
         return notEmpty(map, DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE);
     }
 
     /**
      * <p>Validates that the specified argument character sequence is
      * neither {@code null} nor a length of zero (no characters);
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.notEmpty(myString);</pre>
      *
      * <p>The message in the exception is &quot;The validated
      * character sequence is empty&quot;.
      *
      * @param <T> the character sequence type
      * @param chars  the character sequence to check, validated not null by this method
      * @return the validated character sequence (never {@code null} method for chaining)
      * @throws NullPointerException if the character sequence is {@code null}
      * @throws IllegalArgumentException if the character sequence is empty
      * @see #notEmpty(CharSequence, String, Object...)
      */
     public static <T extends CharSequence> T notEmpty(final T chars) {
         return notEmpty(chars, DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE);
     }
 
     /**
      * <p>Validates that the specified argument collection is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception
      * with the specified message.
      *
      * <pre>Validate.notEmpty(myCollection, "The collection must not be empty");</pre>
      *
      * @param <T> the collection type
      * @param collection  the collection to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated collection (never {@code null} method for chaining)
      * @throws NullPointerException if the collection is {@code null}
      * @throws IllegalArgumentException if the collection is empty
      * @see #notEmpty(Object[])
      */
     public static <T extends Collection<?>> T notEmpty(final T collection, final String message, final Object... values) {
         Objects.requireNonNull(collection, toSupplier(message, values));
         if (collection.isEmpty()) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
         return collection;
     }
 
     /**
      * Validate that the specified argument map is neither {@code null}
      * nor a size of zero (no elements); otherwise throwing an exception
      * with the specified message.
      *
      * <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
      *
      * @param <T> the map type
      * @param map  the map to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated map (never {@code null} method for chaining)
      * @throws NullPointerException if the map is {@code null}
      * @throws IllegalArgumentException if the map is empty
      * @see #notEmpty(Object[])
      */
     public static <T extends Map<?, ?>> T notEmpty(final T map, final String message, final Object... values) {
         Objects.requireNonNull(map, toSupplier(message, values));
         if (map.isEmpty()) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
         return map;
     }
 
     /**
      * Validate that the specified argument character sequence is
      * neither {@code null} nor a length of zero (no characters);
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
      *
      * @param <T> the character sequence type
      * @param chars  the character sequence to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated character sequence (never {@code null} method for chaining)
      * @throws NullPointerException if the character sequence is {@code null}
      * @throws IllegalArgumentException if the character sequence is empty
      * @see #notEmpty(CharSequence)
      */
     public static <T extends CharSequence> T notEmpty(final T chars, final String message, final Object... values) {
         Objects.requireNonNull(chars, toSupplier(message, values));
         if (chars.length() == 0) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
         return chars;
     }
 
     /**
      * <p>Validates that the specified argument array is neither {@code null}
      * nor a length of zero (no elements); otherwise throwing an exception.
      *
      * <pre>Validate.notEmpty(myArray);</pre>
      *
      * <p>The message in the exception is &quot;The validated array is
      * empty&quot;.
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @return the validated array (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if the array is empty
      * @see #notEmpty(Object[], String, Object...)
      */
     public static <T> T[] notEmpty(final T[] array) {
         return notEmpty(array, DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE);
     }
 
     /**
      * <p>Validates that the specified argument array is neither {@code null}
      * nor a length of zero (no elements); otherwise throwing an exception
      * with the specified message.
      *
      * <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated array (never {@code null} method for chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IllegalArgumentException if the array is empty
      * @see #notEmpty(Object[])
      */
     public static <T> T[] notEmpty(final T[] array, final String message, final Object... values) {
         Objects.requireNonNull(array, toSupplier(message, values));
         if (array.length == 0) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
         return array;
     }
 
     /**
      * Validates that the specified argument is not Not-a-Number (NaN); otherwise
      * throwing an exception.
      *
      * <pre>Validate.notNaN(myDouble);</pre>
      *
      * <p>The message of the exception is &quot;The validated value is not a
      * number&quot;.</p>
      *
      * @param value  the value to validate
      * @throws IllegalArgumentException if the value is not a number
      * @see #notNaN(double, String, Object...)
      * @since 3.5
      */
     public static void notNaN(final double value) {
         notNaN(value, DEFAULT_NOT_NAN_EX_MESSAGE);
     }
 
     /**
      * Validates that the specified argument is not Not-a-Number (NaN); otherwise
      * throwing an exception with the specified message.
      *
      * <pre>Validate.notNaN(myDouble, "The value must be a number");</pre>
      *
      * @param value  the value to validate
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message
      * @throws IllegalArgumentException if the value is not a number
      * @see #notNaN(double)
      * @since 3.5
      */
     public static void notNaN(final double value, final String message, final Object... values) {
         if (Double.isNaN(value)) {
             throw new IllegalArgumentException(getMessage(message, values));
         }
     }
 
     /**
      * Validate that the specified argument is not {@code null};
      * otherwise throwing an exception.
      *
      * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
      *
      * <p>The message of the exception is &quot;The validated object is
      * null&quot;.
      *
      * @param <T> the object type
      * @param object  the object to check
      * @return the validated object (never {@code null} for method chaining)
      * @throws NullPointerException if the object is {@code null}
      * @see #notNull(Object, String, Object...)
      * @deprecated Use {@link Objects#requireNonNull(Object)}.
      */
     @Deprecated
     public static <T> T notNull(final T object) {
         return notNull(object, DEFAULT_IS_NULL_EX_MESSAGE);
     }
 
     /**
      * Validate that the specified argument is not {@code null};
      * otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
      *
      * @param <T> the object type
      * @param object  the object to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message
      * @return the validated object (never {@code null} for method chaining)
      * @throws NullPointerException if the object is {@code null}
      * @see Objects#requireNonNull(Object)
      */
     public static <T> T notNull(final T object, final String message, final Object... values) {
         return Objects.requireNonNull(object, toSupplier(message, values));
     }
 
     private static Supplier<String> toSupplier(final String message, final Object... values) {
         return () -> getMessage(message, values);
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * collection; otherwise throwing an exception.
      *
      * <pre>Validate.validIndex(myCollection, 2);</pre>
      *
      * <p>If the index is invalid, then the message of the exception
      * is &quot;The validated collection index is invalid: &quot;
      * followed by the index.</p>
      *
      * @param <T> the collection type
      * @param collection  the collection to check, validated not null by this method
      * @param index  the index to check
      * @return the validated collection (never {@code null} for method chaining)
      * @throws NullPointerException if the collection is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(Collection, int, String, Object...)
      * @since 3.0
      */
     public static <T extends Collection<?>> T validIndex(final T collection, final int index) {
         return validIndex(collection, index, DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE, Integer.valueOf(index));
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * character sequence; otherwise throwing an exception.
      *
      * <pre>Validate.validIndex(myStr, 2);</pre>
      *
      * <p>If the character sequence is {@code null}, then the message
      * of the exception is &quot;The validated object is
      * null&quot;.</p>
      *
      * <p>If the index is invalid, then the message of the exception
      * is &quot;The validated character sequence index is invalid: &quot;
      * followed by the index.</p>
      *
      * @param <T> the character sequence type
      * @param chars  the character sequence to check, validated not null by this method
      * @param index  the index to check
      * @return the validated character sequence (never {@code null} for method chaining)
      * @throws NullPointerException if the character sequence is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(CharSequence, int, String, Object...)
      * @since 3.0
      */
     public static <T extends CharSequence> T validIndex(final T chars, final int index) {
         return validIndex(chars, index, DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE, Integer.valueOf(index));
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * collection; otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.validIndex(myCollection, 2, "The collection index is invalid: ");</pre>
      *
      * <p>If the collection is {@code null}, then the message of the
      * exception is &quot;The validated object is null&quot;.</p>
      *
      * @param <T> the collection type
      * @param collection  the collection to check, validated not null by this method
      * @param index  the index to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated collection (never {@code null} for chaining)
      * @throws NullPointerException if the collection is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(Collection, int)
      * @since 3.0
      */
     public static <T extends Collection<?>> T validIndex(final T collection, final int index, final String message, final Object... values) {
         Objects.requireNonNull(collection, "collection");
         if (index < 0 || index >= collection.size()) {
             throw new IndexOutOfBoundsException(getMessage(message, values));
         }
         return collection;
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * character sequence; otherwise throwing an exception with the
      * specified message.
      *
      * <pre>Validate.validIndex(myStr, 2, "The string index is invalid: ");</pre>
      *
      * <p>If the character sequence is {@code null}, then the message
      * of the exception is &quot;The validated object is null&quot;.</p>
      *
      * @param <T> the character sequence type
      * @param chars  the character sequence to check, validated not null by this method
      * @param index  the index to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated character sequence (never {@code null} for method chaining)
      * @throws NullPointerException if the character sequence is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(CharSequence, int)
      * @since 3.0
      */
     public static <T extends CharSequence> T validIndex(final T chars, final int index, final String message, final Object... values) {
         Objects.requireNonNull(chars, "chars");
         if (index < 0 || index >= chars.length()) {
             throw new IndexOutOfBoundsException(getMessage(message, values));
         }
         return chars;
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * array; otherwise throwing an exception.
      *
      * <pre>Validate.validIndex(myArray, 2);</pre>
      *
      * <p>If the array is {@code null}, then the message of the exception
      * is &quot;The validated object is null&quot;.</p>
      *
      * <p>If the index is invalid, then the message of the exception is
      * &quot;The validated array index is invalid: &quot; followed by the
      * index.</p>
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @param index  the index to check
      * @return the validated array (never {@code null} for method chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(Object[], int, String, Object...)
      * @since 3.0
      */
     public static <T> T[] validIndex(final T[] array, final int index) {
         return validIndex(array, index, DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE, Integer.valueOf(index));
     }
 
     /**
      * Validates that the index is within the bounds of the argument
      * array; otherwise throwing an exception with the specified message.
      *
      * <pre>Validate.validIndex(myArray, 2, "The array index is invalid: ");</pre>
      *
      * <p>If the array is {@code null}, then the message of the exception
      * is &quot;The validated object is null&quot;.</p>
      *
      * @param <T> the array type
      * @param array  the array to check, validated not null by this method
      * @param index  the index to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @return the validated array (never {@code null} for method chaining)
      * @throws NullPointerException if the array is {@code null}
      * @throws IndexOutOfBoundsException if the index is invalid
      * @see #validIndex(Object[], int)
      * @since 3.0
      */
     public static <T> T[] validIndex(final T[] array, final int index, final String message, final Object... values) {
         Objects.requireNonNull(array, "array");
         if (index < 0 || index >= array.length) {
             throw new IndexOutOfBoundsException(getMessage(message, values));
         }
         return array;
     }
 
     /**
      * Validate that the stateful condition is {@code true}; otherwise
      * throwing an exception. This method is useful when validating according
      * to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>
      * Validate.validState(field &gt; 0);
      * Validate.validState(this.isOk());</pre>
      *
      * <p>The message of the exception is &quot;The validated state is
      * false&quot;.</p>
      *
      * @param expression  the boolean expression to check
      * @throws IllegalStateException if expression is {@code false}
      * @see #validState(boolean, String, Object...)
      * @since 3.0
      */
     public static void validState(final boolean expression) {
         if (!expression) {
             throw new IllegalStateException(DEFAULT_VALID_STATE_EX_MESSAGE);
         }
     }
 
     /**
      * Validate that the stateful condition is {@code true}; otherwise
      * throwing an exception with the specified message. This method is useful when
      * validating according to an arbitrary boolean expression, such as validating a
      * primitive number or using your own custom validation expression.
      *
      * <pre>Validate.validState(this.isOk(), "The state is not OK: %s", myObject);</pre>
      *
      * @param expression  the boolean expression to check
      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
      * @param values  the optional values for the formatted exception message, null array not recommended
      * @throws IllegalStateException if expression is {@code false}
      * @see #validState(boolean)
      * @since 3.0
      */
     public static void validState(final boolean expression, final String message, final Object... values) {
         if (!expression) {
             throw new IllegalStateException(getMessage(message, values));
         }
     }
 
     /**
      * Constructs a new instance. This class should not normally be instantiated.
      */
     public Validate() {
     }
 }