If the precondition is not met, the Preconditions method throws an unchecked exception
of a specified type, which helps the method in which the exception was thrown communicate that
its caller has made a mistake. This allows constructs such as
public static double sqrt(double value) {
if (value < 0) {
throw new IllegalArgumentException("input is negative: " + value);
}
// calculate square root
}
to be replaced with the more compact
public static double sqrt(double value) {
checkArgument(value >= 0, "input is negative: %s", value);
// calculate square root
}
so that a hypothetical bad caller of this method, such as:
void exampleBadCaller() {
double d = sqrt(-1.0);
}
would be flagged as having called sqrt() with an illegal argument.
Avoid passing message arguments that are expensive to compute; your code will always compute them, even though they usually won't be needed. If you have such arguments, use the conventional if/throw idiom instead.
Depending on your message arguments, memory may be allocated for boxing and varargs array creation. However, the methods of this class have a large number of overloads that prevent such allocations in many common cases.
The message string is not formatted unless the exception will be thrown, so the cost of the string formatting itself should not be a concern.
As with any performance concerns, you should consider profiling your code (in a production environment if possible) before spending a lot of effort on tweaking a particular element.
Not every type of precondition failure is supported by these methods. Continue to throw
standard JDK exceptions such as java. or UnsupportedOperationException in the situations they are intended for.
It is of course possible to use the methods of this class to check for invalid conditions
which are not the caller's fault. Doing so is not recommended because it is
misleading to future readers of the code and of stack traces. See Conditional failures
explained in the Guava User Guide for more advice. Notably, Verify offers assertions
similar to those in this class for non-precondition checks.
java.util.Objects.requireNonNull()Projects which use com.google.common should generally avoid the use of java.. Instead, use whichever of checkNotNull(Object) or Verify#verifyNotNull(Object) is appropriate to the situation.
(The same goes for the message-accepting overloads.)
%s is supportedPreconditions uses Strings#lenientFormat to format error message template
strings. This only supports the "%s" specifier, not the full range of java. specifiers. However, note that if the number of arguments does not match the
number of occurrences of "%s" in the format string, Preconditions will still
behave as expected, and will still include all argument values in the error message; the message
will simply not be formatted exactly as intended.
See the Guava User Guide on using Preconditions.
| Modifier and Type | Class and Description |
|---|---|
| private static interface |
| Access | Constructor and Description |
|---|---|
| private |
| Modifier and Type | Method and Description |
|---|---|
| private static String | |
| private static String | |
| private static String | |
| public static void | checkArgument(boolean
a boolean expression expression)Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean
a boolean expression expression, Object the exception message to use if the check fails; will be converted to a
string using errorMessage)String#valueOf(Object)Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean
a boolean expression expression, String a template for the exception message should the check fail. The
message is formed by replacing each errorMessageTemplate, @Nullable Object... %s placeholder in the template with an
argument. These are matched by position - the first %s gets errorMessageArgs[0], etc. Unmatched arguments will be appended to the formatted message in
square braces. Unmatched placeholders will be left as-is.the arguments to be substituted into the message template. Arguments
are converted to strings using errorMessageArgs)String#valueOf(Object).Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, char p1)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, int p1)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, long p1)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, char p1, char p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, char p1, int p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, char p1, long p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, char p1, Object p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, int p1, char p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, int p1, int p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, int p1, long p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, int p1, Object p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, long p1, char p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, long p1, int p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, long p1, long p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, long p1, Object p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1, char p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1, int p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1, long p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1, Object p2)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | checkArgument(boolean expression, String errorMessageTemplate, Object p1, Object p2, Object p3)
Ensures the truth of an expression involving one or more parameters to the calling method. |
| public static void | |
| public static int | Returns: the value ofindexa user-supplied index identifying an element of an array, list or string index, int the size of that array, list or string size)Ensures that |
| public static int | Returns: the value ofindexa user-supplied index identifying an element of an array, list or string index, int the size of that array, list or string size, String the text to use to describe this index in an error message desc)Ensures that |
| public static <T> T | Returns: the non-null reference that was validatedan object reference reference)Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | Returns: the non-null reference that was validatedan object reference reference, Object the exception message to use if the check fails; will be converted to a
string using errorMessage)String#valueOf(Object)Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | Returns: the non-null reference that was validatedan object reference reference, String a template for the exception message should the check fail. The
message is formed by replacing each errorMessageTemplate, @Nullable Object... %s placeholder in the template with an
argument. These are matched by position - the first %s gets errorMessageArgs[0], etc. Unmatched arguments will be appended to the formatted message in
square braces. Unmatched placeholders will be left as-is.the arguments to be substituted into the message template. Arguments
are converted to strings using errorMessageArgs)String#valueOf(Object).Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, char p1)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, int p1)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, long p1)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, char p1, char p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, char p1, int p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, char p1, long p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, char p1, Object p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, int p1, char p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, int p1, int p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, int p1, long p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, int p1, Object p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, long p1, char p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, long p1, int p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, long p1, long p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, long p1, Object p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1, char p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1, int p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1, long p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1, Object p2)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | checkNotNull(T reference, String errorMessageTemplate, Object p1, Object p2, Object p3)
Ensures that an object reference passed as a parameter to the calling method is not null. |
| public static <T> T | |
| public static int | Returns: the value ofindexa user-supplied index identifying a position in an array, list or string index, int the size of that array, list or string size)Ensures that |
| public static int | Returns: the value ofindexa user-supplied index identifying a position in an array, list or string index, int the size of that array, list or string size, String the text to use to describe this index in an error message desc)Ensures that |
| public static void | checkPositionIndexes(int
a user-supplied index identifying a starting position in an array, list or string start, int a user-supplied index identifying an ending position in an array, list or string end, int the size of that array, list or string size)Ensures that |
| public static void | checkState(boolean
a boolean expression expression)Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean
a boolean expression expression, Object the exception message to use if the check fails; will be converted to a
string using errorMessage)String#valueOf(Object)Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean
a boolean expression expression, String a template for the exception message should the check fail. The
message is formed by replacing each errorMessageTemplate, @Nullable Object... %s placeholder in the template with an
argument. These are matched by position - the first %s gets errorMessageArgs[0], etc. Unmatched arguments will be appended to the formatted message in
square braces. Unmatched placeholders will be left as-is.the arguments to be substituted into the message template. Arguments
are converted to strings using errorMessageArgs)String#valueOf(Object).Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, char p1)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, int p1)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, long p1)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, char p1, char p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, char p1, int p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, char p1, long p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, char p1, Object p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, int p1, char p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, int p1, int p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, int p1, long p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, int p1, Object p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, long p1, char p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, long p1, int p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, long p1, long p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, long p1, Object p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1, char p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1, int p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1, long p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1, Object p2)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void | checkState(boolean expression, String errorMessageTemplate, Object p1, Object p2, Object p3)
Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method. |
| public static void |