Towards member patterns

Recovering construction arguments

Deconstruction patterns are the dual of constructors; where a constructor takes N arguments and aggregates them into an object, a deconstruction pattern takes an aggregate and decomposes it into its components. Constructors are unusual in that they are instance behavior (they have an implicit this argument), but are not inherited; deconstruction patterns are the same. For deconstruction patterns (but not for all instance patterns), the match candidate is always the receiver. Tentatively, we’ve decided that deconstruction patterns are always unconditional; that a deconstruction pattern for class Foo should match any instance of Foo. At the use site, deconstruction patterns use the same syntax as record patterns:

case Point(int x, int y):

Just as constructors can be overloaded, so can deconstruction patterns. However, the reasons we might overload deconstruction patterns are slightly different than for constructors, and so it may well be the case that we end up with fewer overloads of deconstruction patterns than we do of constructors. Constructors often form telescoping sets, both for reasons of syntactic convenience at the use site (fewer arguments to specify) and to avoid brittleness (clients can let the class implementation pick the defaults rather than hard-coding them.) This motivation is less pronounced for deconstruction patterns (unwanted bindings can be ignored with _), so it is quite possible that authors will choose to have one deconstruction pattern overload per telescoping constructor set, rather than one per constructor.

There is no requirement for deconstruction patterns to expose the exact same API as constructors, but we expect this will be common, at least for classes for which the construction process is effectively an aggregation operation on the constructor arguments.

Recovering static factory arguments

Not all classes want to expose their constructors; sometimes classes prefer to expose static factories instead. In this case, the class should be able to expose corresponding static patterns as well.

For a class like Optional, which exposes factories Optional::of and Optional::empty, the object state incorporates not only the factory arguments, but which factory was chosen. Accordingly, it makes sense to deconstruct the object in the same way:

switch (optional) {
    case Optional.of(var payload): ...
    case Optional.empty(): ...
}

Such patterns are necessarily conditional, asking the Pattern Question: “could this Optional have come from the Optional::of factory, and if so, with what argument?” Static patterns, like static methods, lack a receiver, so this is not defined in the body of a static pattern. However, we will need a way to denote the match candidate, so its state can be examined by the pattern body.

Another feature of static methods is that they can be used to put a factory for a class C in another class, whether one in the same maintenance domain (such as the Collections) or in some other package. This feature is shared by static patterns.

Conversions and queries

Another application for static patterns is the dual of static methods for conversions. For a static method like Integer::toString, which converts an int to its String representation, a corresponding static pattern Integer::toString can ask the Pattern Question: “could this String have come from converting an integer to String, and if so, what integer”.

Some groups of query methods in existing APIs are patterns in disguise. The class java.lang.Class has a pair of instance methods, Class::isArray and Class::getComponentType, that work together to determine if the Class describes an array type, and if so, provide its component type. This question is much better framed as a single pattern:

case Class.arrayClass(var componentType):

The two existing methods are made more complicated by their relationship to each other; Class::getComponentType has a precondition (the Class must describe an array type) and therefore has to specify and implement what to do if the precondition fails, and the relationship between the methods is captured only in documentation. By combining them into a single pattern, it become impossible to misuse (because of the inherent conditionality of patterns) and easier to understand (because it can all be documented in one place.)

This hypothetical Class::arrayClass pattern also has a sensible dual as a factory method:

static<T> Class<T[]> arrayClass(Class<T> componentType)

which produces the array Class for the array type whose component type is provided. An API need not provide both directions of a conversion, but if it does, the two generally strengthen each other. This method/pattern pair could be either static or instance members, depending on API design choice.

Another form of “conversion” method / pattern pair, even though both types are the same, is “power of two”. A powerOfTwo method takes an exponent and returns the resulting power of two; a powerOfTwo pattern asks if its match candidate is a power of two, and if so, binds the base-two logarithm.

Numeric conversions

As Project Valhalla gives us the ability to declare new numeric types, we will want to be able to convert these new types to other numeric types. For unconditional conversions (such as widening half-float to float), an ordinary method will suffice:

float widen(HalfFloat f);

But the reverse is unlikely to be unconditional; narrowing conversions can fail if the value cannot be represented in the narrower type. This is better represented as a pattern which asks the Pattern Question: “could this float have come from widening a HalfFloat, and if so, tell me what HalfFloat that is.” A widening conversion (or boxing conversion) is best represented by a pair of members, an ordinary method for the unconditional direction, and a pattern for the conditional direction.

Conditional extraction

Some operations, such as matching a string to a regular expression with capture groups, are pattern matches in disguise. We should be able to take a regular expression R and match against it with instanceof or switch, binding capture groups (using varargs patterns) if it matches.

Patterns as inverse methods and constructors

