package Torello.Java;

import Torello.Java.StrFilter;

import java.util.function.Predicate;
import java.util.Iterator;

/**
 * A simple functional-interface (lambda) for filtering lists of <CODE>FileNode</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=FILENODE_FILTER>
 * 
 * @see StrFilter
 */
@FunctionalInterface
public interface FileNodeFilter extends Predicate<FileNode>, java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDFI>  */
    public static final long serialVersionUID = 1;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
     *
     * @param fn Any file node
     *
     * @return A {@code TRUE} value should mean that the {@code FileNode} has passed the test
     * (will be kept / retained).  A return value of {@code FALSE} should indicate that the
     * {@code FileNode} needs to be filtered.
     */
    public boolean test(FileNode fn);

    /**
     * Standard Java-{@code Predicate}, Java Functional-Interface AND routine.
     *
     * <BR /><BR />Logically AND's <B>{@code 'this'}</B> {@code FileNodeFilter} with the filter
     * parameter <B>{@code 'other'}</B>
     *
     * @param other A 2nd {@code FileNodeFilter} with which <B>{@code 'this'}</B> filter may be
     * AND'ed.
     *
     * @return A new {@code FileNodeFilter} that is the logical-and of <B>{@code 'this'}</B> filter
     * and <B>{@code 'other'}</B>
     */
    default FileNodeFilter and(FileNodeFilter other)
    {
        // FAIL-FAST: Check that the lambda will not throw a null pointer exception prior to
        // creating the lambda.

        if (other == null) throw new NullPointerException
            ("The parameter 'other' to FileNodeFilter.and(other) was null.");

        return (FileNode f) -> this.test(f) && other.test(f);
    }

    /**
     * Standard Java-{@code Predicate}, Java Functional-Interface OR routine.
     *
     * <BR /><BR />Logically OR's <B>{@code 'this'}</B> {@code FileNodeFilter} with the filter
     * parameter <B>{@code 'other'}</B>
     *
     * @param other A 2nd {@code FileNodeFilter} with which <B>{@code 'this'}</B> filter may be
     * or'ed.
     *
     * @return A new FileNodeFilter that is the logical-or of <B>{@code 'this'}</B> filter and
     * <B>"other"</B>
     */
    default FileNodeFilter or(FileNodeFilter other)
    {
        // FAIL-FAST: Check that the lambda will not throw a null pointer exception prior to
        // creating the lambda.

        if (other == null) throw new NullPointerException
            ("The parameter 'other' to FileNodeFilter.or(other) was null..");

        return (FileNode f) -> this.test(f) || other.test(f);
    }

    /**
     * Standard Java-{@code Predicate}, Java Functional-Interface NEGATE routine.
     *
     * <BR /><BR />Generates 's a {@code FileNodeFilter} that is the "logical-not" of
     * <B>{@code 'this'}</B> filter.
     *
     * @return A new {@code FileNodeFilter} that would return {@code TRUE} whenever
     * <B>{@code 'this'}</B> would return {@code FALSE}, and vice-versa.
     */
    default FileNodeFilter negate() { return (FileNode f) -> ! this.test(f); }

    /**
     * This is similar to the java streams function {@code filter(Predicate<>)}.  Elements that do
     * not meet the criteria specified by this {@code FileNodeFilter} - <I>specifically, if an
     * element of the input-parameter {@code 'urlList'} would evaluate to {@code FALSE}</I> - then
     * that element shall be removed from the list.
     *
     * @param fileNodes An {@code Iterable} of {@code FileNode's} which the user would like
     * filtered using {@code 'this'} filter.
     *
     * @return The number of elements that were removed from parameter {@code 'fileNodes'} based on
     * the results of the {@code 'test(FileNode)'} lambda-method {@code FileNodeFilter.test()} of
     * {@code 'this'} instance.
     */
    public default int filter(Iterable<FileNode> fileNodes)
    {
        int                 removeCount = 0;
        Iterator<FileNode>  iter        = fileNodes.iterator();

        // If the filter test returns FALSE, then remove the URL from the collection.
        // Increment the removeCount Counter.

        while (iter.hasNext()) if (! test(iter.next())) { removeCount++; iter.remove(); }

        return removeCount;
    }

    /**
     * This wraps a {@code StrFilter} inside of a {@code FileNodeFilter}.  The
     * {@code String}-comparison that is performed will use the full-path-name of the
     * {@code FileNode}.
     *
     * @param sf This is a "String Predicate" that has (usually, but not required) been built by
     * one of the many {@code String}-Filter Factory-Build static-methods of
     * {@code class StrFilter}.  The Predicate's that are constructed via the build methods of
     * {@code StrFilter} call the {@code Object.toString()} method on the objects they receive for
     * testing.
     *
     * @return FileNodeFilter This will return an instance of a {@code FileNodeFilter} that will
     * test the full-path-name as a {@code String}.
     *
     * @see StrFilter
     */ 
    public static FileNodeFilter fromStrFilter(StrFilter sf)
    {
        if (sf == null) throw new NullPointerException(
            "The String-Filter Predicate Parameter 'sf' in static-factory builder method " +
            "'fromStrFilter' was passed a null value."
        );

        return (FileNode fn) -> sf.test(fn);
    }
}