Package de.unruh.javapatterns

Class Capture<T>

java.lang.Object
de.unruh.javapatterns.Pattern<T>
de.unruh.javapatterns.Capture<T>
Type Parameters:
T - The type of the value captured by this capture variable
public final class Capture<T>
extends Pattern<T>
A capturing variable in a pattern match.

A Capture<T> is a pattern that matches everything and, when matched, stores the value that it matched. Within a single pattern match, the capture must not be matched twice. (It is, however, possible to have the same capture occur in mutually exclusive parts of the pattern, see, e.g., Patterns.Or(de.unruh.javapatterns.Pattern<? super T>...).)

The value that was assigned to the capture x can be read using x.v(). This is possible both in the action of a pattern match (see Case) and in the pattern itself. This makes it possible to make parts of the pattern depend on values that have been captured already. (E.g., Patterns.Array(de.unruh.javapatterns.Pattern<? super T>...)(x, Patterns.Is(T)(x)) matches only arrays with two identical entries.)

Captures need to be declared before the pattern match with a given type, e.g., 

 Capture<String> x = Capture("x");
 ...
 match(value, ... patterns using x ...)
However, the value of the capture is local to one case of the pattern match. (So, logically, a capture is a local variable within the case.) A capture can be used in several cases in the same match, or in different matches, but it is not thread-safe (i.e., not in concurrent matches).

  • Method Summary

    Modifier and Type Method Description
    void apply​(@NotNull MatchManager mgr, T value)
    Performs the pattern match.
    boolean isAssigned()
    Returns whether this capture has been assigned.
    java.lang.String toString()
    Should give a human readable representation of this pattern.
    T v()
    The current value of the capture.

    Methods inherited from class de.unruh.javapatterns.Pattern

    capture, reject

    Methods inherited from class java.lang.Object

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

  • Method Details

    • toString

      public java.lang.String toString()
      Description copied from class: Pattern
      Should give a human readable representation of this pattern. Used in error messages.
      Specified by:
      toString in class Pattern<T>

    • isAssigned

      public boolean isAssigned()
      Returns whether this capture has been assigned.

    • v

      @Contract(pure=true) public T v()
      The current value of the capture.
      Throws:
      InvalidPatternMatch - if the capture has not been assigned in the current pattern

    • apply

      public void apply​(@NotNull @NotNull MatchManager mgr, @Nullable T value)
      Description copied from class: Pattern
      Performs the pattern match. See the class documentation.

      Must only be invoked from withing an apply. (I.e., a pattern may invoke apply on its subpatterns from within its own apply method.)

      Specified by:
      apply in class Pattern<T>
      Parameters:
      mgr - the MatchManager that manages the life-cycle of the captures in this pattern match. Must be passed to subpatterns and not be kept after the termination of the invocation of apply(...).
      value - the value to be pattern-matched