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 entirety, from all code written in Java. Java is a Garbage-Collected Language, and one of the most salient benefits of this is the ability to work with 'immutable strings' - such that the programmer has to worry very little about memory leaks and invalid pointer references!

    The entire Java-HTML Search Package is based on the 'immutable' aspect of a Java-String. All of the HTMLNode classes in this package are just wrappers around Java String's.

    This class is designed to make it easier to perform 'filter-operations' on a set of String's of java-strings. This is extremely simple, and may be used with any POJO that has a working toString() method. In fact, both the interface FileNodeFilter and the interface URLFilter will accept a 'StrFilter' as a Constructor-Initializer.


    • 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)
        FunctionalInterface Target-Method:
        This method corresponds to the @FunctionalInterface Annotation's method requirement. It is the only non-default, non-static method in this interface, and may be the target of a Lambda-Expression or '::' (double-colon) Function-Pointer.

        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).

        Standard Filter Behavior:
        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.'

        This behavior is consisten with the Java Stream's method Stream.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​(java.lang.String strListFileName,
                             boolean ignoreCase)
                      throws java.io.IOException
        Convenience Method
        Invokes: strListKEEP(Iterator, boolean)
        Loads: 'strListFileName' from disk to an Iterator<String>
        Ignores: Any blank-lines or lines that begin with the '#' character.
        Code:
        Exact Method Body:
         return strListKEEP(
     FileRW
         .loadFileToStream(strListFileName, false)
         .filter((String line) -> ! StringParse.onlyWhiteSpace_OrZeroLen.test(line))
         .filter((String line) -> line.charAt(0) != '#')
         .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>
        Ignores: Any blank-lines or lines that begin with the '#' character.
        Catches Exception, and Fails Fast - (See LFEC)
        Code:
        Exact Method Body:
         return strListKEEP(
     LFEC
         .loadFileToStream(strListFileName, false)
         .filter((String line) -> ! StringParse.onlyWhiteSpace_OrZeroLen.test(line))
         .filter((String line) -> line.charAt(0) != '#')
         .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 a 'StrFilter' for some of the most common uses/tasks in which 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

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 a 'StrFilter' for some of the most common uses/tasks in which 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 a 'StrFilter' for some of the most common uses/tasks in which 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 a 'StrFilter' for some of the most common uses/tasks in which 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 a 'StrFilter' for some of the most common uses/tasks in which 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.

        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 a 'StrFilter' for some of the most common uses/tasks in which 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.

        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 a 'StrFilter' for some of the most common uses/tasks in which 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.

        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 a 'StrFilter' for some of the most common uses/tasks in which 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.

        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 a 'StrFilter' for some of the most common uses/tasks in which 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);

 // Mostly, this is over-board, but it doesn't slow anything down much, and it does force
 // users to think about Object-References and Parameter-Argument Marshaling.

 final String[] cmpStrs = compareStrs.clone();

 // 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 a 'StrFilter' for some of the most common uses/tasks in which 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 a 'StrFilter' for some of the most common uses/tasks in which 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);