Package de.unruh.javapatterns

Class Match

java.lang.Object
de.unruh.javapatterns.Match
public final class Match
extends java.lang.Object
Functions for invoking pattern matches. This is an uninstantiable class containing only static members.

It contains functions for applying patterns to a given value and executing code when of them matches.

The general pattern for executing a pattern match is: 

 result = match(value, withCase(pattern1, action1), withCase(pattern2, action2), ...)
Here value is the value to pattern match, and pattern1, ... are the patterns to try and apply. For the first pattern that matches, the corresponding action is executed (with access to the values captured by the pattern, see Capture), and match returns the return value of that action. An action is a lambda expression of the form () -> ..., returning either some value or void. If the action invokes Pattern.reject(), matching continues with the next pattern. If no pattern matches, match throws a MatchException.

The patterns are of type Pattern, see there for explanations how to specify patterns.

For better readability, the match can also be written as 

 result = match(value, pattern1, action1, pattern2, action2, ...)
with at most 22 pattern/action pairs. (This is enabled via a large number of helper functions in this class, all called match. These helper functions are elided from this API documentation to keep things readable.)

  • Method Summary

    Modifier and Type Method Description
    static <In,​ Return,​ Exn extends java.lang.Throwable>
    Return    		 match​(In value, @NotNull Case<In,​Return,​Exn>... cases)
    Performs a pattern match.
    static <In,​ Exn extends java.lang.Throwable>
    Case<In,​java.lang.Void,​Exn>    		 withCase​(@NotNull Pattern<? super In> pattern, @NotNull MatchRunnable<Exn> action)
    Constructs a Case object from a pattern and lambda expression returning void.
    static <In,​ Return,​ Exn extends java.lang.Throwable>
    Case<In,​Return,​Exn>    		 withCase​(@NotNull Pattern<? super In> pattern, @NotNull MatchSupplier<? extends Return,​Exn> action)
    Constructs a Case object from a pattern and lambda expression.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • withCase

      @Contract(pure=true, value="_, _ -> new") public static <In,​ Return,​ Exn extends java.lang.Throwable> Case<In,​Return,​Exn> withCase​(@NotNull @NotNull Pattern<? super In> pattern, @NotNull @NotNull MatchSupplier<? extends Return,​Exn> action)
      Constructs a Case object from a pattern and lambda expression. Used as an argument to match(Object, Case[]).
      Type Parameters:
      In - Type of the value to be pattern matched.
      Exn - Exceptions that the action might throw (PatternMatchReject does not need to be declared here even if Pattern.reject() is used.)
      Return - Return type of the action
      Parameters:
      pattern - Pattern to apply in a match
      action - Action to perform when the pattern matches. Usually given as a lambda expression. If the lambda expression returns void, use withCase(Pattern, MatchRunnable).

    • withCase

      @Contract(pure=true, value="_, _ -> new") public static <In,​ Exn extends java.lang.Throwable> Case<In,​java.lang.Void,​Exn> withCase​(@NotNull @NotNull Pattern<? super In> pattern, @NotNull @NotNull MatchRunnable<Exn> action)
      Constructs a Case object from a pattern and lambda expression returning void.
      Type Parameters:
      In - Type of the value to be pattern matched.
      Exn - Exceptions that the action might throw (PatternMatchReject does not need to be declared here even if Pattern.reject() is used.)
      Parameters:
      pattern - Pattern to apply in a match
      action - Action to perform when the pattern matches. Usually given as a lambda expression. Must return void, use withCase(Pattern, MatchSupplier) otherwise.
      Throws:
      InvalidPatternMatch - if a capture variable is assigned twice, or read while unassigned, or some other invalid operation occurs in the pattern match (a match failure does not count as an invalid operation).

    • match

      @SafeVarargs public static <In,​ Return,​ Exn extends java.lang.Throwable> Return match​(@Nullable In value, @NotNull @NotNull Case<In,​Return,​Exn>... cases) throws Exn extends java.lang.Throwable, MatchException
      Performs a pattern match. Applies each of the cases in sequence to @{code value}, and returns the return value of the first successful case.
      Type Parameters:
      In - Type of the value to be pattern matched.
      Exn - Exceptions that the action might throw (PatternMatchReject does not need to be declared here even if Pattern.reject() is used.)
      Return - Return type of the action
      Parameters:
      value - The value to be pattern matched
      cases - Cases to try. Each case consists of a pattern and an action that is executed in case of a successful match. See Case.
      Throws:
      Exn - if the action throws it
      MatchException - if none of the cases match