Package de.unruh.javapatterns

Class Patterns

java.lang.Object

de.unruh.javapatterns.Patterns

public final class Patterns
extends java.lang.Object

This class contains static methods for constructing a number of different patterns.

(This class itself cannot be instantiated.)

Throughout the documentation of the patterns in this class, we refer to the value that is matched against the pattern simply the "matched value".

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Patterns.Instance<U>	Pattern that matches if the matched value has a specific type U.

Field Summary

Fields

Modifier and Type	Field	Description
static @NotNull Pattern<java.lang.Object>	Any	Pattern that matches everything (including null).
static @NotNull Pattern<java.lang.Object>	Null	Pattern that matches only null.

Method Summary

Modifier and Type	Method	Description
static <T> @NotNull Pattern<T>	And(@NotNull Pattern<? super T>... patterns)	Pattern that combined several subpatterns that all need to be match.
static <T> @NotNull Pattern<T[]>	Array(@NotNull Pattern<? super T>... patterns)	Pattern that matches an array.
static <U> @NotNull Pattern<java.lang.Object>	Instance(@NotNull java.lang.Class<U> clazz, @NotNull Pattern<? super U> pattern)	Pattern that matches if the matched value has a specific type U.
static <T> @NotNull Pattern<T>	Is(@NotNull Capture<T> expected)	Pattern that matches if the matched value equals the value in the captured variable expected.
static <T> @NotNull Pattern<T>	Is(@NotNull java.util.function.Predicate<? super T> predicate)	Pattern that matches if the matched value satisfies a predicate.
static <T> @NotNull Pattern<T>	Is(@NotNull java.util.function.Supplier<T> expected)	Pattern that matches if the matched value equals the value computed by expected.
static <T> @NotNull Pattern<T>	Is(T expected)	Pattern that matches if the matched value equals expected.
static <T> @NotNull Pattern<T>	NoMatch(@NotNull Pattern<? super T> pattern)
static <T> @NotNull Pattern<T>	NotNull(@NotNull Pattern<? super T> pattern)	Pattern that matches non-null values.
static <T> @NotNull Pattern<T>	Or(@NotNull Pattern<? super T>... patterns)	Pattern that combined several subpatterns of which one needs to match.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Any

@NotNull
public static final @NotNull Pattern<java.lang.Object> Any

Pattern that matches everything (including null).

Null

@NotNull
public static final @NotNull Pattern<java.lang.Object> Null

Pattern that matches only null.

Method Detail

Is

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> Is(@Nullable
                                         T expected)

Pattern that matches if the matched value equals expected.

Equality is tested using Objects.equals(java.lang.Object, java.lang.Object). If a different equality test is required, use Is(Predicate).

Since expected is executed during pattern construction, expected cannot depend on the value of capture variables. Use Is(Supplier) if delayed execution is desired. (Or Is(Capture) to match a single captured value.)

Type Parameters:

T - type of the matched value

Parameters:

expected - the value that the matched value is compared to

Returns:

the pattern

Is

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> Is(@NotNull
                                         @NotNull java.util.function.Supplier<T> expected)

Pattern that matches if the matched value equals the value computed by expected.

Equality is tested using Objects.equals(java.lang.Object, java.lang.Object). If a different equality test is required, use Is(Predicate).

Type Parameters:

T - type of the matched value

Parameters:

expected - lambda expression computing the expected value

Returns:

the pattern

Is

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> Is(@NotNull
                                         @NotNull Capture<T> expected)

Pattern that matches if the matched value equals the value in the captured variable expected.

Equality is tested using Objects.equals(java.lang.Object, java.lang.Object). If a different equality test is required, use Is(Predicate).

Type Parameters:

T - type of the matched value

Parameters:

expected - lambda expression computing the expected value

Returns:

the pattern

Is

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> Is(@NotNull
                                         @NotNull java.util.function.Predicate<? super T> predicate)

Pattern that matches if the matched value satisfies a predicate.

Type Parameters:

T - type of the matched value

Parameters:

predicate - lambda expression testing whether the matched value should be accepted

Returns:

the pattern

NotNull

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> NotNull(@NotNull
                                              @NotNull Pattern<? super T> pattern)

Pattern that matches non-null values.

This pattern succeeds if the matched value is not null, and the subpattern pattern matches the matched value.

Typical use cases would be NotNull(Any) or NotNull(x) for a capture variable x. Both forms would match any non-null value, and the latter assigns it to the capture x.

Type Parameters:

T - type of the matched value

Parameters:

pattern - the subpattern that also needs to match the matched value

Returns:

the pattern that matched only non-null values

And

@NotNull
@Contract(pure=true,
          value="_ -> new")
@SafeVarargs
public static <T> @NotNull Pattern<T> And(@NotNull
                                          @NotNull Pattern<? super T>... patterns)

Pattern that combined several subpatterns that all need to be match.

This pattern matches if all subpatterns in patterns match the matched value.

All captures assigned by the subpatterns will be assigned by this pattern. Consequently, the subpatterns must not assign the same captures.

Type Parameters:

T - type of the matched value

Parameters:

patterns - subpatterns that all should match

Returns:

the combined pattern

Or

@NotNull
@Contract(pure=true,
          value="_ -> new")
@SafeVarargs
public static <T> @NotNull Pattern<T> Or(@NotNull
                                         @NotNull Pattern<? super T>... patterns)

Pattern that combined several subpatterns of which one needs to match.

This pattern matches if at least one subpattern in patterns matches the matched value.

Only the captures assigned by the first matching subpattern will be assigned by this pattern. Consequently, the subpatterns are allowed to assign the same values.

Type Parameters:

T - type of the matched value

Parameters:

patterns - subpatterns that all should match

Returns:

the combined pattern

Instance

@NotNull
@Contract(pure=true,
          value="_, _ -> new")
public static <U> @NotNull Pattern<java.lang.Object> Instance(@NotNull
                                                              @NotNull java.lang.Class<U> clazz,
                                                              @NotNull
                                                              @NotNull Pattern<? super U> pattern)

Pattern that matches if the matched value has a specific type U.

This pattern matches if the matched value has type U (runtime type check) and the subpattern pattern matches as well.

Example: Instance(String.class, x) will match a string and assign it to the capture x which can be of type Capture<String>.

If the type we want to check is a generic type, this pattern is somewhat problematic: For example, if we have a capture x of type Capture<List<String>>, then Instance(List.class, x) will not type check because it expects x to match values of raw type List, not of type List<String>. See Instance for a variant of this pattern suitable for that case.

Type Parameters:

U - the type that the matched value should have

Parameters:

clazz - class tag for type U

pattern - the subpattern that also need to match the matched value after being type cast

Returns:

the type checking pattern

NoMatch

@NotNull
@Contract(pure=true,
          value="_ -> new")
public static <T> @NotNull Pattern<T> NoMatch(@NotNull
                                              @NotNull Pattern<? super T> pattern)

Array

@NotNull
@Contract(pure=true,
          value="_ -> new")
@SafeVarargs
public static <T> @NotNull Pattern<T[]> Array(@NotNull
                                              @NotNull Pattern<? super T>... patterns)

Pattern that matches an array.

The pattern matches if the matched value is an array of length patterns.length, and the i-th element of the matched value matches the i-th pattern in patterns.

All captures assigned by the subpatterns patterns will be assigned by this pattern. Consequently, the subpatterns must assign distinct captures.

Type Parameters:

T - the element type of the array (i.e., the matched value has type T[])

Parameters:

patterns - the patterns for the array elements

Returns:

the array pattern