Package Torello.Java

Interface StrFilter

  • All Superinterfaces:
    java.util.function.Predicate<java.lang.Object>, java.io.Serializable
    Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
    @FunctionalInterface
public interface StrFilter
extends java.io.Serializable, java.util.function.Predicate<java.lang.Object>
    A simple functional-interface that provides many 'builder' methods for creating standard Java Predicate's that operate on an Object's 'toString' method.

    When Java was written, the concept of a "Memory Address" was eliminated, in its entirety, from the scope and range of the code that is written in Java. Java has many similarities to C and C++, but when it comes to memory-addresses, the diverge greatly. Java is a 'garbage collected language' and that means the internal JRE worries about deallocating objects that are no longer in use. In C, this was half of the work a programmer had to do. The biggest benefit of the garbage-collected aspect is the ability to work with 'immutable strings' in a way that the programmer has to think very little about irrelevant concepts like memory-leaks and invalid pointer references. In fact, the entire HTML-Search Package in this jar file would have been 100 times more difficult with the 'immutable' aspect of the java-string. All of the HTML node classes in this package are mostly just wrappers around java-strings.

    This class is designed to make it easier to perform 'filter-operations' on a collections of java-strings. This class is an extremely 'general-purpose' class, and it can be used with any object whose toString() method is fully functioning, and returns something significant about the object. There are two primary classes in this library that utilize this class 'StrFilter'

    • interface FileNodeFilter facilitates using instances of 'StrFilter' with a static-factory method provided in its interface
    • interface URLFilter also provides a static-factory wrapper/builder in its interface. The class URLFilter treats URL's as String's for the purposes of filtering URL's, and makes this class StrFilter an invaluable too.


    REDUNDANT-CODE NOTE: The features and functions provided by class StrFilter might appear to be 'eerily' similar to the functions in class TextComparitor (to the astute programmer). The primary impetus for having both is that the TextComparitor does not wrap it's (input) comparison-strings inside the predicate test. The ability to separate the "Comparison Type" from the "Comparing String Data" is extremely important for syntactical reasons involving where and how the class TextComparitor is used.

    This class, class StrFilter, is often passed as a constructor to more complicated predicates, like class URLFilter. On the other hand, the NodeSearch package uses TextComparitor's in just about every one of it's search routines. And great care is taken to ensure that both the compare-operation, and the compare-data are kept together through-out the package. In the case of TextComparitor , running the constructor as often as would be required to use this library has forced this situation.

    In any case, it is OK that TextComparitor does not "wrap" the strings against which the values are being compared, while the intended uses of StrFilter require that the compare-strings are included in the predicate body. Of course this means that the StrFilter constructor (static factory methods) are used much more often. TextComparitor doesn't have any factory build methods at all. Note, even that a StrFilter can be constructed / built using a TextComparitor as input. However, the opposite scenario - building a TextComparitor using an StrFilter - would not be a useful feature. The purpose in explaining this is to hopefully show what StrFilter does, and its similarities to TextComparitor (which is a class that has copious amounts of documentation already).


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 
        static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Functional Interfaces are usually not thought of as Data Objects that need to be saved, stored and retrieved; however, having the ability to store intermediate results along with the lambda-functions that helped get those results can make debugging easier.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

    • Method Detail

      • test

        🡅  🡇  ⇈  ⮫ 
        boolean test​(java.lang.Object o)
        FUNCTIONAL-INTERFACE BOOLEAN METHOD: This is the method that fulfils this functional-interface 'test' method.

        This method will receive a java.lang.Object. This Object must have implemented its toString() method The purpose of this method is to provide an easy means to filter certain String's (automatically).

        PRECISE NOTE: This method should return FALSE if the passed String should be skipped. A return value of TRUE implies that the String is not to be ignored or passed over, but rather 'kept.'

        NOTE: This behavior is compatible with the Java Stream's method "filter(Predicate<...>)".
        Specified by:
        test in interface java.util.function.Predicate<java.lang.Object>
        Parameters:
        o - This is the Object that will be tested. If it passes the test, then this method must return TRUE which would imply that the object shall not be filtered. If the object fails the test, this method should return FALSE, and the object shall not be included in the result set as it has failed the test.
        Returns:
        When implementing this method, returning TRUE must mean that the Object has passed the filter's test-requirements (and will subsequently be retained by whatever function is carrying out the filter operation).

      • castToStrPred

        🡅  🡇  ⇈  ⮫ 
        default java.util.function.Predicate<java.lang.String> castToStrPred()
        Java is not perfect. This method is fine: since String inherits Object, and the interface Predicate does not have any write-dependencies.

        Erasure is like this with interface Predicate - because that's how it works with all of the generics. A Vector<Object> cannot be passed to a Vector<String> parameter (because a person might need to use the String's). But a Predicate<Object> can not have problems being passed to a Predicate<String>...
        Returns:
        'this' StrFilter cast into a Predicate<String>
        Code:
        Exact Method Body:
         Predicate p = this;
 return (Predicate<String>) p;

      • strListKEEP

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListKEEP​(boolean ignoreCase,
                             java.lang.String... strList)
        Convenience Method
        Invokes: strListKEEP(Iterator, boolean)
        Converts: String[] VarArgs to Iterator<String>
        Code:
        Exact Method Body:
         return strListKEEP(Arrays.asList(strList).iterator(), ignoreCase);

      • strListKEEP

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListKEEP​(java.lang.String strListFileName,
                             boolean ignoreCase)
                      throws java.io.IOException
        Convenience Method
        Invokes: strListKEEP(Iterator, boolean)
        Loads: 'strListFileName' from disk to an Iterator<String>
        Code:
        Exact Method Body:
         return strListKEEP(FileRW.loadFileToVector(strListFileName, false).iterator(), ignoreCase);

      • strListKEEP_NOIOE

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListKEEP_NOIOE​(java.lang.String strListFileName,
                                   boolean ignoreCase)
        Convenience Method
        Invokes: strListKEEP(Iterator, boolean)
        Loads: 'strListFileName' from disk to an Iterator<String>
        Catches Exception, and Fails Fast - (See LFEC)
        Code:
        Exact Method Body:
         return strListKEEP(LFEC.loadFileToVector(strListFileName, false).iterator(), ignoreCase);

      • strListKEEP

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListKEEP​(java.util.Iterator<java.lang.String> strList,
                             boolean ignoreCase)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, an input-object's toString() result is compared against the String's contained in 'strList' - which would also be called an input-String 'white-list.'
        Parameters:
        strList - A list of String's to be used as a 'comparison set' against an input-String in a Predicate-test.
        ignoreCase - When this is TRUE all equality-comparisons performed in the String's tested will ignore case-sensitivity.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to each of the String's in the input-parameter 'strList'
        Code:
        Exact Method Body:
         // Build a TreeSet<String>, this will be used, internally, in the instance of 'StrFilter'
 // (a Predicate<Object>) that is returned by this factory-builder method.
 // 
 // Experienced Java users: TreeSet is a very convenient and easy-to-use "sorted list"
 // implementation that stores strings, in sorted order, in a binary-tree.  This makes
 // looking them up as efficient as possible.
 final TreeSet<String> ts = new TreeSet<>();

 // When building this sorted-list (TreeSet), if we are ignoring case (and-only-if), then
 // we must convert the strings contained by the input parameter string-list 'strList' to
 // lower-case first.
 if (ignoreCase) while (strList.hasNext()) ts.add(strList.next().toLowerCase());
 else            while (strList.hasNext()) ts.add(strList.next());

 // The returned Predicate<Object> must call '.toString()' on it's object-input before
 // checking the "Sorted-List" (TreeSet<String>) to see if it contains the string.  If a
 // case-insensitive predicate was requested, then we must build a Predicate that invokes
 // BOTH 'toString()' AND THEN invokes 'toLowerCase()' on the input Object.
 if (ignoreCase) return (Object o) -> ts.contains(o.toString().toLowerCase());
 else            return (Object o) -> ts.contains(o.toString());

      • strListREJECT

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListREJECT​(java.lang.String strListFileName,
                               boolean ignoreCase)
                        throws java.io.IOException
        Convenience Method
        Invokes: strListREJECT(Iterator, boolean)
        Loads: 'strListFileName' from disk to an Iterator<String>
        Code:
        Exact Method Body:
         return strListREJECT(FileRW.loadFileToVector(strListFileName, false).iterator(), ignoreCase);

      • strListREJECT_NOIOE

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListREJECT_NOIOE​(java.lang.String strListFileName,
                                     boolean ignoreCase)
        Convenience Method
        Invokes: strListREJECT(Iterator, boolean)
        Loads: 'strListFileName' from disk to an Iterator<String>
        Catches Exception, and Fails Fast - (See LFEC)
        Code:
        Exact Method Body:
         return strListREJECT(LFEC.loadFileToVector(strListFileName, false).iterator(), ignoreCase);

      • strListREJECT

        🡅  🡇  ⇈  ⮫ 
        static StrFilter strListREJECT​
            (java.util.Iterator<java.lang.String> strList,
             boolean ignoreCase)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, an input-object's toString() result is compared against the String's contained in 'strList' - which would also be called an input-String 'black-list.'
        Parameters:
        strList - A list of String's to be used as a 'comparison set' against an input-String in a Predicate-test.
        ignoreCase - When this is TRUE all equality-comparisons performed in the String's tested will ignore case-sensitivity.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to each of the String's in the input-parameter 'strList'.
        Code:
        Exact Method Body:
         // Build a TreeSet<String>, this will be used, internally, in the instance of 'StrFilter'
 // (a Predicate<Object>) that is returned by this factory-builder method.
 // 
 // Experienced Java users: TreeSet is a very convenient and easy-to-use "sorted list"
 // implementation that stores strings, in sorted order, in a binary-tree.  This makes
 // looking them up as efficient as possible.
 final TreeSet<String> ts = new TreeSet<>();

 // When building this sorted-list (TreeSet), if we are ignoring case (and-only-if), then
 // we must convert the strings contained by the input parameter string-list 'strList' to
 // lower-case first.
 if (ignoreCase) while (strList.hasNext()) ts.add(strList.next().toLowerCase());
 else            while (strList.hasNext()) ts.add(strList.next());

 // The returned Predicate<Object> must call '.toString()' on it's object-input before
 // checking the "Sorted-List" (TreeSet<String>) to see if it contains the string.  If a
 // case-insensitive predicate was requested, then we must build a Predicate that invokes
 // BOTH 'toString()' AND THEN invokes 'toLowerCase()' on the input Object.
 if (ignoreCase) return (Object o) -> ! ts.contains(o.toString().toLowerCase());
 else            return (Object o) -> ! ts.contains(o.toString());

      • regExKEEP

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExKEEP​(java.util.regex.Pattern regEx,
                           boolean regExMustMatchEntireString)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, an input-object's toString() result is checked against Java's Regular-Expression matcher. The Predicate generated will choose to KEEP input-Object's by returning TRUE when the Regular-Expression matches the Object.toString() results.
        Parameters:
        regEx - A regular-expression used to compare against an input-Object (using Object.toString() in a Predicate-test.
        regExMustMatchEntireString - When this parameter is passed TRUE, then the regular-expression Pattern must match the entire input Object.toString() . When this parameter is passed FALSE, it only need match some portion or part of the input-parameter String in the Predicate-test that is being generated.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regEx'
        Code:
        Exact Method Body:
         // FAIL-FAST: Perform this test BEFORE building the regex, to save the programmer
 // from later on (when using this factory generated predicate) having a
 // NullPointerException that is more difficult to isolate.
 if (regEx == null) throw new NullPointerException(
     "The Regular-Expression provided to the 'regEx' parameter of this static-factory-builder" +
     "method, 'regExKEEP,' was null."
 );

 if (regExMustMatchEntireString)
 {
     // the java.util.regex.Pattern.asPredicate() method produces a predicate that must
     // match an entire input string.  This would be identical (if it were possible) to insert
     // a '^' at the beginning of the regex, and an '$' at the end.
     final Predicate<String> p = regEx.asPredicate();
     return (Object o) -> p.test(o.toString());
 }
 else
     return (Object o) -> regEx.matcher(o.toString()).find();

      • regExREJECT

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExREJECT​(java.util.regex.Pattern regEx,
                             boolean regExMustMatchEntireString)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, an input-object's toString() result is checked against Java's Regular-Expression matcher. The Predicate generated will choose to REJECT input-Object's by returning FALSE when the Regular-Expression matches the Object.toString() results.
        Parameters:
        regEx - A regular-expression used to compare against an input-Object (using Object.toString() in a Predicate-test.
        regExMustMatchEntireString - When this parameter is passed TRUE, then the regular-expression Pattern must match the entire input Object.toString() . When this parameter is passed FALSE, it only need match some portion or part of the input-parameter String in the Predicate-test that is being generated.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regEx'
        Code:
        Exact Method Body:
         // FAIL-FAST: Perform this test BEFORE building the regex, to save the programmer
 // from later on (when using this factory generated predicate) having a
 // NullPointerException that is more difficult to isolate.
 if (regEx == null) throw new NullPointerException(
     "The Regular-Expression provided to the 'regEx' parameter of this static-factory-builder" +
     "method, 'regExREJECT,' was null."
 );

 if (regExMustMatchEntireString)
 {
     // the java.util.regex.Pattern.asPredicate() method produces a predicate that must
     // match an entire input string.  This would be identical (if it were possible) to insert
     // a '^' at the beginning of the regex, and an '$' at the end.
     final Predicate<String> p = regEx.asPredicate().negate();
     return (Object o) -> ! p.test(o.toString());
 }
 else
     return (Object o) -> ! regEx.matcher(o.toString()).find();

      • regExsAND

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExsAND​(java.util.regex.Pattern... regExs)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, a list of regular-expressions may be passed for input match-criteria. The Predicate that is created by this factory-method will have a test() method that returns TRUE if an input object's Object.toString() output matches each-and-every-one of the provided regular-expressions.
        Parameters:
        regExs - A list of regular-expressions to match against an input-String.

        NOTE: The regular-expression will be considered to match an input Object.toString() result, even if it only matches some part of the input String - which is the standard behaviour for Regular-Expressions. If the user wishes to find "Complete Matches" - then attempting to use multiple regular-expressions on the same input String is actually somewhat meaningless.

        If such comparison-behaviour is required, use the tried-and-true Regular-Ex '^' and '$' operators.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regExs'
        Code:
        Exact Method Body:
         // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 for (Pattern regEx : regExs) if (regEx == null) throw new NullPointerException
     ("One or more of the elements passed to static-factory method 'regexsAND' are null.");

 // This over-comes a minor "possible complication" - without likely causing much
 // inefficiency.  If a RegEx[] were passed (array, not a '...' list) and that array were
 // changed after building this Predicate, the Predicate's behavior would fail.
 // Avoid this (unlikely, but possible) problem by copying the array, and returning a 
 // predicate that stores a different  array pointer (because it is to a different array)
 // inside the Predicate's body.
 final Pattern[] pArr = regExs.clone();

 // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 if (pArr.length == 0) throw new IllegalArgumentException(
     "This static-factory method 'regExsAND' has been invoked with zero-arguments to the" +
     "'regExs' var-args parameter."
 );

 return (Object o) ->
 {
     String s=o.toString();

     // Cycle the Regular-Expressions.  "AND" means if even one fails, return FALSE immediately.
     for (Pattern p : pArr) if (! p.matcher(s).find()) return false;

     // None of them failed, return TRUE.
     return true;
 };

      • regExsOR

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExsOR​(java.util.regex.Pattern... regExs)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, a list of regular-expressions may be passed for input match-criteria. The Predicate that is created by this factory-method will have a test() method that returns TRUE if an input object's Object.toString() output matches any-one-of the provided regular-expressions.
        Parameters:
        regExs - A list of regular-expressions to match against an input-String.

        NOTE: The regular-expression will be considered to match an input Object.toString() result, even if it only matches some part of the input String - which is the standard behaviour for Regular-Expressions. If the user wishes to find "Complete Matches" - then attempting to use multiple regular-expressions on the same input String is actually somewhat meaningless.

        If such comparison-behaviour is required, use the tried-and-true Regular-Ex '^' and '$' operators.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regExs'
        Code:
        Exact Method Body:
         // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once the lambda-predicate is invoked.
 for (Pattern regEx : regExs) if (regEx == null) throw new NullPointerException
         ("One or more of the elements passed to static-factory method 'regExsOR' are null.");

 // This over-comes a minor "possible complication" - without likely causing much
 // inefficiency.  If a RegEx[] were passed (array, not a '...' list) and that array were
 // changed after building this Predicate, the Predicate's behavior would fail.
 // Avoid this (unlikely, but possible) problem by copying the array, and returning a 
 // predicate that stores a different  array pointer (because it is to a different array)
 // inside the Predicate's body.
 final Pattern[] pArr = regExs.clone();

 // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 if (pArr.length == 0) throw new IllegalArgumentException(
     "This static-factory method 'regExsOR' has been invoked with zero-arguments to the" +
     "'regExs' var-args parameter."
 );

 return (Object o) ->
 {
     String s = o.toString();

     // Cycle the Regular-Expressions.  "OR" means if even one succeeds, return TRUE immediately.
     for (Pattern p : pArr) if (p.matcher(s).find()) return true;

     // None succeeded, so return FALSE.
     return false;
 };

      • regExsNAND

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExsNAND​(java.util.regex.Pattern... regExs)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, a list of regular-expressions may be passed for input match-criteria. The Predicate that is created by this factory-method will have a test() method that returns TRUE if an input object's Object.toString() output does-not-match-any of the provided regular-expressions.
        Parameters:
        regExs - A list of regular-expressions to match against an input-String.

        NOTE: The regular-expression will be considered to match an input Object.toString() result, even if it only matches some part of the input String - which is the standard behaviour for Regular-Expressions. If the user wishes to find "Complete Matches" - then attempting to use multiple regular-expressions on the same input String is actually somewhat meaningless.

        If such comparison-behaviour is required, use the tried-and-true Regular-Ex '^' and '$' operators.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regExs'.
        Code:
        Exact Method Body:
         // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once the
 // lambda-predicate is invoked.
 for (Pattern regEx : regExs) if (regEx == null) throw new NullPointerException
         ("One or more of the elements passed to static-factory method 'regExsNAND' are null.");

 // This over-comes a minor "possible complication" - without likely causing much
 // inefficiency.  If a RegEx[] were passed (array, not a '...' list) and that array were
 // changed after building this Predicate, the Predicate's behavior would fail.
 // Avoid this (unlikely, but possible) problem by copying the array, and returning a 
 // predicate that stores a different  array pointer (because it is to a different array)
 // inside the Predicate's body.
 final Pattern[] pArr = regExs.clone();

 // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 if (pArr.length == 0) throw new IllegalArgumentException(
     "This static-factory method 'regExsNAND' has been invoked with zero-arguments to the" +
     "'regExs' var-args parameter."
 );

 return (Object o) ->
 {
     String s = o.toString();

     // Cycle the Regular-Expressions.  "NAND" means if even one succeeds, return FALSE immediately.
     for (Pattern p : pArr) if (p.matcher(s).find()) return false;

     // All regex's failed, so return TRUE
     return true;
 };

      • regExsXOR

        🡅  🡇  ⇈  ⮫ 
        static StrFilter regExsXOR​(java.util.regex.Pattern... regExs)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed.

        Here, a list of regular-expressions may be passed for input match-criteria. The Predicate that is created by this factory-method will have a test() method that returns TRUE if an input object's Object.toString() output matches precisely-one-of the provided regular-expressions.
        Parameters:
        regExs - A list of regular-expressions to match against an input-String.

        NOTE: The regular-expression will be considered to match an input Object.toString() result, even if it only matches some part of the input String - which is the standard behaviour for Regular-Expressions. If the user wishes to find "Complete Matches" - then attempting to use multiple regular-expressions on the same input String is actually somewhat meaningless.

        If such comparison-behaviour is required, use the tried-and-true Regular-Ex '^' and '$' operators.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameter 'regExs'
        Code:
        Exact Method Body:
         // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once the
 // lambda-predicate is invoked.
 for (Pattern regEx : regExs) if (regEx == null) throw new NullPointerException
         ("One or more of the elements passed to static-factory method 'regExsXOR' are null.");

 // This over-comes a minor "possible complication" - without likely causing much
 // inefficiency.  If a RegEx[] were passed (array, not a '...' list) and that array were
 // changed after building this Predicate, the Predicate's behavior would fail.
 // Avoid this (unlikely, but possible) problem by copying the array, and returning a 
 // predicate that stores a different  array pointer (because it is to a different array)
 // inside the Predicate's body.
 final Pattern[] pArr = regExs.clone();

 // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 if (pArr.length == 0) throw new IllegalArgumentException(
     "This static-factory method 'regExsXOR' has been invoked with zero-arguments to the" +
     "'regExs' var-args parameter."
 );

 return (Object o) ->
 {
     String  s       = o.toString();
     int     count   = 0;

     // Cycle the Regular-Expressions.  Because this is "XOR" - we must keep a count.
     // If that count is > 1, we have to return FALSE immediately.
     for (Pattern p : pArr) if (p.matcher(s).find()) { if (++count > 1) return false; }

     // If there was precisely one match, return TRUE, otherwise return FALSE.
     return count == 1;
 };

      • comparitor

        🡅  🡇  ⇈  ⮫ 
        static StrFilter comparitor​(TextComparitor tc,
                            java.lang.String... compareStrs)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed. Here, the class TextComparitor is reused from the 'NodeSearch' package. Please review how each of the pre-defined, static-instances of class TextComparitor operate when presented with String-input.

        Example:
         StrFilter filter = StrFilter.comparitor
     (TextComparitor.DOES_NOT_START_WITH, "Today in Washington,");
 // The above fiter would REJECT any input Object whose 'toString()' method returned a 
 // String that began with the words "Today in Washington,"
 
 StrFilter filter2 = StrFilter.comparitor
     (TextComparitor.CONTAINS_CASE_INSENSITIVE, "Highway 61 Revisited");
 // This filter would KEEP / RETAIN any input Object whose 'toString()' method returned a
 // String that contained the words "Highway 61 Revisited".  This comparison to be performed
 // would be case-insensitive.
        Parameters:
        tc - This is an instance of the class TextComparitor, which is defined in the NodeSearch package.
        compareStrs - These must be the comparison-String's used by class 'TextComparitor' for performing the comparisons.
        Returns:
        A new StrFilter that can be used to test and filter String's, according to the input-parameters 'tc' and 'compareStrs'
        See Also:
        TextComparitor
        Code:
        Exact Method Body:
         // FAIL-FAST: Check that the user-provided-parameters would not cause exceptions once
 // the lambda-predicate is invoked.
 if (tc == null) throw new NullPointerException
     ("A null TextComparitor has been passed to static-factory method 'comparitorKeep'");

 TCCompareStrException.check(compareStrs);

 final String[] cmpStrs = compareStrs.clone();
     // Mostly, this is over-board, but it doesn't slow anything down much, and it
     // it does force users to think about Object-References and Parameter-Argument
     // Marshaling.

 // Builds (and returns) a Predicate<Object> that re-uses the TextComparitor's
 // 'test(String, String...)' method.
 return (Object o) -> tc.test(o.toString(), cmpStrs);

      • isEqualKEEP

        🡅  🡇  ⇈  ⮫ 
        static StrFilter isEqualKEEP​(java.lang.String s,
                             boolean ignoreCase)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed. Here, a single String is used as input. The Predicate that is created by this factory-method will have a test() method that returns TRUE only if the an input object's 'toString()' output equals the the input-parameter String 's'.
        Parameters:
        s - This is a String which will be used to test for equality in the generated Predicate.test(Object)
        ignoreCase - When this is TRUE, the equality-test will ignore case when performing its comparisons.
        Returns:
        A new StrFilter that can be used to test and filter Object's via the Object.toString() method, and the input-parameter 's'
        Code:
        Exact Method Body:
         if (s == null) throw new NullPointerException
     ("A null String has been passed to parameter 's' of static-factory method 'isEqualKEEP'.");

 // Builds & returns a predicate based on the whether or not 'ignoreCase' is true or false.
 return ignoreCase
     ? (Object o) -> o.toString().equalsIgnoreCase(s)
     : (Object o) -> o.toString().equals(s);

      • isEqualREJECT

        🡅  ⇈  ⮫ 
        static StrFilter isEqualREJECT​(java.lang.String s,
                               boolean ignoreCase)
        This is a static-factory generator method. It helps the programmer automatically build an instance of this FunctionalInterface 'StrFilter' for one of the most common uses/tasks where a String-Filter Predicate would be needed. Here, a single String is used as input. The Predicate that is created by this factory-method will have a test() method that returns TRUE only if an input Object's Object.toString() output does-not-equal the the input-parameter String 's'.
        Parameters:
        s - This is a String which will be used to test for equality in the generated Predicate.test(Object).
        ignoreCase - When this is TRUE, the equality-test will ignore case when performing its comparisons.
        Returns:
        A new StrFilter that can be used to test and filter Object's via the Object.toString() method, and the input-parameter 's'
        Code:
        Exact Method Body:
         if (s == null) throw new NullPointerException
     ("A null String has been passed to parameter 's' of static-factory method 'isEqualREJECT'.");

 // Builds & returns a predicate based on the whether or not 'ignoreCase' is true or false.
 return ignoreCase
     ? (Object o) -> ! o.toString().equalsIgnoreCase(s)
     : (Object o) -> ! o.toString().equals(s);