001package Torello.Java.Function;
002
003/**
004 * Function-Pointer
005 * <SPAN CLASS=TJF>Input:</SPAN> {@code char}
006 * <SPAN CLASS=TJF>Output:</SPAN> {@code boolean}.
007 * 
008 * <BR /><BR />
009 * This is similar to Java's {@code IntPredicate}, except it explicity requires a {@code char}
010 * type in it's lambda {@code 'test'} method.
011 */
012@FunctionalInterface
013public interface CharPredicate
014{
015    /**
016     * Evaluates this predicate on the given argument.
017     * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
018     *
019     * @param c primitive-{@code char} (character) input argument.
020     * @return {@code TRUE} if the input argument matches this predicate, and <B>FALSE</B>
021     * otherwise.
022     */
023    public boolean test(char c);
024
025    /**
026     * <EMBED CLASS='external-html' DATA-FILE-ID=PRED_AND_METHOD>
027     * @param other A predicate that will be logically-AND'ed with this predicate
028     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PRED_AND_RETURN>
029     * @throws NullPointerException if parameter {@code 'other'} is null.
030     */
031    default CharPredicate and(CharPredicate other)
032    {
033        if (other == null)
034            throw new NullPointerException("null has been passed to parameter 'other'");
035
036        return (char c) -> this.test(c) && other.test(c);
037    }
038
039    /**
040     * <EMBED CLASS='external-html' DATA-FILE-ID=PRED_NEGATE_METHOD>
041     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PRED_NEGATE_RETURN>
042     */
043    default CharPredicate negate()
044    { return (char c) -> ! this.test(c); }
045
046    /**
047     * <EMBED CLASS='external-html' DATA-FILE-ID=PRED_OR_METHOD>
048     * @param other a predicate that will be logically-ORed with this predicate
049     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PRED_OR_RETURN>
050     * @throws NullPointerException if parameter {@code 'other'} is null.
051     */
052    default CharPredicate or(CharPredicate other)
053    {
054        if (other == null)
055            throw new NullPointerException("null has been passed to parameter 'other'");
056
057        return (char c) -> this.test(c) || other.test(c);
058    }
059}