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 Details

    • 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 Details

    • 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