Package com.github.tommyettinger.ds

Class Junction<T extends Comparable<T>>

java.lang.Object
com.github.tommyettinger.ds.Junction<T>
Type Parameters:
T - any Comparable type, such as String or any enum type
All Implemented Interfaces:
Term<T>, Comparable<Term<T>>
public class Junction<T extends Comparable<T>> extends Object implements Term<T>
Matches potentially more than one T value in different ways against a supplied Collection of T. This is inspired by the Junction type in Raku, but isn't totally equivalent. A Junction is the outermost parent of its hierarchy, and contains a Term node. Note, the equals(Object) method is meant to compare two Junctions to see if they are equivalent, while the match(Collection) method is how you actually check if this Junction matches a Collection.
A Junction mostly provides the same API as any other Term type, but does also supply negate(), which can be useful when you don't want to use remove(Collection) to remove matches, but instead want to filter and keep only terms that match this Junction. Note that negate() modifies this Junction in-place, so you might want to call negate() again after filtering.
There are several inner classes here, all Term types, which are used to actually implement the different types of logic for different types of matching. Junction.Leaf is simplest, and simply wraps a single T instance in a Term so it can be used with other Terms. Junction.Not negates matches on its Term item, so if == would make sense without a Not, != would be used instead with a Not. Junction.Any has multiple Terms, and will match if any of those Terms match. The contrasting type is Junction.All, which also has multiple Terms, but will match only if all of those Terms match. Lastly, Junction.One is special, and matches only if exactly one of its multiple Terms match. Any, All, and One are usually shown as taking two arguments, but can actually take 1 or more. This is important for One because it still requires exactly one match even if 10 arguments are given.
This provides a static convenience method, parse(String), that can parse a Junction of String from a String that may contain symbols for various terms, and/or parentheses. Given an input such as a|b|c, you get a Junction that will match any of "a", "b", or "c". Alternatively, an input such as (beef|turkey|veggie|warm melted cheese)&bun will match a Collection that contains "beef" as well as "bun", "turkey" as well as "bun", "veggie" as well as "bun", or "warm melted cheese" as well as "bun".

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Junction.All<T extends Comparable<T>>
    Takes one or more Terms and matches if all of those Terms match.
    static class 
    Junction.Any<T extends Comparable<T>>
    Takes one or more Terms and matches if any of those Terms match.
    static class 
    Junction.Leaf<T extends Comparable<T>>
    Simply matches a single T value, with no additional Terms involved.
    static class 
    Junction.Not<T extends Comparable<T>>
    Takes a Term and treats a case where it matches or doesn't match as the opposite.
    static class 
    Junction.One<T extends Comparable<T>>
    Takes one or more Terms and matches if exactly one of those Terms matches.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    Term<T>
    root
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Junction()
     
    Junction(Term<T> root)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    appendChildren(Collection<Term<T>> appending)
    If this Term has sub-Terms, which this calls children, calling appendChildren will take all children one level descendant from this and place them into appending, in undefined order.
    Term<T>
    canonicalize()
    Attempts to convert this Term and its children (recursively) to a single possible format for potentially many different internal representations.
    int
    compareTo(Term<T> o)
     
    final boolean
    equals(Object o)
    Used primarily to check for equality between Terms, not to act like Term.match(Collection).
    int
    hashCode()
     
    boolean
    match(Collection<? extends T> coll)
    A predicate that checks if the given Collection of T satisfies this Term.
    String
    name()
    Gets a plain-English name, typically all lower-case and one word, that describes what operation this Term performs.
    Junction<T>
    negate()
     
    static <T extends Comparable<T>>
    Junction<T>
    of(T item)
     
    static <T extends Comparable<T>>
    Junction<T>
    parse(com.github.tommyettinger.function.ObjToObjFunction<String,T> converter, String text)
    Parses all of text into one Junction of T, creating T items from String sections using converter.
    static <T extends Comparable<T>>
    Junction<T>
    parse(com.github.tommyettinger.function.ObjToObjFunction<String,T> converter, String text, int start, int end)
    Parses a substring of text into one Junction of T, creating T items from String sections using converter.
    static Junction<String>
    parse(String text)
    Parses the String text into one Junction of String.
    static Junction<String>
    parse(String text, int start, int end)
    Parses a substring of text into one Junction of String.
    Collection<T>
    remove(Collection<T> coll)
    Modifies the given Collection of T by removing any items that match this Term.
    char
    symbol()
    Gets a single char constant that represents this Term and determines its comparison order in the event of a tie.
    String
    toString()
    Slightly different from the normal toString() behavior, this may incorporate Term.name() but doesn't need to, and if it contains multiple parts, they should be separated by Term.symbol().
    T
    value()
    If this term has a T value (not inside another wrapping Term), this returns that value.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

  • Constructor Details

    • Junction

      public Junction()

    • Junction

      public Junction(Term<T> root)

  • Method Details

    • appendChildren

      public void appendChildren(Collection<Term<T>> appending)
      Description copied from interface: Term
      If this Term has sub-Terms, which this calls children, calling appendChildren will take all children one level descendant from this and place them into appending, in undefined order. Typically, after appendChildren() has been called at least once and doesn't need to append more, calling code will sort appending.
      Specified by:
      appendChildren in interface Term<T extends Comparable<T>>
      Parameters:
      appending - will be modified by appending child Terms

    • value

      public T value()
      Description copied from interface: Term
      If this term has a T value (not inside another wrapping Term), this returns that value. Otherwise, this returns null.
      Specified by:
      value in interface Term<T extends Comparable<T>>
      Returns:
      a T value not inside another wrapping Term, or null if this Term doesn't have a T value.

    • canonicalize

      public Term<T> canonicalize()
      Description copied from interface: Term
      Attempts to convert this Term and its children (recursively) to a single possible format for potentially many different internal representations. This mostly means things like Not(Not(Leaf("something"))) can be simplified to Leaf("something"), and chains of Any of Any of Any of... can be simplified to one Any with more items. The last case also works for All, but not One.
      Specified by:
      canonicalize in interface Term<T extends Comparable<T>>
      Returns:
      a unified formatting of the data this held, modifying this Term in place.

    • negate

      public Junction<T> negate()

    • equals

      public final boolean equals(Object o)
      Description copied from interface: Term
      Used primarily to check for equality between Terms, not to act like Term.match(Collection).
      Specified by:
      equals in interface Term<T extends Comparable<T>>
      Overrides:
      equals in class Object
      Parameters:
      o - another Object that must be a Term of the same class for this to be able to return true
      Returns:
      true if and only if o is a Term of the same class, and this Term is equivalent to o

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • match

      public boolean match(Collection<? extends T> coll)
      Description copied from interface: Term
      A predicate that checks if the given Collection of T satisfies this Term. Returns true if this Term matches the given Collection, or false otherwise.
      Specified by:
      match in interface Term<T extends Comparable<T>>
      Parameters:
      coll - a Collection of T that will not be modified
      Returns:
      true if coll matches, or false otherwise

    • remove

      public Collection<T> remove(Collection<T> coll)
      Description copied from interface: Term
      Modifies the given Collection of T by removing any items that match this Term. You can use negate() on an outer Junction to flip this to perform the converse operation to removing, filtering.
      Specified by:
      remove in interface Term<T extends Comparable<T>>
      Parameters:
      coll - a Collection of T that may be modified
      Returns:
      usually coll, after modifications

    • symbol

      public char symbol()
      Description copied from interface: Term
      Gets a single char constant that represents this Term and determines its comparison order in the event of a tie. Every Term class should return a different char from this method.
      Specified by:
      symbol in interface Term<T extends Comparable<T>>
      Returns:
      a char that represents this Term and is used to break ties in sorting.

    • name

      public String name()
      Description copied from interface: Term
      Gets a plain-English name, typically all lower-case and one word, that describes what operation this Term performs.
      Specified by:
      name in interface Term<T extends Comparable<T>>
      Returns:
      a typically lower-case single-word name describing what this Term does

    • toString

      public String toString()
      Description copied from interface: Term
      Slightly different from the normal toString() behavior, this may incorporate Term.name() but doesn't need to, and if it contains multiple parts, they should be separated by Term.symbol().
      Specified by:
      toString in interface Term<T extends Comparable<T>>
      Overrides:
      toString in class Object
      Returns:
      a String representation of this Term, or sometimes only its contents

    • compareTo

      public int compareTo(Term<T> o)
      Specified by:
      compareTo in interface Comparable<T extends Comparable<T>>

    • of

      public static <T extends Comparable<T>> Junction<T> of(T item)

    • parse

      public static Junction<String> parse(String text)
      Parses the String text into one Junction of String.
      Parameters:
      text - the String to parse
      Returns:
      the resulting Junction of String

    • parse

      public static Junction<String> parse(String text, int start, int end)
      Parses a substring of text into one Junction of String. The start is inclusive and the end is exclusive.
      Parameters:
      text - the String to parse
      start - the first index to read from, inclusive
      end - the last index to stop reading before, exclusive
      Returns:
      the resulting Junction of String

    • parse

      public static <T extends Comparable<T>> Junction<T> parse(com.github.tommyettinger.function.ObjToObjFunction<String,T> converter, String text)
      Parses all of text into one Junction of T, creating T items from String sections using converter.
      Parameters:
      converter - converts String sections to T values to put in the Junction; an enum's valueOf(String) can work
      text - the String to parse
      Returns:
      the resulting Junction of String

    • parse

      public static <T extends Comparable<T>> Junction<T> parse(com.github.tommyettinger.function.ObjToObjFunction<String,T> converter, String text, int start, int end)
      Parses a substring of text into one Junction of T, creating T items from String sections using converter. The start is inclusive and the end is exclusive.
      Parameters:
      converter - converts String sections to T values to put in the Junction; an enum's valueOf(String) can work
      text - the String to parse
      start - the first index to read from, inclusive
      end - the last index to stop reading before, exclusive
      Returns:
      the resulting Junction of String