One way to frame patterns in the object model is as inverse constructors and inverse methods. For purposes of this document, I will use an illustrative syntax that directly evokes this duality (but remember, we’re not discussing syntax now):

class Point {
    final int x, y;

    // Constructor
    Point(int x, int y) { ... }

    // Deconstruction pattern
    inverse Point(int x, int y) { ... }
}

class Optional<T> {
    // Static factories
    static<T> Optional<T> of(T t) { ... }
    static<T> Optional<T> empty() { ... }

    // Static patterns
    static<T> inverse Optional<T> of(T t) { ... }
    static<T> inverse Optional<T> empty() { ... }
}

Point has a constructor and an inverse constructor (deconstruction pattern) for the external representation (int x, int y); in an inverse constructor, the binding list appears where the parameter list does in the constructor. Optional<T> has static factories and corresponding patterns for empty and of. As with inverse constructors, the binding list of a pattern appears in the position that the parameters appear in a method declaration; additionally, the match candidate type appears in the position that the return value appears in a method declaration. In both cases, the declaration site and use site of the pattern uses the same syntax.

In the body of an inverse constructor or method, we need to be able to talk about the match candidate. In this model, the match candidate has a type determined by the declaration (for an inverse constructor, the class; for an inverse method, the type specified in the “return position” of the inverse method declaration), and there is a predefined context variable (e.g., that) that refers to the match candidate. For inverse constructors, the receiver (this) is aliased to the match candidate (that), but not necessarily so for inverse methods.

Do all methods potentially have inverses?

We’ve seen examples of constructors, static methods, and instance methods that have sensible inverses, but not all methods do. For example, methods that operate primarily by side effects (such as mutative methods like setters or List::add) are not suitable candidates for inverses. Similarly, pure functions that “co-mingle” their arguments (such as arithmetic operators) are also not suitable candidates for inverses, because the ingredients to the operation typically can’t be recovered from the result (i.e., 4 could be the result of plus(2, 2) or plus(1, 3)).

Intuitively, the methods that are invertible are the ones that are aggregative. The constructor of a (well-behaved) record is aggregative, since all the information passed to the constructor is preserved in the result. Factories like Optional::of are similarly aggregative, as are non-lossy conversions such as widening or boxing conversions.

Ideally, an aggregation operation and its corresponding inverse form an embedding projection pair between the aggregate and a component space. Intuitively, an embedding-projection pair is an algebraic structure defined by a pair of functions between two sets such that composing in one direction (embed-then-project) is an identity, and composing in the other direction (project-then-embed) is a well-behaved approximation.

Conversions

Conversion methods are a frequent candidate for inversion. We already have

// Integer.java
static String toString(int i) { ... }

to which the obvious inverse is

static inverse String toString(int i) { ... }

and we can inspect a string to see if it is the string representation of an integer with

if (s instanceof Integer.toString(int i)) { ... }

This composes nicely with deconstruction patterns; if we have a Box<String> and want to ask whether the contained string is really the string representation of an integer, we can ask:

case Box(Integer.toString(int i)):

which conveniently looks just like the composition of constructors or factories used to create such an instance (new Box(Integer.toString(3))).

When it comes to user-definable numeric conversions, the most likely strategy involves combining related operators in a single witness object. For example, numeric conversion might be modeled as:

interface NumericConversion<FROM, TO> {
    TO convert(FROM from);
    inverse TO convert(FROM from);
}

which reflects the fact that conversion is total in one direction (widening, boxing) and conditional in the other (narrowing, unboxing.)

Regular expression matching

Regular expressions are a form of ad-hoc pattern; a given string might match a given regex, or not, and if it does, it might product multiple bindings (the capture groups.) It would be nice to be able to express regular expression matches as ordinary pattern matches.

Conveniently, we already have an object representation of regular expressions — java.util.Pattern. Which is an ideal place to put an instance pattern:

// varargs pattern
public inverse String match(String... groups) {
    Matcher m = matcher(that);    // *that* is the match candidate
    if (m.matches())              // receiver for matcher() is the Pattern
        __yield IntStream.range(1, m.groupCount())
                            .map(m::group)
                            .toArray(String[]::new);
}

And now, we want to express “does string s match any of these regular expressions”:

static final Pattern As = Pattern.compile("([aA]*)");
static final Pattern Bs = Pattern.compile("([bB]*)");
static final Pattern Cs = Pattern.compile("([cC]*)");

...

switch (aString) {
    case As.match(String as) -> ...
    case Bs.match(String bs) -> ...
    case Cs.match(String cs) -> ...
    ...
}

Essentially, j.u.r.Pattern becomes a pattern object, where the state of the object is used to determine whether or not it matches any given input. (There is nothing stopping a class from having multiple patterns, just as it can have multiple methods.)